@tileflow/core 0.1.0-alpha.14 → 0.1.0-alpha.17

package/README.md

@@ -42,18 +42,31 @@ export default defineTileflow({
       },
       typography: {
         font: 'Inter',
+        roads: {weight: 'bold'},
       },
     },
   },
   maps: {
     madrid: {
-      basemap: osm(),
+      basemap: osm({version: '2026-06-07'}),
       icons: 'brand',
       theme: 'light',
       modules: [
-        labels({roads: 'major'}),
-        poi({categories: ['food', 'coffee', 'culture', 'transit'], icons: 'essential'}),
-        roads({detail: 'streets', hierarchy: 'clear', outline: 'subtle', weight: 'regular'}),
+        labels({roads: 'major', roadClasses: ['motorway', 'trunk', 'primary']}),
+        poi({
+          categories: ['food', 'coffee', 'culture', 'transit'],
+          color: 'category',
+          density: 'balanced',
+          icons: 'essential',
+        }),
+        roads({
+          detail: 'streets',
+          hierarchy: 'clear',
+          oneWayMarkers: true,
+          outline: 'subtle',
+          weight: 'regular',
+          widthScale: {motorway: 1.15, minor: 0.9},
+        }),
       ],
       layers: {
         'highway-primary': {
@@ -71,6 +84,43 @@ export default defineTileflow({
 });
 ```
 
+## Capture scenes
+
+Commit named visual scenes beside the maps they exercise. Scenes are strict, bounded test inputs;
+they do not change style or manifest identity.
+
+```ts
+export default defineTileflow({
+  maps: {
+    madrid: {basemap: osm(), theme: 'light'},
+  },
+  scenes: {
+    'madrid-desktop': {
+      map: 'madrid',
+      camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
+      viewport: {width: 1280, height: 800, dpr: 1},
+    },
+    'madrid-product': {
+      map: 'madrid',
+      camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
+      viewport: {width: 390, height: 844, dpr: 2},
+      target: {
+        kind: 'application',
+        path: '/maps/madrid',
+        captureId: 'product-map',
+      },
+    },
+  },
+});
+```
+
+The default target renders autonomously with no server. An application target uses the app's
+normal loopback development server and selects exactly one wrapper by `captureId`, explicit
+selector, or map name. Cameras accept `center` or `bounds`; viewports are 64–4096 CSS pixels at DPR
+1 or 2 within the public physical-pixel budget. Standalone capture applies the camera; an
+application route must render it itself because capture does not mutate application component
+state. Use `tileflow capture <scene>` or the `@tileflow/capture` Node package to render them.
+
 ## Style contract
 
 Tileflow keeps these levels separate:
@@ -80,6 +130,8 @@ Tileflow keeps these levels separate:
 - `theme.modules.<name>` contains advanced, module-specific tokens. These are granular: setting `theme.modules.roads.rail` does not recolor primary roads.
 - `maps.<name>.icons` can point at a reusable root icon set, a hosted MapLibre sprite URL, or a local icon folder for Vite/build output.
 - `maps.<name>.modules` enables semantic behavior such as `labels()`, `poi()`, and `roads()`. Road colors remain in `theme.modules.roads`; `roads()` controls detail, hierarchy, weight, outline, and optional transport extras.
+- `typography` sets a global font/weight and optional `places`, `roads`, `water`, and `poi` overrides. The hosted Noto Sans endpoint guarantees `regular` and `bold`; custom glyph endpoints may provide the other typed weights.
+- `buildingStyle` controls generated building fill opacity, outline opacity/width, and a height threshold that selects the theme's low/high-rise colors. Generated landuse and landcover layers consume their corresponding module colors.
 - `maps.<name>.renderer` can be `auto`, `osm-bright`, or `generated`. `auto` preserves the default template when compatible; `generated` always uses Tileflow's generated layers; `osm-bright` throws if the map config cannot be rendered with the template.
 - `layers` is the raw MapLibre escape hatch for exact layer patches.
 
@@ -95,6 +147,8 @@ roads({
   hierarchy: 'strong',
   weight: 'regular',
   outline: 'strong',
+  oneWayMarkers: true,
+  widthScale: {motorway: 1.15, primary: 1.05, minor: 0.9},
   extras: {
     paths: false,
     rail: false,
@@ -108,6 +162,8 @@ roads({
 adds service roads and tracks. `hierarchy` accepts `subtle`, `clear`, or `strong`; `weight`
 accepts `thin`, `regular`, or `bold`; and `outline` accepts `none`, `subtle`, or `strong`.
 `extras.paths`, `extras.rail`, and `extras.ferry` are independent and default to `false`.
+`widthScale` accepts bounded multipliers for selected road classes, and `oneWayMarkers` adds
+direction markers to eligible one-way roads.
 
 Without options, `roads()` uses `detail: 'streets'`, `hierarchy: 'clear'`,
 `weight: 'regular'`, `outline: 'subtle'`, and all extras disabled. Named visual recipes belong
@@ -124,6 +180,7 @@ labels({
   language: 'auto',
   places: 'major',
   roads: 'major',
+  roadClasses: ['motorway', 'trunk', 'primary', 'secondary'],
   water: 'major',
 });
 ```
@@ -140,12 +197,46 @@ are also clamped to the classes currently visible through `roads({detail})`, so
 is the intersection of both modules. `language` accepts `auto`, `local`, or a language code such as
 `en` or `es`.
 
+`roadClasses` is an optional explicit eligibility list. It is intersected with both the label
+detail and visible `roads()` classes, so it cannot label a road family that the map has hidden.
+
 Without options, `labels()` uses `language: 'auto'` and `major` for all three label families.
 Label colors remain in `theme.modules.labels`; font family and weight remain in `typography`.
 
+## POI module
+
+POI category policy is resolved once for filtering, icon selection, label color, and collision
+priority:
+
+```ts
+poi({
+  categories: ['food', 'culture', 'lodging'],
+  classMapping: {culture: ['planetarium']},
+  color: 'category',
+  density: 'balanced',
+  icons: 'full',
+  labels: 'full',
+  placement: {coupleIconAndLabel: true, iconPadding: 4, textPadding: 8},
+});
+```
+
+Built-in mappings inspect both `class` and `subclass`; `classMapping` adds source-specific values
+without removing the defaults. `color: 'category'` uses `theme.modules.poi` colors end to end.
+Named density is opt-in and adds bounded category-aware rank gates plus stable sort priority;
+omitting it preserves legacy layer behavior. Raw source rank expressions remain available through
+`styleOverride` when a particular dataset needs a bespoke rule.
+
+## Tile-source revision
+
+Set `version` on `osm({...})`, `maps.<name>.tiles`, or a named project tileset to pin an immutable
+archive identifier. Map-level `tiles.version` wins over basemap and named-tileset defaults. Tileflow
+adds it as `archiveVersion` to the TileJSON URL and records it as
+`metadata['tileflow:tilesetVersion']`; it never infers stability from an unversioned response.
+
 ## Public API
 
-Use the package root only:
+Application config, compilation, runtime resolution, and capture-scene APIs come from the package
+root:
 
 ```ts
 import {
@@ -160,6 +251,28 @@ import {
 } from '@tileflow/core';
 ```
 
-Subpaths under `src/`, `themes/`, `templates/`, and `modules/` are internal implementation details and can change during alpha releases.
+Capture scene schemas, types, normalization, limits, and schema version are also exported from the
+package root. See the [local visual capture contract](https://tileflow.dev/docs/agent-workflow) for
+the CLI workflow and readiness boundary.
+
+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).
+
+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,74 @@
+import { T as TileflowAnalytics } from './runtime-BMZ_tuba.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: {
+    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;
+    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;
+    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,320 @@
+// 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/start`;
+  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"
+  });
+}
+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;
+      if (!mapId) {
+        return false;
+      }
+      const key = `${options.sessionId}:${mapId}:${styleId ?? ""}`;
+      if (starts.has(key)) {
+        return false;
+      }
+      starts.add(key);
+      send(analytics, {
+        mapId,
+        sessionId: options.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();
+    if (!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) => applyTileflowAnalyticsRequest(
+          url,
+          resolvedRequest,
+          asyncAnalyticsTiming === "resolution" ? options.getAnalytics() : analyticsAtRequest,
+          options.sessionId
+        ) ?? resolvedRequest
+      );
+    }
+    return applyTileflowAnalyticsRequest(
+      url,
+      request,
+      asyncAnalyticsTiming === "resolution" ? options.getAnalytics() : analyticsAtRequest,
+      options.sessionId
+    );
+  };
+}
+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 applyTileflowAnalyticsRequest(url, request, analytics, sessionId) {
+  const nextUrl = resolveTileflowAnalyticsRequestUrl(request?.url ?? url, analytics, sessionId);
+  if (!nextUrl) {
+    return request;
+  }
+  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
+};