@tileflow/core 0.1.0-alpha.28 → 0.1.0-alpha.29

package/README.md

@@ -67,7 +67,7 @@ Omitted fields inherit, but declaring a field does not imply a recursive merge:
   Spread the parent's list explicitly when composing contributors. Later contributors win for an
   exact icon ID.
 - `fonts` and `glyphs` are mutually exclusive text providers. Declaring either replaces the inherited
-  provider. `data`, `projection`, `terrain`, and `marine` are also atomic.
+  provider. `atmosphere`, `data`, `projection`, `terrain`, and `marine` are also atomic.
 
 Identity (`id`, `name`, `version`) and tooling `scenes` belong to the leaf map and do not inherit.
 Module object order does not determine rendering order. See the
@@ -222,8 +222,15 @@ tooling prepare browser resources; direct MapLibre integrations must register re
 before loading a style. See the
 [browser runtime contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/framework-browser-runtime.md).
 
+Set `projection: 'globe'` and `atmosphere: true` in `tileflow.config.ts` for a blue globe rim,
+space background, and stars. Use `atmosphere: false` to disable an inherited atmosphere, or an
+options object for theme-aware colors and bounded star brightness/motion. React, Vue, Svelte, and
+standalone capture apply the browser effect automatically. Direct MapLibre integrations call
+`attachTileflowAtmosphere(map)` from `@tileflow/core/browser`. See
+[globe atmosphere](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/globe-atmosphere.md).
+
 A map with text must declare exactly one text provider. Streets, Ferraris, Härad, Soundings,
-Verdant, and San Francisto use URL glyph providers. Baedeker and Siegfried use packaged Cormorant
+and Blueprint use URL glyph providers. Baedeker and Siegfried use packaged Cormorant
 fonts; Cyberpunk and Matrix use packaged Oxanium fonts. Hosted deployment currently rejects
 package/local font bundles; use self-hosted output or explicitly replace the provider with compatible
 public glyphs. Tile URLs and font providers do not establish redistribution rights.
@@ -242,6 +249,7 @@ for exact options. Prefer the installed CLI's generated contracts when using a p
 These guides are also included in the installed package under `docs/`. They describe this source
 revision; prefer the installed copy when working with an older release.
 
+- [Globe atmosphere](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/globe-atmosphere.md)
 - [Map and terrain examples](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/map-and-terrain-examples.md)
 - [Authoring model](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/authoring-model.md)
 - [Shared visual primitives](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/shared-visual-primitives.md)

package/dist/browser.d.ts

@@ -45,6 +45,7 @@ type TileflowLight = {
     position?: readonly [number, number, number];
 };
 type MapLibreStyle = {
+    sky?: Record<string, unknown>;
     version: 8;
     name: string;
     glyphs?: string;
@@ -93,6 +94,32 @@ type TileflowStyleFontFace = {
     weight?: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
 };
 
+/** Structural MapLibre capabilities; importing this module never loads a renderer. */
+type TileflowAtmosphereMap = {
+    getBearing(): number;
+    getCanvas(): HTMLCanvasElement;
+    getCenter(): {
+        lat: number;
+        lng: number;
+    };
+    getContainer(): HTMLElement;
+    getPitch(): number;
+    getZoom(): number;
+    getStyle(): {
+        metadata?: unknown;
+        projection?: {
+            type?: unknown;
+        };
+    } | undefined;
+    on(event: 'move' | 'resize' | 'style.load' | 'remove', listener: () => void): unknown;
+    off(event: 'move' | 'resize' | 'style.load' | 'remove', listener: () => void): unknown;
+};
+/**
+ * Render compiled globe atmosphere metadata. Call after constructing a browser map.
+ * Follows style replacements and releases its canvas, listeners, and pending frame on disposal.
+ */
+declare function attachTileflowAtmosphere(map: TileflowAtmosphereMap): () => void;
+
 declare const tileflowMaplibreContourVersion: "0.1.0";
 type TileflowContourProtocolRequest = Readonly<{
     url: string;
@@ -243,4 +270,4 @@ declare function createTileflowTransformRequest<TRequest extends TileflowTransfo
     worldRequestBridge?: TileflowWorldRequestBridge;
 }): TileflowTransformRequest<TRequest, TResourceType> | undefined;
 
-export { type TileflowAsyncAnalyticsTiming, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowFairUseNotice, type TileflowFairUseNoticeController, type TileflowFairUseNoticeState, type TileflowFrameScheduler, type TileflowMapLifecycleAttachment, type TileflowMapLifecycleEvent, type TileflowMapLifecycleSubscriber, type TileflowMapReadinessState, type TileflowPmtilesProtocolHandler, type TileflowPmtilesProtocolRegistrationOptions, type TileflowPmtilesProtocolRegistry, type TileflowSessionSender, type TileflowSessionStarter, type TileflowStyleFontLoadOptions, type TileflowStyleSwitchMap, type TileflowThemeController, type TileflowThemeTransition, type TileflowThemeTransitionPhase, type TileflowThemeTransitionResult, type TileflowTransformRequest, type TileflowTransformRequestParameters, type TileflowUserTransformRequest, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowFairUseNotice, attachTileflowMapLifecycle, createTileflowSessionStarter, createTileflowThemeController, createTileflowTransformRequest, getTileflowSystemColorScheme, loadTileflowStyleFonts, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, subscribeTileflowSystemColorScheme, tileflowFairUseNoticeMessage, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol };
+export { type TileflowAsyncAnalyticsTiming, type TileflowAtmosphereMap, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowFairUseNotice, type TileflowFairUseNoticeController, type TileflowFairUseNoticeState, type TileflowFrameScheduler, type TileflowMapLifecycleAttachment, type TileflowMapLifecycleEvent, type TileflowMapLifecycleSubscriber, type TileflowMapReadinessState, type TileflowPmtilesProtocolHandler, type TileflowPmtilesProtocolRegistrationOptions, type TileflowPmtilesProtocolRegistry, type TileflowSessionSender, type TileflowSessionStarter, type TileflowStyleFontLoadOptions, type TileflowStyleSwitchMap, type TileflowThemeController, type TileflowThemeTransition, type TileflowThemeTransitionPhase, type TileflowThemeTransitionResult, type TileflowTransformRequest, type TileflowTransformRequestParameters, type TileflowUserTransformRequest, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowAtmosphere, attachTileflowFairUseNotice, attachTileflowMapLifecycle, createTileflowSessionStarter, createTileflowThemeController, createTileflowTransformRequest, getTileflowSystemColorScheme, loadTileflowStyleFonts, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, subscribeTileflowSystemColorScheme, tileflowFairUseNoticeMessage, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol };

package/dist/browser.js

@@ -2201,6 +2201,207 @@ function getTileflowLocationOrigin() {
   return window.location.origin;
 }
 
+// src/atmosphere.ts
+var tileflowAtmosphereMetadataKey = "tileflow:atmosphere";
+function readTileflowAtmosphere(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const record = value;
+  if (record.version !== 1 || Object.keys(record).length !== 7) return void 0;
+  for (const key of ["skyColor", "horizonColor", "fogColor", "spaceColor"]) {
+    if (typeof record[key] !== "string" || !/^#[0-9a-f]{6}$/i.test(record[key])) return void 0;
+  }
+  for (const key of ["starIntensity", "starParallax"]) {
+    const number = record[key];
+    if (typeof number !== "number" || !Number.isFinite(number) || number < 0 || number > 1)
+      return void 0;
+  }
+  return {
+    skyColor: record.skyColor,
+    horizonColor: record.horizonColor,
+    fogColor: record.fogColor,
+    spaceColor: record.spaceColor,
+    starIntensity: record.starIntensity,
+    starParallax: record.starParallax
+  };
+}
+function atmosphereSpaceOpacity(zoom) {
+  const progress = Math.max(0, Math.min(1, (zoom - 3) / 3));
+  return 1 - progress * progress * (3 - 2 * progress);
+}
+function atmosphereAngleDelta(next, previous) {
+  return ((next - previous) % 360 + 540) % 360 - 180;
+}
+function wrapAtmosphereStar(value, extent) {
+  return (value % extent + extent) % extent;
+}
+function createAtmosphereStars(count = 650) {
+  let seed = 7321;
+  const random = () => {
+    seed = Math.imul(seed, 1664525) + 1013904223 >>> 0;
+    return seed / 4294967296;
+  };
+  return Array.from({ length: count }, () => ({
+    x: random(),
+    y: random(),
+    radius: 0.35 + random() ** 5 * 0.95,
+    alpha: 0.18 + random() ** 2 * 0.6
+  }));
+}
+
+// src/atmosphere-browser.ts
+function attachTileflowAtmosphere(map) {
+  const container = map.getContainer();
+  const document2 = container.ownerDocument;
+  const browser = document2.defaultView;
+  if (!browser) return () => {
+  };
+  const mapCanvas = map.getCanvas();
+  const previousFilter = mapCanvas.style.filter;
+  const reducedMotion = browser.matchMedia("(prefers-reduced-motion: reduce)");
+  const stars = createAtmosphereStars();
+  let options;
+  let canvas;
+  let context = null;
+  let frame;
+  let disposed = false;
+  let appliedFilter;
+  let width = 0;
+  let height = 0;
+  let pixelRatio = 0;
+  let previousLongitude = map.getCenter().lng;
+  let previousBearing = map.getBearing();
+  let longitude = previousLongitude;
+  let bearing = previousBearing;
+  function restoreFilter() {
+    if (appliedFilter !== void 0 && mapCanvas.style.filter === appliedFilter)
+      mapCanvas.style.filter = previousFilter;
+    appliedFilter = void 0;
+  }
+  function removeCanvas() {
+    canvas?.remove();
+    canvas = void 0;
+    context = null;
+    width = height = pixelRatio = 0;
+    restoreFilter();
+  }
+  function syncStyle() {
+    if (disposed) return;
+    const style = map.getStyle();
+    const metadata = style?.metadata;
+    options = style?.projection?.type === "globe" && metadata && typeof metadata === "object" ? readTileflowAtmosphere(
+      metadata[tileflowAtmosphereMetadataKey]
+    ) : void 0;
+    if (!options) {
+      if (frame !== void 0) browser.cancelAnimationFrame(frame);
+      frame = void 0;
+      removeCanvas();
+      return;
+    }
+    if (!canvas) {
+      canvas = document2.createElement("canvas");
+      canvas.setAttribute("aria-hidden", "true");
+      canvas.setAttribute("data-tileflow-atmosphere", "");
+      Object.assign(canvas.style, {
+        position: "absolute",
+        inset: "0",
+        width: "100%",
+        height: "100%",
+        opacity: "0",
+        pointerEvents: "none"
+      });
+      context = canvas.getContext("2d");
+      container.insertBefore(canvas, container.firstChild);
+    }
+    canvas.style.background = `radial-gradient(ellipse at 50% 48%, ${options.skyColor} 0%, ${options.spaceColor} 100%)`;
+    schedule();
+  }
+  function draw() {
+    frame = void 0;
+    if (disposed || !options || !canvas) return;
+    const center = map.getCenter();
+    longitude += atmosphereAngleDelta(center.lng, previousLongitude);
+    bearing += atmosphereAngleDelta(map.getBearing(), previousBearing);
+    previousLongitude = center.lng;
+    previousBearing = map.getBearing();
+    const opacity = atmosphereSpaceOpacity(map.getZoom());
+    canvas.style.opacity = String(opacity);
+    if (opacity === 0) {
+      restoreFilter();
+      return;
+    }
+    const baseFilter = previousFilter && previousFilter !== "none" ? `${previousFilter} ` : "";
+    mapCanvas.style.filter = `${baseFilter}drop-shadow(0 0 2px ${withAlpha(options.horizonColor, opacity * 0.65)}) drop-shadow(0 0 12px ${withAlpha(options.horizonColor, opacity * 0.4)})`;
+    appliedFilter = mapCanvas.style.filter;
+    if (!context) return;
+    const nextWidth = container.clientWidth;
+    const nextHeight = container.clientHeight;
+    if (!nextWidth || !nextHeight) return;
+    const nextPixelRatio = Math.min(browser.devicePixelRatio || 1, 2);
+    if (width !== nextWidth || height !== nextHeight || pixelRatio !== nextPixelRatio) {
+      width = nextWidth;
+      height = nextHeight;
+      pixelRatio = nextPixelRatio;
+      canvas.width = Math.round(width * pixelRatio);
+      canvas.height = Math.round(height * pixelRatio);
+      context.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0);
+    }
+    context.clearRect(0, 0, width, height);
+    if (options.starIntensity === 0) return;
+    const motion = reducedMotion.matches ? 0 : options.starParallax / 0.4;
+    const xOffset = motion * (-longitude * 0.8 - bearing * 0.35);
+    const yOffset = motion * (center.lat * 0.6 + map.getPitch() * 0.4);
+    const intensity = options.starIntensity / 0.6;
+    const fieldWidth = 1600;
+    const fieldHeight = 1e3;
+    for (const star of stars) {
+      const x3 = wrapAtmosphereStar(star.x * fieldWidth + xOffset, fieldWidth);
+      const y = wrapAtmosphereStar(star.y * fieldHeight + yOffset, fieldHeight);
+      for (let tileX = -1; tileX * fieldWidth < width; tileX++) {
+        for (let tileY = -1; tileY * fieldHeight < height; tileY++) {
+          const screenX = x3 + tileX * fieldWidth;
+          const screenY = y + tileY * fieldHeight;
+          if (screenX < -3 || screenX > width + 3 || screenY < -3 || screenY > height + 3) continue;
+          if (star.radius > 0.95) {
+            context.fillStyle = withAlpha(options.horizonColor, star.alpha * intensity * 0.12);
+            context.beginPath();
+            context.arc(screenX, screenY, star.radius * 2.5, 0, Math.PI * 2);
+            context.fill();
+          }
+          context.fillStyle = `rgba(208, 227, 255, ${Math.min(1, star.alpha * intensity)})`;
+          context.beginPath();
+          context.arc(screenX, screenY, star.radius, 0, Math.PI * 2);
+          context.fill();
+        }
+      }
+    }
+  }
+  function schedule() {
+    if (!disposed && options && frame === void 0) frame = browser.requestAnimationFrame(draw);
+  }
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    if (frame !== void 0) browser.cancelAnimationFrame(frame);
+    map.off("move", schedule);
+    map.off("resize", schedule);
+    map.off("style.load", syncStyle);
+    map.off("remove", dispose);
+    reducedMotion.removeEventListener("change", schedule);
+    removeCanvas();
+  }
+  map.on("move", schedule);
+  map.on("resize", schedule);
+  map.on("style.load", syncStyle);
+  map.on("remove", dispose);
+  reducedMotion.addEventListener("change", schedule);
+  syncStyle();
+  return dispose;
+}
+function withAlpha(color, alpha) {
+  const value = Number.parseInt(color.slice(1), 16);
+  return `rgba(${value >> 16}, ${value >> 8 & 255}, ${value & 255}, ${alpha})`;
+}
+
 // src/data/world-release-id-values.ts
 var tileflowWorldReleaseIdMinimumLength = 12;
 var tileflowWorldReleaseIdMaximumLength = 128;
@@ -4393,6 +4594,7 @@ function isPromiseLike(value) {
   return Boolean(value && typeof value.then === "function");
 }
 export {
+  attachTileflowAtmosphere,
   attachTileflowFairUseNotice,
   attachTileflowMapLifecycle,
   createTileflowSessionStarter,

package/dist/build.d.ts

@@ -1,7 +1,7 @@
 import { T as TileflowCaptureScene } from './capture-scene-D6soWztE.js';
-import { T as TileflowRenderedIconIdentity, a as TileflowIconCompositionV1, R as ResolvedTileflowMap, b as TileflowDataRequirementsV1, c as TileflowSourceRequirementsV1, d as TileflowMap, e as TileflowStyleOptions, f as TileflowInspectedStyle, g as TileflowPreparedMapAssets } from './icon-composition-D7sBlZZh.js';
-export { h as TileflowDataCompatibilityIssue, i as TileflowDataFieldRequirement, j as TileflowDataFieldType, k as TileflowDataLayerRequirement, l as TileflowObservedDataContractV1, m as TileflowStyleInspection, n as TileflowStyleInspectionContribution, o as TileflowStyleInspectionLayer, p as TileflowStyleInspectionRenderOperation, q as collectMapLineage, r as inferTileflowDataRequirements, s as inferTileflowSourceRequirements, t as tileflowStyleInspectionSchemaVersion, v as validateTileflowDataCompatibility } from './icon-composition-D7sBlZZh.js';
-import { M as MapLibreStyle, T as TileflowRuntimeManifest } from './manifest-types-BdGjIYy-.js';
+import { T as TileflowRenderedIconIdentity, a as TileflowIconCompositionV1, R as ResolvedTileflowMap, b as TileflowDataRequirementsV1, c as TileflowSourceRequirementsV1, d as TileflowMap, e as TileflowStyleOptions, f as TileflowInspectedStyle, g as TileflowPreparedMapAssets } from './icon-composition-BquPlPPI.js';
+export { h as TileflowDataCompatibilityIssue, i as TileflowDataFieldRequirement, j as TileflowDataFieldType, k as TileflowDataLayerRequirement, l as TileflowObservedDataContractV1, m as TileflowStyleInspection, n as TileflowStyleInspectionContribution, o as TileflowStyleInspectionLayer, p as TileflowStyleInspectionRenderOperation, q as collectMapLineage, r as inferTileflowDataRequirements, s as inferTileflowSourceRequirements, t as tileflowStyleInspectionSchemaVersion, v as validateTileflowDataCompatibility } from './icon-composition-BquPlPPI.js';
+import { M as MapLibreStyle, T as TileflowRuntimeManifest } from './manifest-types-BZU4zbmI.js';
 import { z } from 'zod';
 
 declare const tileflowMapRevisionSchemaVersion: 1;
@@ -258,9 +258,9 @@ declare const tileflowRendererDeploymentArtifactSchema: z.ZodObject<{
                                 iconIds: z.ZodArray<z.ZodString>;
                             }, z.core.$strict>], "kind">>;
                             winners: z.ZodArray<z.ZodObject<{
-                                id: z.ZodString;
                                 width: z.ZodNumber;
                                 height: z.ZodNumber;
+                                id: z.ZodString;
                                 layout: z.ZodOptional<z.ZodObject<{
                                     stretchX: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
                                     stretchY: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
@@ -289,8 +289,8 @@ declare const tileflowRendererDeploymentArtifactSchema: z.ZodObject<{
                     }, z.core.$strict>>;
                     themes: z.ZodRecord<z.ZodString, z.ZodObject<{
                         colorScheme: z.ZodEnum<{
-                            dark: "dark";
                             light: "light";
+                            dark: "dark";
                         }>;
                         dataRequirements: z.ZodRecord<z.ZodString, z.ZodUnknown>;
                         sourceRequirements: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -450,9 +450,9 @@ declare const tileflowRendererDeploymentArtifactSchema: z.ZodObject<{
                                 iconIds: z.ZodArray<z.ZodString>;
                             }, z.core.$strict>], "kind">>;
                             winners: z.ZodArray<z.ZodObject<{
-                                id: z.ZodString;
                                 width: z.ZodNumber;
                                 height: z.ZodNumber;
+                                id: z.ZodString;
                                 layout: z.ZodOptional<z.ZodObject<{
                                     stretchX: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
                                     stretchY: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
@@ -481,8 +481,8 @@ declare const tileflowRendererDeploymentArtifactSchema: z.ZodObject<{
                     }, z.core.$strict>>;
                     themes: z.ZodRecord<z.ZodString, z.ZodObject<{
                         colorScheme: z.ZodEnum<{
-                            dark: "dark";
                             light: "light";
+                            dark: "dark";
                         }>;
                         dataRequirements: z.ZodRecord<z.ZodString, z.ZodUnknown>;
                         sourceRequirements: z.ZodRecord<z.ZodString, z.ZodUnknown>;