@tileflow/dev 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/chunk-XTRHREXO.js

@@ -0,0 +1,1688 @@
+import {
+  inspectTileflowPmtilesForLocalUse
+} from "./chunk-ONYQNLNA.js";
+import {
+  getTileflowFontWatchPaths,
+  joinTileflowPublicUrl,
+  prepareTileflowStyleFonts,
+  replaceTileflowStyleFontSources
+} from "./chunk-RSBV4L2Y.js";
+import {
+  getTileflowIconWatchPaths,
+  prepareTileflowCatalogIcons
+} from "./chunk-CENQR5Q2.js";
+import {
+  TileflowStyleValidationError,
+  normalizeTileflowStyleValidationIssues,
+  sanitizeDiagnosticSecrets,
+  validateTileflowStyle
+} from "./chunk-KDFTE4Q5.js";
+import {
+  defaultTileflowConfigPath,
+  getTileflowMapNames,
+  loadValidTileflowConfigWithInputs
+} from "./chunk-6MGFMKG3.js";
+import {
+  isPathWithin
+} from "./chunk-D4OE4ITL.js";
+
+// src/artifacts.ts
+import { createHash } from "crypto";
+import { realpathSync as realpathSync2 } from "fs";
+import {
+  copyFile as copyFile2,
+  lstat as lstat2,
+  mkdir as mkdir2,
+  mkdtemp,
+  open as open2,
+  readFile,
+  realpath as realpath2,
+  rename,
+  rm as rm2,
+  unlink
+} from "fs/promises";
+import { createRequire } from "module";
+import { dirname as dirname2, relative as relative2, resolve as resolve3, sep as sep2 } from "path";
+import {
+  compareCodeUnits as compareCodeUnits2,
+  getTileflowStyleFontFaces,
+  serializeCanonicalJson,
+  tileflowMapIdSchema,
+  tileflowThemeNameSchema
+} from "@tileflow/core";
+import {
+  createManifest,
+  createStyleFromCatalog,
+  createStylesFromCatalog,
+  createStylesFromCatalogWithInspection,
+  createTileflowMapBuildManifest,
+  tileflowMapBuildManifestFileName
+} from "@tileflow/core/build";
+import { parseTileflowRuntimeManifest } from "@tileflow/core/manifest";
+
+// src/local-tilesets.ts
+import { randomUUID } from "crypto";
+import { constants } from "fs";
+import { chmod, copyFile, lstat, mkdir, open, readdir, realpath, rm, stat } from "fs/promises";
+import { basename, resolve } from "path";
+import { compareCodeUnits } from "@tileflow/core";
+var minimumLocalPmtilesBytes = 127n;
+var maximumLocalPmtilesBytes = 8000000000n;
+async function prepareTileflowLocalTilesets(project, styles, options) {
+  const hasSources = Object.values(project.maps).some(
+    (map) => Object.keys(map.sources ?? {}).length > 0
+  );
+  if (!hasSources) {
+    return { dispose: async () => void 0, files: [], styles, watchPaths: [] };
+  }
+  const logicalProjectRoot = resolve(options.cwd);
+  const projectRoot = await realpath(logicalProjectRoot).catch(() => logicalProjectRoot);
+  const snapshotStore = resolve(logicalProjectRoot, ".tileflow/cache/pmtiles-snapshots/v1");
+  await assertSafeSnapshotStore(logicalProjectRoot, snapshotStore);
+  await collectAbandonedSnapshotGenerations(snapshotStore);
+  const generationId = `snapshot-${process.pid}-${randomUUID().replaceAll("-", "")}`;
+  const generationDirectory = resolve(snapshotStore, generationId);
+  await mkdir(generationDirectory);
+  const bindings = /* @__PURE__ */ new Map();
+  const files = /* @__PURE__ */ new Map();
+  const snapshots = /* @__PURE__ */ new Map();
+  const output = Object.fromEntries(
+    Object.entries(styles).map(([mapName, family]) => [
+      mapName,
+      Object.fromEntries(
+        Object.entries(family).map(([themeName, style]) => [themeName, cloneStyle(style)])
+      )
+    ])
+  );
+  let disposed = false;
+  const dispose = async () => {
+    if (disposed) return;
+    disposed = true;
+    if (!isPathWithin(snapshotStore, generationDirectory)) {
+      throw new Error("Local PMTiles snapshot generation escaped its store.");
+    }
+    await rm(generationDirectory, { force: true, recursive: true });
+  };
+  try {
+    for (const mapName of Object.keys(project.maps).sort(compareCodeUnits)) {
+      const map = project.maps[mapName];
+      for (const [sourceId, source] of Object.entries(map.sources ?? {}).sort(
+        ([left], [right]) => compareCodeUnits(left, right)
+      )) {
+        const requestedPath = resolve(options.baseDirectory, source.local);
+        const sourcePath = await realpath(requestedPath).catch(() => requestedPath);
+        if (!isPathWithin(projectRoot, sourcePath)) {
+          throw localTilesetError(
+            "TF_LOCAL_TILESET_OUTSIDE_ROOT",
+            `maps.${mapName}.sources.${sourceId}.local`,
+            "Local hosted tileset must stay inside the project root."
+          );
+        }
+        const sourceStat = await lstat(sourcePath).catch(() => null);
+        if (!sourceStat?.isFile() || sourceStat.isSymbolicLink()) {
+          throw localTilesetError(
+            "TF_LOCAL_TILESET_NOT_FOUND",
+            `maps.${mapName}.sources.${sourceId}.local`,
+            `Local hosted tileset "${sourceId}" was not found.`
+          );
+        }
+        let snapshot = snapshots.get(sourcePath);
+        if (!snapshot) {
+          snapshot = await createLocalTilesetSnapshot(
+            sourcePath,
+            generationDirectory,
+            snapshots.size
+          );
+          snapshots.set(sourcePath, snapshot);
+        }
+        const file = {
+          byteLength: snapshot.byteLength,
+          etag: snapshot.etag,
+          fileName: `tilesets/${source.tileset}.pmtiles`,
+          logicalId: source.tileset,
+          sourcePath: snapshot.sourcePath
+        };
+        const existing = bindings.get(source.tileset);
+        if (existing && existing.originalSourcePath !== sourcePath) {
+          throw localTilesetError(
+            "TF_LOCAL_TILESET_BINDING_CONFLICT",
+            `maps.${mapName}.sources.${sourceId}.local`,
+            `Logical tileset "${source.tileset}" resolves to different local archives in one generation.`
+          );
+        }
+        bindings.set(source.tileset, { file, originalSourcePath: sourcePath });
+        files.set(file.fileName, files.get(file.fileName) ?? file);
+        validateSourceContract(
+          mapName,
+          sourceId,
+          source.type,
+          output[mapName] ?? {},
+          snapshot.inspection
+        );
+        const publicUrl = joinTileflowPublicUrl(options.assetBaseUrl, file.fileName);
+        for (const style of Object.values(output[mapName] ?? {})) {
+          const definition = style.sources[sourceId];
+          if (!definition) {
+            throw localTilesetError(
+              "TF_LOCAL_TILESET_SOURCE_MISSING",
+              `maps.${mapName}.sources.${sourceId}`,
+              `Compiled style is missing hosted source "${sourceId}".`
+            );
+          }
+          definition.url = `tileflow-pmtiles://${publicUrl}`;
+          delete definition.tiles;
+        }
+      }
+    }
+    return {
+      dispose,
+      files: [...files.values()].sort(
+        (left, right) => compareCodeUnits(left.fileName, right.fileName)
+      ),
+      styles: output,
+      watchPaths: [...snapshots.keys()].sort(compareCodeUnits)
+    };
+  } catch (error) {
+    await dispose().catch(() => void 0);
+    throw error;
+  }
+}
+async function createLocalTilesetSnapshot(sourcePath, generationDirectory, index) {
+  const sourceHandle = await open(sourcePath, "r");
+  const snapshotPath = resolve(generationDirectory, `${index}.pmtiles`);
+  try {
+    const before = sourceIdentity(await sourceHandle.stat({ bigint: true }));
+    if (before.size < minimumLocalPmtilesBytes || before.size > maximumLocalPmtilesBytes) {
+      throw localTilesetError(
+        "TF_TILESET_ARCHIVE_INVALID",
+        "archive",
+        "Expected one bounded PMTiles file."
+      );
+    }
+    await copyFile(sourcePath, snapshotPath, constants.COPYFILE_FICLONE);
+    await syncFile(snapshotPath);
+    const [afterHandle, afterPath, snapshotStat] = await Promise.all([
+      sourceHandle.stat({ bigint: true }).then(sourceIdentity),
+      stat(sourcePath, { bigint: true }).then(sourceIdentity),
+      stat(snapshotPath, { bigint: true })
+    ]);
+    assertSourceIdentity(before, afterHandle);
+    assertSourceIdentity(before, afterPath);
+    if (!snapshotStat.isFile() || snapshotStat.size !== before.size) {
+      throw localTilesetError(
+        "TF_LOCAL_TILESET_CHANGED",
+        "local",
+        "Local hosted tileset changed while its immutable snapshot was prepared."
+      );
+    }
+    const inspection = await inspectTileflowPmtilesForLocalUse(snapshotPath);
+    await chmod(snapshotPath, 292);
+    return Object.freeze({
+      byteLength: Number(before.size),
+      etag: `"${generationIdFromDirectory(generationDirectory)}-${index}"`,
+      inspection,
+      sourcePath: snapshotPath
+    });
+  } finally {
+    await sourceHandle.close();
+  }
+}
+function generationIdFromDirectory(path) {
+  const generationId = basename(path);
+  if (!/^snapshot-\d+-[a-f0-9]{32}$/u.test(generationId)) {
+    throw new Error("Local PMTiles snapshot generation is invalid.");
+  }
+  return generationId;
+}
+function sourceIdentity(value) {
+  if (!value.isFile()) throw new Error("Local PMTiles source is not a file.");
+  return Object.freeze({
+    device: BigInt(value.dev),
+    inode: BigInt(value.ino),
+    mtimeNanoseconds: "mtimeNs" in value ? BigInt(value.mtimeNs) : BigInt(Math.round(value.mtimeMs * 1e6)),
+    size: BigInt(value.size)
+  });
+}
+function assertSourceIdentity(before, after) {
+  if (before.device !== after.device || before.inode !== after.inode || before.mtimeNanoseconds !== after.mtimeNanoseconds || before.size !== after.size) {
+    throw localTilesetError(
+      "TF_LOCAL_TILESET_CHANGED",
+      "local",
+      "Local hosted tileset changed while its immutable snapshot was prepared."
+    );
+  }
+}
+function validateSourceContract(mapName, sourceId, sourceType, styles, inspection) {
+  const isVectorArchive = inspection.contract.tileType === "mlt" || inspection.contract.tileType === "mvt";
+  if (sourceType === "vector" !== isVectorArchive) {
+    throw localTilesetError(
+      "TF_SOURCE_TILE_TYPE_MISMATCH",
+      `maps.${mapName}.sources.${sourceId}.type`,
+      `Source "${sourceId}" declares ${sourceType} but the PMTiles archive contains ${inspection.contract.tileType}.`
+    );
+  }
+  if (!isVectorArchive || !inspection.contract.sourceLayersDeclared) return;
+  const availableLayers = new Map(
+    inspection.contract.sourceLayers.map((layer) => [layer.id, layer])
+  );
+  for (const style of Object.values(styles)) {
+    const requirements = asRecord(style.metadata?.["tileflow:sourceRequirements"]);
+    const sources = asRecord(requirements?.sources);
+    const source = asRecord(sources?.[sourceId]);
+    const sourceLayers = Array.isArray(source?.sourceLayers) ? source.sourceLayers : [];
+    for (const candidate of sourceLayers) {
+      const required = asRecord(candidate);
+      const layerId = required?.id;
+      if (typeof layerId !== "string") continue;
+      const available = availableLayers.get(layerId);
+      if (!available) {
+        const candidates = [...availableLayers.keys()].sort(compareCodeUnits);
+        throw localTilesetError(
+          "TF_SOURCE_LAYER_NOT_FOUND",
+          `maps.${mapName}.sources.${sourceId}.sourceLayers.${layerId}`,
+          `Source "${sourceId}" has no source-layer "${layerId}". Available: ${candidates.join(", ") || "(none)"}.`
+        );
+      }
+      if (!available.fieldsDeclared) continue;
+      const availableFields = new Map(available.fields.map((field) => [field.name, field.type]));
+      const requiredFields = Array.isArray(required?.fields) ? required.fields : [];
+      for (const fieldCandidate of requiredFields) {
+        const field = asRecord(fieldCandidate);
+        const fieldName = field?.name;
+        if (typeof fieldName !== "string") continue;
+        if (!availableFields.has(fieldName)) {
+          const candidates = [...availableFields.keys()].sort(compareCodeUnits);
+          throw localTilesetError(
+            "TF_SOURCE_FIELD_NOT_FOUND",
+            `maps.${mapName}.sources.${sourceId}.sourceLayers.${layerId}.fields.${fieldName}`,
+            `Source-layer "${layerId}" has no field "${fieldName}". Available: ${candidates.join(", ") || "(none)"}.`
+          );
+        }
+        const requiredType = field?.type;
+        const actualType = availableFields.get(fieldName);
+        if (typeof requiredType === "string" && actualType !== void 0 && requiredType !== actualType) {
+          throw localTilesetError(
+            "TF_SOURCE_FIELD_TYPE_MISMATCH",
+            `maps.${mapName}.sources.${sourceId}.sourceLayers.${layerId}.fields.${fieldName}`,
+            `Field "${layerId}.${fieldName}" is ${actualType}; ${requiredType} is required.`
+          );
+        }
+      }
+    }
+  }
+}
+async function collectAbandonedSnapshotGenerations(store) {
+  const entries = await readdir(store, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const match = /^snapshot-(\d+)-[a-f0-9]{32}$/u.exec(entry.name);
+    if (!match?.[1] || processIsAlive(Number(match[1]))) continue;
+    const path = resolve(store, entry.name);
+    if (isPathWithin(store, path)) await rm(path, { force: true, recursive: true });
+  }
+}
+async function assertSafeSnapshotStore(projectRoot, store) {
+  const segments = [".tileflow", "cache", "pmtiles-snapshots", "v1"];
+  let current = projectRoot;
+  for (const segment of segments) {
+    current = resolve(current, segment);
+    try {
+      const value = await lstat(current);
+      if (!value.isDirectory() || value.isSymbolicLink()) {
+        throw new Error(`Local PMTiles snapshot path is unsafe: ${current}`);
+      }
+    } catch (error) {
+      if (!hasErrorCode(error, "ENOENT")) throw error;
+      await mkdir(current).catch((mkdirError) => {
+        if (!hasErrorCode(mkdirError, "EEXIST")) throw mkdirError;
+      });
+      const created = await lstat(current);
+      if (!created.isDirectory() || created.isSymbolicLink()) {
+        throw new Error(`Local PMTiles snapshot path is unsafe: ${current}`);
+      }
+    }
+  }
+  if (resolve(current) !== resolve(store)) {
+    throw new Error("Local PMTiles snapshot path escaped its project root.");
+  }
+}
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return !hasErrorCode(error, "ESRCH");
+  }
+}
+async function syncFile(path) {
+  const handle = await open(path, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+function cloneStyle(style) {
+  return JSON.parse(JSON.stringify(style));
+}
+function localTilesetError(code, path, message) {
+  return Object.assign(new Error(message), { code, path, phase: "local-tileset-resolution" });
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function hasErrorCode(error, code) {
+  return Boolean(error && typeof error === "object" && error.code === code);
+}
+
+// src/session.ts
+import { watch } from "chokidar";
+import { realpathSync } from "fs";
+import { dirname, extname, isAbsolute, relative, resolve as resolve2, sep, win32 } from "path";
+var tileflowArtifactSessionSchemaVersion = 1;
+var configExtensions = /* @__PURE__ */ new Set([".cjs", ".cts", ".js", ".json", ".mjs", ".mts", ".ts", ".tsx"]);
+var iconExtensions = /* @__PURE__ */ new Set([".jpeg", ".jpg", ".png", ".svg", ".webp"]);
+var fontExtensions = /* @__PURE__ */ new Set([".otf", ".ttf", ".woff2"]);
+var excludedDirectories = /* @__PURE__ */ new Set([
+  ".cache",
+  ".git",
+  ".hg",
+  ".next",
+  ".nuxt",
+  ".svn",
+  ".svelte-kit",
+  ".tileflow",
+  ".turbo",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules"
+]);
+async function createTileflowArtifactSessionWithBuilder(options, buildArtifacts, discoverWatchPaths) {
+  const session = new TileflowArtifactSessionImpl(options, buildArtifacts, discoverWatchPaths);
+  await session.start();
+  return session;
+}
+var TileflowArtifactSessionImpl = class {
+  #buildArtifacts;
+  #buildOptions;
+  #configPath;
+  #cwd;
+  #debounceMs;
+  #discoverWatchPaths;
+  #listeners = /* @__PURE__ */ new Set();
+  #ignoredPaths;
+  #watchEnabled;
+  #closed = false;
+  #closing;
+  #debounceTimer;
+  #generation = 0;
+  #current;
+  #artifactGenerations = /* @__PURE__ */ new Set();
+  #lastGoodGeneration;
+  #refreshes = /* @__PURE__ */ new Set();
+  #refreshToken = 0;
+  #state = { generation: 0, status: "building" };
+  #watcher;
+  #watchedArtifactPaths = /* @__PURE__ */ new Set();
+  constructor(options, buildArtifacts, discoverWatchPaths) {
+    this.#cwd = resolve2(options.cwd ?? process.cwd());
+    this.#configPath = resolve2(this.#cwd, options.config ?? "tileflow.config.ts");
+    this.#debounceMs = Math.max(0, Math.min(options.debounceMs ?? 75, 1e3));
+    this.#watchEnabled = options.watch ?? false;
+    this.#ignoredPaths = (options.ignoredPaths ?? []).map((path) => resolve2(this.#cwd, path));
+    this.#buildArtifacts = buildArtifacts;
+    this.#discoverWatchPaths = discoverWatchPaths;
+    this.#buildOptions = {
+      apiBaseUrl: options.apiBaseUrl,
+      assetBaseUrl: options.assetBaseUrl,
+      config: options.config,
+      cwd: this.#cwd,
+      inspection: options.inspection,
+      styleBaseUrl: options.styleBaseUrl,
+      target: options.target
+    };
+  }
+  async start() {
+    if (this.#watchEnabled) {
+      this.#watcher = watch(dirname(this.#configPath), {
+        awaitWriteFinish: { pollInterval: 20, stabilityThreshold: 50 },
+        followSymlinks: false,
+        ignoreInitial: true,
+        ignored: (path, stats) => this.#ignoreWatchPath(path, stats?.isDirectory()),
+        usePolling: process.platform === "win32"
+      });
+      const watcherReady = new Promise((resolveReady, rejectReady) => {
+        const watcher = this.#watcher;
+        const cleanup = () => {
+          watcher.off("ready", onReady);
+          watcher.off("error", onError);
+        };
+        const onReady = () => {
+          cleanup();
+          resolveReady();
+        };
+        const onError = (error) => {
+          cleanup();
+          rejectReady(error);
+        };
+        watcher.once("ready", onReady);
+        watcher.once("error", onError);
+      });
+      this.#watcher.on("all", (event, path) => {
+        if (event === "addDir" || event === "unlinkDir") return;
+        if (!this.#shouldRefreshForWatchEvent(path)) return;
+        this.#scheduleRefresh(path);
+      });
+      this.#watcher.on("error", (error) => {
+        if (this.#closed) return;
+        this.#refreshToken += 1;
+        this.#publishInvalid(this.#generation + 1, error);
+      });
+      await watcherReady;
+    }
+    await this.refresh("initial");
+  }
+  getState() {
+    return this.#state;
+  }
+  getLastGoodArtifacts() {
+    return this.#current?.artifacts;
+  }
+  acquireArtifacts(generation) {
+    const current = this.#current;
+    if (this.#closed || !current?.accepting || generation !== void 0 && generation !== current.generation) {
+      return void 0;
+    }
+    current.references += 1;
+    let released = false;
+    return Object.freeze({
+      artifacts: current.artifacts,
+      generation: current.generation,
+      release: async () => {
+        if (released) return;
+        released = true;
+        current.references -= 1;
+        if (!current.accepting && current.references === 0) {
+          await this.#disposeGeneration(current);
+        }
+      }
+    });
+  }
+  subscribe(listener) {
+    if (this.#closed) return () => void 0;
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+  async refresh(_reason = "manual") {
+    const refresh = this.#refresh();
+    this.#refreshes.add(refresh);
+    try {
+      await refresh;
+    } finally {
+      this.#refreshes.delete(refresh);
+    }
+  }
+  async #refresh() {
+    if (this.#closed) return;
+    const generation = ++this.#generation;
+    const token = ++this.#refreshToken;
+    this.#publish({
+      generation,
+      status: "building",
+      ...this.#lastGoodGeneration === void 0 ? {} : { lastGoodGeneration: this.#lastGoodGeneration }
+    });
+    try {
+      const artifacts = await this.#buildArtifacts(this.#buildOptions);
+      if (this.#closed || token !== this.#refreshToken) {
+        await disposeArtifacts(artifacts);
+        return;
+      }
+      const previous = this.#current;
+      const current = createArtifactGeneration(generation, artifacts);
+      this.#artifactGenerations.add(current);
+      this.#current = current;
+      this.#lastGoodGeneration = generation;
+      this.#updateArtifactWatchPaths(artifacts.watchPaths);
+      if (previous) {
+        previous.accepting = false;
+        if (previous.references === 0) await this.#disposeGeneration(previous);
+      }
+      this.#publish({
+        artifacts,
+        generation,
+        lastGoodGeneration: generation,
+        status: "ready"
+      });
+    } catch (error) {
+      if (this.#closed || token !== this.#refreshToken) return;
+      if (this.#watcher && this.#discoverWatchPaths) {
+        try {
+          const watchPaths = await this.#discoverWatchPaths();
+          if (this.#closed || token !== this.#refreshToken) return;
+          this.#updateArtifactWatchPaths(watchPaths);
+        } catch {
+        }
+      }
+      this.#publishInvalid(generation, error);
+    }
+  }
+  close() {
+    this.#closing ??= this.#close();
+    return this.#closing;
+  }
+  async #close() {
+    this.#closed = true;
+    this.#refreshToken += 1;
+    if (this.#debounceTimer) clearTimeout(this.#debounceTimer);
+    this.#listeners.clear();
+    await this.#watcher?.close();
+    const retained = [...this.#artifactGenerations];
+    this.#current = void 0;
+    for (const generation of retained) {
+      generation.accepting = false;
+      if (generation.references === 0) void this.#disposeGeneration(generation);
+    }
+    await Promise.allSettled([...this.#refreshes]);
+    await Promise.all(retained.map((generation) => generation.completion));
+  }
+  #ignoreWatchPath(path, isDirectory) {
+    const resolvedPath = resolve2(path);
+    const relativePath = relative(dirname(this.#configPath), resolvedPath);
+    const segments = relativePath.split(sep).filter(Boolean);
+    if (this.#ignoredPaths.some((path2) => isSameOrInside(path2, resolvedPath))) return true;
+    if (segments.some((segment) => excludedDirectories.has(segment))) return true;
+    if (isDirectory !== false) return false;
+    if (resolvedPath === this.#configPath || this.#watchedArtifactPaths.has(resolvedPath))
+      return false;
+    const extension = extname(resolvedPath).toLowerCase();
+    if (configExtensions.has(extension)) return false;
+    if (iconExtensions.has(extension) || fontExtensions.has(extension)) return false;
+    return true;
+  }
+  #shouldRefreshForWatchEvent(path) {
+    const resolvedPath = resolve2(path);
+    const extension = extname(resolvedPath).toLowerCase();
+    if (!iconExtensions.has(extension) && !fontExtensions.has(extension)) return true;
+    return [...this.#watchedArtifactPaths].some((path2) => isSameOrInside(path2, resolvedPath));
+  }
+  #publish(state) {
+    this.#state = state;
+    for (const listener of this.#listeners) listener(state);
+  }
+  #publishInvalid(generation, error) {
+    this.#generation = Math.max(this.#generation, generation);
+    this.#publish({
+      diagnostics: createTileflowArtifactDiagnostics(error, this.#cwd),
+      generation,
+      status: "invalid",
+      ...this.#lastGoodGeneration === void 0 ? {} : { lastGoodGeneration: this.#lastGoodGeneration }
+    });
+  }
+  #scheduleRefresh(_path) {
+    if (this.#closed) return;
+    if (this.#debounceTimer) clearTimeout(this.#debounceTimer);
+    this.#debounceTimer = setTimeout(() => {
+      this.#debounceTimer = void 0;
+      void this.refresh("filesystem");
+    }, this.#debounceMs);
+  }
+  #updateArtifactWatchPaths(paths) {
+    if (!this.#watcher) return;
+    const next = new Set(paths.map((path) => resolve2(this.#cwd, path)));
+    const previous = this.#watchedArtifactPaths;
+    this.#watchedArtifactPaths = next;
+    for (const path of previous) {
+      if (!next.has(path) && !isSameOrInside(dirname(this.#configPath), path)) {
+        void this.#watcher.unwatch(path);
+      }
+    }
+    for (const path of next) {
+      if (!previous.has(path) && !isSameOrInside(dirname(this.#configPath), path)) {
+        this.#watcher.add(path);
+      }
+    }
+  }
+  #disposeGeneration(generation) {
+    if (generation.disposeStarted) return generation.completion;
+    generation.disposeStarted = true;
+    void disposeArtifacts(generation.artifacts).then(
+      () => {
+        this.#artifactGenerations.delete(generation);
+        generation.resolveCompletion();
+      },
+      (error) => {
+        this.#artifactGenerations.delete(generation);
+        generation.rejectCompletion(error);
+      }
+    );
+    return generation.completion;
+  }
+};
+function createArtifactGeneration(generation, artifacts) {
+  let rejectCompletion;
+  let resolveCompletion;
+  const completion = new Promise((resolvePromise, rejectPromise) => {
+    rejectCompletion = rejectPromise;
+    resolveCompletion = resolvePromise;
+  });
+  return {
+    accepting: true,
+    artifacts,
+    completion,
+    disposeStarted: false,
+    generation,
+    references: 0,
+    rejectCompletion,
+    resolveCompletion
+  };
+}
+async function disposeArtifacts(artifacts) {
+  const dispose = artifacts.dispose;
+  artifacts.dispose = void 0;
+  await dispose?.();
+}
+function isSameOrInside(root, candidate) {
+  const path = relative(resolve2(root), resolve2(candidate));
+  return path === "" || !isAbsolute(path) && path !== ".." && !path.startsWith(`..${sep}`);
+}
+function createTileflowArtifactDiagnostics(error, cwd) {
+  const inheritedCode = optionalDiagnosticField(error, "code");
+  const inheritedPath = optionalDiagnosticPath(error);
+  const inheritedPhase = optionalDiagnosticField(error, "phase") ?? optionalNestedDiagnosticField(error, "phase");
+  const semanticResolutionPath = isTileflowMapResolutionDiagnostic(error, inheritedPath) ? sanitizeDiagnosticSecrets(inheritedPath) : void 0;
+  const issueList = getIssueList(error);
+  if (issueList.length > 0) {
+    return normalizeDiagnostics(
+      issueList.map((issue) => ({
+        ...issue.code ?? inheritedCode ? { code: issue.code ?? inheritedCode } : {},
+        message: sanitizeMessage(issue.message, cwd),
+        path: sanitizePath(issue.path, cwd),
+        ...issue.phase ?? inheritedPhase ? { phase: issue.phase ?? inheritedPhase } : {}
+      }))
+    );
+  }
+  return normalizeDiagnostics([
+    {
+      ...inheritedCode ? { code: inheritedCode } : {},
+      message: sanitizeMessage(
+        error instanceof Error ? removeSemanticResolutionPath(error.message, semanticResolutionPath) : "Unknown build error",
+        cwd
+      ),
+      path: semanticResolutionPath ?? sanitizePath(inheritedPath ?? "", cwd),
+      ...inheritedPhase ? { phase: inheritedPhase } : {}
+    }
+  ]);
+}
+function getIssueList(error) {
+  if (!error || typeof error !== "object") return [];
+  const containers = [];
+  for (const key of ["messages", "issues"]) {
+    const value = error[key];
+    if (Array.isArray(value)) containers.push(value);
+  }
+  const details = error.details;
+  if (details && typeof details === "object") {
+    const diagnostics = details.diagnostics;
+    if (Array.isArray(diagnostics)) containers.push(diagnostics);
+  }
+  return containers.flatMap(
+    (value) => value.flatMap((entry) => {
+      if (!entry || typeof entry !== "object") return [];
+      const message = entry.message;
+      const path = entry.path;
+      const code = optionalDiagnosticField(entry, "code");
+      const phase = optionalDiagnosticField(entry, "phase");
+      return typeof message === "string" ? [
+        {
+          ...code ? { code } : {},
+          message,
+          path: typeof path === "string" ? path : "",
+          ...phase ? { phase } : {}
+        }
+      ] : [];
+    })
+  );
+}
+function sanitizeMessage(value, cwd) {
+  let sanitized = value;
+  for (const root of localPathAliases(cwd)) sanitized = sanitized.replaceAll(root, ".");
+  sanitized = sanitized.replace(/[\r\n]+/g, " ").trim();
+  sanitized = sanitized.replace(/https?:\/\/[^\s'")<>]+/gi, (url) => {
+    try {
+      return new URL(url.replace(/[),.;]+$/, "")).origin;
+    } catch {
+      return "(resource URL)";
+    }
+  });
+  sanitized = sanitized.replace(/(^|[\s'"(])[A-Za-z]:[\\/][^\s'")]+/g, "$1(external path)");
+  sanitized = sanitized.replace(/(^|[\s'"(])(?:\\\\|\/\/)[^\s'")]+/g, "$1(external path)");
+  sanitized = sanitized.replace(/(^|[\s'"(])\/[^\s'")]+/g, "$1(external path)");
+  return sanitizeDiagnosticSecrets(sanitized);
+}
+function sanitizePath(value, cwd) {
+  if (!value) return "";
+  if (win32.isAbsolute(value) && !isAbsolute(value)) return "(external)";
+  if (!isAbsolute(value)) return sanitizeDiagnosticSecrets(value.replaceAll("\\", "/"));
+  const local = relative(canonicalPath(cwd), canonicalPath(value)).replaceAll(sep, "/");
+  return local.startsWith("../") || local === ".." ? "(external)" : sanitizeDiagnosticSecrets(local || ".");
+}
+function optionalDiagnosticPath(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const path = value.path;
+  return typeof path === "string" && path ? path : void 0;
+}
+function isTileflowMapResolutionDiagnostic(value, path) {
+  if (!value || typeof value !== "object" || !path) return false;
+  const record = value;
+  return record.name === "TileflowMapResolutionError" && typeof record.code === "string" && typeof record.mapId === "string" && path.startsWith("/modules/") && !/[\p{Cc}]/u.test(path) && !/~(?:[^01]|$)/u.test(path);
+}
+function removeSemanticResolutionPath(message, path) {
+  if (!path) return message;
+  return message.replace(` at ${path}:`, ":");
+}
+function localPathAliases(path) {
+  return [.../* @__PURE__ */ new Set([resolve2(path), canonicalPath(path)])].sort(
+    (left, right) => right.length - left.length
+  );
+}
+function canonicalPath(path) {
+  try {
+    return realpathSync.native(resolve2(path));
+  } catch {
+    return resolve2(path);
+  }
+}
+function normalizeDiagnostics(diagnostics) {
+  const bounded = diagnostics.map((diagnostic) => ({
+    ...diagnostic.code ? { code: boundDiagnosticField(diagnostic.code) } : {},
+    message: boundDiagnosticText(diagnostic.message, 300),
+    path: boundDiagnosticText(diagnostic.path, 300),
+    ...diagnostic.phase ? { phase: boundDiagnosticField(diagnostic.phase) } : {}
+  }));
+  bounded.sort((left, right) => {
+    const leftKey = `${left.path}\0${left.message}\0${left.code ?? ""}\0${left.phase ?? ""}`;
+    const rightKey = `${right.path}\0${right.message}\0${right.code ?? ""}\0${right.phase ?? ""}`;
+    return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+  });
+  return bounded.filter(
+    (diagnostic, index) => index === 0 || JSON.stringify(diagnostic) !== JSON.stringify(bounded[index - 1])
+  ).slice(0, 32);
+}
+function optionalDiagnosticField(value, key) {
+  if (!value || typeof value !== "object") return void 0;
+  const field = value[key];
+  return typeof field === "string" && field.trim() ? boundDiagnosticField(field) : void 0;
+}
+function optionalNestedDiagnosticField(value, key) {
+  if (!value || typeof value !== "object") return void 0;
+  return optionalDiagnosticField(value.details, key);
+}
+function boundDiagnosticField(value) {
+  return boundDiagnosticText(value.replace(/[^A-Za-z0-9_-]/g, ""), 64);
+}
+function boundDiagnosticText(value, limit) {
+  return value.length <= limit ? value : `${value.slice(0, limit - 1)}\u2026`;
+}
+
+// src/artifacts.ts
+var tileflowArtifactPlanSchemaVersion = 1;
+var tileflowArtifactInventoryFileName = ".tileflow-artifacts.json";
+var TileflowHostedManifestOverwriteError = class extends Error {
+  code = "HOSTED_MANIFEST_OVERWRITE_REFUSED";
+  constructor(path) {
+    super(
+      `Refusing to overwrite Hosted manifest at ${path}. Remove it, choose another output directory, or explicitly set overwriteHostedManifest: true.`
+    );
+    this.name = "TileflowHostedManifestOverwriteError";
+  }
+};
+var TileflowLocalTilesetProductionError = class extends Error {
+  code = "TF_LOCAL_TILESET_PRODUCTION_UNRESOLVED";
+  constructor() {
+    super(
+      "Production builds cannot publish local PMTiles sources. Publish the tileset explicitly or provide an application-owned production source."
+    );
+    this.name = "TileflowLocalTilesetProductionError";
+  }
+};
+function createTileflowManifest(project, options = {}) {
+  return createManifest(project, options);
+}
+function createTileflowStyle(project, mapName, options = {}) {
+  const style = createStyleFromCatalog(project, mapName, options);
+  assertValidTileflowStyle(style, mapName);
+  return style;
+}
+function createTileflowStyles(project, options = {}) {
+  const { mapAssets, ...styleOptions } = options;
+  const styles = createStylesFromCatalog(project, {
+    ...styleOptions,
+    mapAssets
+  });
+  assertValidTileflowStyles(project, styles);
+  return styles;
+}
+function createTileflowStylesWithInspection(project, options = {}) {
+  const { mapAssets, ...styleOptions } = options;
+  const inspected = createStylesFromCatalogWithInspection(project, {
+    ...styleOptions,
+    mapAssets
+  });
+  const styles = Object.fromEntries(
+    Object.entries(inspected).map(([mapName, family]) => [
+      mapName,
+      Object.fromEntries(
+        Object.entries(family).map(([themeName, result]) => [themeName, result.style])
+      )
+    ])
+  );
+  const inspections = Object.fromEntries(
+    Object.entries(inspected).map(([mapName, family]) => [
+      mapName,
+      Object.fromEntries(
+        Object.entries(family).map(([themeName, result]) => [themeName, result.inspection])
+      )
+    ])
+  );
+  assertValidTileflowStyles(project, styles);
+  return { inspections, styles };
+}
+function assertValidTileflowStyles(project, styles) {
+  const issues = [];
+  for (const mapName of getTileflowMapNames(project).sort(compareCodeUnits2)) {
+    const family = styles[mapName];
+    if (!family) continue;
+    for (const themeName of Object.keys(family).sort(compareCodeUnits2)) {
+      const style = family[themeName];
+      issues.push(...validateTileflowStyle(style, `${mapName}/${themeName}`));
+    }
+  }
+  if (issues.length > 0) {
+    throw new TileflowStyleValidationError(normalizeTileflowStyleValidationIssues(issues));
+  }
+}
+async function createTileflowArtifactPlan(prepared, options = {}) {
+  if (options.target === "production" && hasLocalTilesetSources(prepared.project)) {
+    throw new TileflowLocalTilesetProductionError();
+  }
+  const inspected = options.inspection ? createTileflowStylesWithInspection(prepared.project, {
+    apiBaseUrl: options.apiBaseUrl,
+    mapAssets: prepared.mapAssets
+  }) : void 0;
+  const compiledStyles = inspected?.styles ?? createTileflowStyles(prepared.project, {
+    apiBaseUrl: options.apiBaseUrl,
+    mapAssets: prepared.mapAssets
+  });
+  const localTilesets = await prepareTileflowLocalTilesets(prepared.project, compiledStyles, {
+    assetBaseUrl: resolveAssetBaseUrl(options),
+    baseDirectory: prepared.baseDirectory,
+    cwd: prepared.cwd
+  });
+  try {
+    const preparedFonts = await prepareTileflowStyleFonts(prepared.project, localTilesets.styles, {
+      assetBaseUrl: resolveAssetBaseUrl(options),
+      baseDirectory: prepared.baseDirectory,
+      cwd: prepared.cwd,
+      target: "local"
+    });
+    const styles = preparedFonts.styles;
+    const assets = [...prepared.assets, ...preparedFonts.assets];
+    const provenance = await createTileflowBuildProvenance(prepared.cwd);
+    const buildManifest = await createTileflowMapBuildManifest(
+      Object.fromEntries(
+        Object.keys(prepared.project.maps).sort(compareCodeUnits2).map((mapName) => {
+          const map = prepared.project.maps[mapName];
+          const style = styles[mapName];
+          return [
+            mapName,
+            {
+              assets: getMapBuildAssets(
+                mapName,
+                assets,
+                preparedFonts.bundles[mapName]?.files ?? []
+              ),
+              lineage: prepared.project.mapMetadata?.[mapName]?.lineage ?? [
+                { id: map.id, mapVersion: map.version }
+              ],
+              map,
+              sourceAssets: {
+                fonts: preparedFonts.sourceIdentities[mapName] ?? [],
+                icons: prepared.mapIconSources[mapName] ?? []
+              },
+              styles: style
+            }
+          ];
+        })
+      ),
+      { provenance }
+    );
+    const stableManifest = createFontAwareManifest(
+      createManifest(prepared.project, { styleBaseUrl: options.styleBaseUrl }),
+      styles
+    );
+    const inputs = {
+      directories: uniqueStrings(
+        [...prepared.watchPaths, ...preparedFonts.watchPaths].map(canonicalInputPath)
+      ),
+      files: uniqueStrings(
+        [...options.inputFiles ?? [], ...localTilesets.watchPaths].map(canonicalInputPath)
+      )
+    };
+    const partial = {
+      assets,
+      buildManifest,
+      dispose: localTilesets.dispose,
+      manifest: stableManifest,
+      project: prepared.project,
+      ...localTilesets.files.length > 0 ? { localTilesets: localTilesets.files } : {},
+      ...inspected ? { styleInspections: inspected.inspections } : {},
+      styles,
+      watchPaths: uniqueStrings([...inputs.files, ...inputs.directories])
+    };
+    const generation = hashArtifactGeneration(getStableTileflowArtifactFiles(partial));
+    const manifest = createGenerationManifest(stableManifest, generation, assets);
+    const generationArtifacts = { ...partial, manifest };
+    return {
+      ...generationArtifacts,
+      files: createGenerationArtifactFiles(generationArtifacts, generation),
+      inputs,
+      project: prepared.project,
+      schemaVersion: tileflowArtifactPlanSchemaVersion,
+      sourceProject: prepared.sourceProject
+    };
+  } catch (error) {
+    await localTilesets.dispose().catch(() => void 0);
+    throw error;
+  }
+}
+async function createTileflowBuildArtifacts(options = {}) {
+  const loaded = await loadValidTileflowConfigWithInputs(
+    options.config ?? defaultTileflowConfigPath,
+    {
+      cwd: options.cwd,
+      fresh: true
+    }
+  );
+  const prepared = await prepareTileflowCatalogIcons(loaded.project, {
+    assetBaseUrl: resolveAssetBaseUrl(options),
+    baseDirectory: dirname2(loaded.configFile),
+    cwd: options.cwd ?? process.cwd()
+  });
+  return await createTileflowArtifactPlan(prepared, { ...options, inputFiles: loaded.inputFiles });
+}
+function getTileflowArtifactFiles(artifacts) {
+  if ("files" in artifacts && Array.isArray(artifacts.files)) {
+    return validateArtifactFiles(artifacts.files);
+  }
+  return getStableTileflowArtifactFiles(artifacts);
+}
+function getStableTileflowArtifactFiles(artifacts) {
+  const files = [
+    {
+      contentType: "application/json; charset=utf-8",
+      fileName: tileflowMapBuildManifestFileName,
+      source: `${serializeCanonicalJson(artifacts.buildManifest)}
+`
+    },
+    {
+      contentType: "application/json; charset=utf-8",
+      fileName: "manifest.json",
+      source: `${JSON.stringify(artifacts.manifest, null, 2)}
+`
+    },
+    ...Object.entries(artifacts.styles).flatMap(
+      ([mapName, themes]) => Object.entries(themes).map(([themeName, style]) => ({
+        contentType: "application/json; charset=utf-8",
+        fileName: `styles/${mapName}/${themeName}.json`,
+        source: `${JSON.stringify(style, null, 2)}
+`
+      }))
+    ),
+    ...artifacts.assets
+  ];
+  return validateArtifactFiles(files);
+}
+function validateArtifactFiles(files) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    assertTileflowArtifactFileName(file.fileName);
+    if (file.fileName === tileflowArtifactInventoryFileName) {
+      throw new Error(`${file.fileName} is reserved for the Tileflow artifact inventory.`);
+    }
+    if (seen.has(file.fileName)) {
+      throw new Error(`Duplicate Tileflow artifact file: ${file.fileName}`);
+    }
+    seen.add(file.fileName);
+  }
+  return [...files].sort((left, right) => compareCodeUnits2(left.fileName, right.fileName));
+}
+function createGenerationManifest(manifest, generation, assets) {
+  return {
+    ...manifest,
+    maps: Object.fromEntries(
+      Object.entries(manifest.maps).map(([mapName, map]) => [
+        mapName,
+        {
+          ...map,
+          themes: Object.fromEntries(
+            Object.entries(map.themes).map(([themeName, theme]) => [
+              themeName,
+              {
+                ...theme,
+                styleUrl: insertGenerationInPublicUrl(
+                  theme.styleUrl,
+                  `styles/${mapName}/${themeName}.json`,
+                  generation
+                ),
+                ...theme.fontFaces ? {
+                  fontFaces: theme.fontFaces.map((fontFace) => ({
+                    ...fontFace,
+                    source: retargetLocalFontAssetUrl(fontFace.source, assets, generation)
+                  }))
+                } : {}
+              }
+            ])
+          )
+        }
+      ])
+    )
+  };
+}
+function createGenerationArtifactFiles(artifacts, generation) {
+  const prefix = `generations/${generation}`;
+  const stableFiles = getStableTileflowArtifactFiles(artifacts);
+  const immutableStyles = Object.entries(artifacts.styles).flatMap(
+    ([mapName, themes]) => Object.entries(themes).map(([themeName, style]) => {
+      const hasLocalSprite = artifacts.assets.some(
+        (asset) => asset.fileName.startsWith(`icons/${mapName}/`)
+      );
+      const sprite = style.sprite;
+      const generationStyleWithSprite = hasLocalSprite && typeof sprite === "string" ? {
+        ...style,
+        // Every theme in one logical map shares the same immutable sprite closure.
+        sprite: isRelativePublicUrl(sprite) ? sprite : insertGenerationInPublicUrl(sprite, `icons/${mapName}/sprite`, generation)
+      } : style;
+      const generationStyle = replaceTileflowStyleFontSources(
+        generationStyleWithSprite,
+        (source) => retargetLocalFontAssetUrl(source, artifacts.assets, generation)
+      );
+      return {
+        contentType: "application/json; charset=utf-8",
+        fileName: `${prefix}/styles/${mapName}/${themeName}.json`,
+        source: `${JSON.stringify(generationStyle, null, 2)}
+`
+      };
+    })
+  );
+  const immutableAssets = artifacts.assets.map(
+    (asset) => ({ ...asset, fileName: `${prefix}/${asset.fileName}` })
+  );
+  return validateArtifactFiles([...stableFiles, ...immutableStyles, ...immutableAssets]);
+}
+function createFontAwareManifest(manifest, styles) {
+  const maps = Object.fromEntries(
+    Object.entries(manifest.maps).map(([mapName, map]) => [
+      mapName,
+      {
+        ...map,
+        themes: Object.fromEntries(
+          Object.entries(map.themes).map(([themeName, theme]) => {
+            const style = styles[mapName]?.[themeName];
+            if (!style) {
+              throw new Error(`Missing compiled Tileflow style for ${mapName}/${themeName}.`);
+            }
+            const definitions = getTileflowStyleFontFaces(style);
+            return [themeName, { ...theme, fontFaces: definitions }];
+          })
+        )
+      }
+    ])
+  );
+  return parseTileflowRuntimeManifest({ ...manifest, maps });
+}
+function retargetLocalFontAssetUrl(source, assets, generation) {
+  if (isRelativePublicUrl(source)) return source;
+  const asset = assets.find(
+    (candidate) => candidate.fileName.startsWith("fonts/") && (source === candidate.fileName || source.endsWith(`/${candidate.fileName}`))
+  );
+  if (!asset) throw new Error(`Unable to resolve Tileflow font artifact URL: ${source}`);
+  return insertGenerationInPublicUrl(source, asset.fileName, generation);
+}
+function getMapBuildAssets(mapName, assets, fontAssets) {
+  const selected = /* @__PURE__ */ new Map();
+  for (const asset of assets) {
+    if (asset.fileName.startsWith(`icons/${mapName}/`)) selected.set(asset.fileName, asset);
+  }
+  for (const asset of fontAssets) {
+    selected.set(asset.fileName, asset);
+  }
+  return [...selected.values()].sort(
+    (left, right) => compareCodeUnits2(left.fileName, right.fileName)
+  );
+}
+function hashBytes(source) {
+  return createHash("sha256").update(typeof source === "string" ? Buffer.from(source, "utf8") : Buffer.from(source)).digest("hex");
+}
+async function createTileflowBuildProvenance(cwd) {
+  const projectDirectory = resolve3(cwd);
+  const projectRequire = createRequire(
+    resolve3(projectDirectory, "__tileflow_build_provenance__.cjs")
+  );
+  const toolRequire = createRequire(import.meta.url);
+  const packages = {};
+  packages["@tileflow/core"] = await readPackageVersion(
+    "@tileflow/core",
+    resolvePackageJson(projectRequire, "@tileflow/core") ?? resolvePackageJson(toolRequire, "@tileflow/core")
+  );
+  packages["@tileflow/dev"] = await readPackageVersion(
+    "@tileflow/dev",
+    new URL("../package.json", import.meta.url)
+  );
+  const mapsPackage = resolvePackageJson(projectRequire, "@tileflow/maps");
+  if (mapsPackage) {
+    packages["@tileflow/maps"] = await readPackageVersion("@tileflow/maps", mapsPackage);
+  }
+  const lockfile = await findNearestLockfile(projectDirectory);
+  return {
+    ...lockfile ? { lockfile: { format: lockfile.format, sha256: hashBytes(lockfile.source) } } : {},
+    packages,
+    schemaVersion: 1
+  };
+}
+function resolvePackageJson(require2, packageName) {
+  try {
+    return require2.resolve(`${packageName}/package.json`);
+  } catch {
+    return void 0;
+  }
+}
+async function readPackageVersion(expectedName, path) {
+  if (!path) throw new Error(`Unable to resolve build package provenance for ${expectedName}.`);
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    throw new Error(`Unable to read build package provenance for ${expectedName}.`);
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.name !== expectedName || typeof parsed.version !== "string") {
+    throw new Error(`Invalid build package provenance for ${expectedName}.`);
+  }
+  return parsed.version;
+}
+async function findNearestLockfile(cwd) {
+  const candidates = [
+    { fileName: "pnpm-lock.yaml", format: "pnpm" },
+    { fileName: "package-lock.json", format: "npm" },
+    { fileName: "yarn.lock", format: "yarn" },
+    { fileName: "bun.lock", format: "bun" },
+    { fileName: "bun.lockb", format: "bun" }
+  ];
+  let directory = cwd;
+  while (true) {
+    for (const candidate of candidates) {
+      try {
+        return {
+          format: candidate.format,
+          source: await readFile(resolve3(directory, candidate.fileName))
+        };
+      } catch (error) {
+        if (!hasErrorCode2(error, "ENOENT")) throw error;
+      }
+    }
+    const parent = dirname2(directory);
+    if (parent === directory) return void 0;
+    directory = parent;
+  }
+}
+function insertGenerationInPublicUrl(url, logicalPath, generation) {
+  const marker = `/${logicalPath}`;
+  const index = url.lastIndexOf(marker);
+  if (index >= 0 && index + marker.length === url.length) {
+    return `${url.slice(0, index)}/generations/${generation}${marker}`;
+  }
+  if (url === logicalPath) return `generations/${generation}/${logicalPath}`;
+  throw new Error(`Unable to content-address Tileflow artifact URL: ${url}`);
+}
+function createTileflowArtifactSession(options = {}) {
+  return createTileflowArtifactSessionWithBuilder(
+    options,
+    createTileflowBuildArtifacts,
+    () => getTileflowWatchPaths(options)
+  );
+}
+async function getTileflowWatchPaths(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const loaded = await loadValidTileflowConfigWithInputs(
+    options.config ?? defaultTileflowConfigPath,
+    { cwd, fresh: true }
+  );
+  const [iconPaths, fontPaths] = await Promise.all([
+    getTileflowIconWatchPaths(loaded.project, cwd, dirname2(loaded.configFile)),
+    getTileflowFontWatchPaths(loaded.project, cwd, dirname2(loaded.configFile))
+  ]);
+  return uniqueStrings([...loaded.inputFiles, ...iconPaths, ...fontPaths]);
+}
+function isTileflowArtifactInputPath(inputs, path) {
+  const candidate = canonicalInputPath(path);
+  return inputs.files.some((input) => canonicalInputPath(input) === candidate) || inputs.directories.some((input) => isPathWithin(canonicalInputPath(input), candidate));
+}
+async function refreshTileflowArtifactSession(session, options) {
+  const inputs = getArtifactInputGraph(session.getLastGoodArtifacts());
+  if (options.inputPath && inputs && !isTileflowArtifactInputPath(inputs, options.inputPath)) {
+    return false;
+  }
+  await session.refresh(options.reason);
+  return true;
+}
+function getArtifactInputGraph(artifacts) {
+  if (!artifacts || !("inputs" in artifacts)) return void 0;
+  const inputs = artifacts.inputs;
+  return inputs && Array.isArray(inputs.files) && Array.isArray(inputs.directories) ? inputs : void 0;
+}
+async function writeTileflowBuildArtifacts(options) {
+  const artifacts = await createTileflowBuildArtifacts({ ...options, target: "production" });
+  try {
+    await writeTileflowArtifactPlan(artifacts, options);
+    return { ...artifacts, dispose: void 0, localTilesets: void 0 };
+  } finally {
+    await disposeTileflowBuildArtifacts(artifacts);
+  }
+}
+async function disposeTileflowBuildArtifacts(artifacts) {
+  const dispose = artifacts.dispose;
+  artifacts.dispose = void 0;
+  await dispose?.();
+}
+async function writeTileflowArtifactPlan(artifacts, options) {
+  assertNoLocalTilesetsForProduction(artifacts);
+  const cwd = options.cwd ?? process.cwd();
+  const output = await prepareTileflowOutputDirectory(cwd, options.outDir);
+  const files = getTileflowArtifactFiles(artifacts);
+  await assertTileflowSelfHostedManifestTarget(resolve3(output.outDir, "manifest.json"), options);
+  await commitTileflowArtifactFiles(output, files);
+}
+function assertNoLocalTilesetsForProduction(artifacts) {
+  if (artifacts.localTilesets?.length) throw new TileflowLocalTilesetProductionError();
+}
+function hasLocalTilesetSources(project) {
+  return Object.values(project.maps).some((map) => Object.keys(map.sources ?? {}).length > 0);
+}
+async function assertTileflowSelfHostedManifestTarget(manifestPath, options = {}) {
+  if (options.overwriteHostedManifest) return;
+  let source;
+  try {
+    source = await readFile(resolve3(manifestPath), "utf8");
+  } catch (error) {
+    if (hasErrorCode2(error, "ENOENT")) return;
+    throw error;
+  }
+  try {
+    const manifest = parseTileflowRuntimeManifest(JSON.parse(source));
+    if (isHostedRuntimeManifest(manifest)) {
+      throw new TileflowHostedManifestOverwriteError(resolve3(manifestPath));
+    }
+  } catch (error) {
+    if (error instanceof TileflowHostedManifestOverwriteError) throw error;
+  }
+}
+function isHostedRuntimeManifest(manifest) {
+  return Boolean(
+    manifest.apiUrl || Object.values(manifest.maps).some(
+      (map) => map.apiUrl || map.environment || map.mapId || map.usageMode || map.worldGeneration || Object.values(map.themes).some((theme) => theme.styleId)
+    )
+  );
+}
+function assertValidTileflowStyle(style, mapName) {
+  const issues = validateTileflowStyle(style, mapName);
+  if (issues.length > 0) {
+    throw new TileflowStyleValidationError(normalizeTileflowStyleValidationIssues(issues));
+  }
+}
+async function commitTileflowArtifactFiles(output, files) {
+  await assertTileflowOutputDirectoryIsSafe(output);
+  const { outDir } = output;
+  const previous = await readTileflowArtifactInventory(outDir);
+  const desiredNames = files.map((file) => file.fileName);
+  const generation = getArtifactGeneration(files);
+  const retainedGenerations = previous ? generation === previous.generation ? getManagedGenerations(previous.files) : [previous.generation] : [];
+  const retainedPrefixes = retainedGenerations.map((item) => `generations/${item}/`);
+  const retainedGenerationNames = previous ? previous.files.filter((name) => retainedPrefixes.some((prefix) => name.startsWith(prefix))) : [];
+  const retainedNames = uniqueStrings(retainedGenerationNames);
+  const inventoryNames = uniqueStrings([...desiredNames, ...retainedNames]);
+  const inventory = {
+    files: inventoryNames,
+    generation,
+    schemaVersion: 1
+  };
+  const inventoryFile = {
+    contentType: "application/json; charset=utf-8",
+    fileName: tileflowArtifactInventoryFileName,
+    source: `${JSON.stringify(inventory, null, 2)}
+`
+  };
+  const stagedFiles = [...files, inventoryFile];
+  const staleNames = (previous?.files ?? []).filter((name) => !inventoryNames.includes(name));
+  const affectedNames = uniqueStrings([
+    ...desiredNames,
+    ...staleNames,
+    tileflowArtifactInventoryFileName
+  ]);
+  const stageDir = await mkdtemp(resolve3(outDir, ".tileflow-stage-"));
+  const newDir = resolve3(stageDir, "new");
+  const backupDir = resolve3(stageDir, "backup");
+  const backedUp = /* @__PURE__ */ new Set();
+  const installed = /* @__PURE__ */ new Set();
+  try {
+    for (const file of stagedFiles) {
+      const stagePath = managedPath(newDir, file.fileName);
+      await mkdir2(dirname2(stagePath), { recursive: true });
+      await writeFileDurably(stagePath, file.source);
+    }
+    for (const name of affectedNames) {
+      await assertManagedTargetIsSafe(outDir, name);
+      const targetPath = managedPath(outDir, name);
+      if (!await isFile(targetPath)) continue;
+      const backupPath = managedPath(backupDir, name);
+      await mkdir2(dirname2(backupPath), { recursive: true });
+      await copyFile2(targetPath, backupPath);
+      backedUp.add(name);
+    }
+    const commitOrder = stagedFiles.map((file) => file.fileName).sort((left, right) => {
+      const leftRank = commitRank(left);
+      const rightRank = commitRank(right);
+      return leftRank - rightRank || compareCodeUnits2(left, right);
+    });
+    for (const name of commitOrder.filter(
+      (candidate) => candidate !== tileflowArtifactInventoryFileName
+    )) {
+      const sourcePath = managedPath(newDir, name);
+      const targetPath = managedPath(outDir, name);
+      await mkdir2(dirname2(targetPath), { recursive: true });
+      await rename(sourcePath, targetPath);
+      installed.add(name);
+    }
+    for (const name of staleNames) {
+      await removeManagedFile(managedPath(outDir, name));
+    }
+    const stagedInventoryPath = managedPath(newDir, tileflowArtifactInventoryFileName);
+    const inventoryPath = managedPath(outDir, tileflowArtifactInventoryFileName);
+    await rename(stagedInventoryPath, inventoryPath);
+    installed.add(tileflowArtifactInventoryFileName);
+  } catch (error) {
+    await rollbackManagedFiles(outDir, backupDir, affectedNames, backedUp, installed);
+    throw error;
+  } finally {
+    await rm2(stageDir, { force: true, recursive: true });
+  }
+}
+function getArtifactGeneration(files) {
+  const generations = getManagedGenerations(files.map((file) => file.fileName));
+  if (generations.length !== 1) {
+    throw new Error("A Tileflow artifact plan must contain exactly one content generation.");
+  }
+  return generations[0];
+}
+function getManagedGenerations(fileNames) {
+  return uniqueStrings(
+    fileNames.flatMap((fileName) => {
+      const match = /^generations\/([a-f0-9]{64})\//.exec(fileName);
+      return match?.[1] ? [match[1]] : [];
+    })
+  );
+}
+function commitRank(fileName) {
+  if (fileName === tileflowArtifactInventoryFileName) return 2;
+  if (fileName === "manifest.json") return 1;
+  return 0;
+}
+async function rollbackManagedFiles(outDir, backupDir, affectedNames, backedUp, installed) {
+  const rollbackErrors = [];
+  for (const name of [...affectedNames].reverse()) {
+    try {
+      const targetPath = managedPath(outDir, name);
+      if (installed.has(name) && !backedUp.has(name)) {
+        await removeManagedFile(targetPath);
+      }
+      if (backedUp.has(name)) {
+        await mkdir2(dirname2(targetPath), { recursive: true });
+        await copyFile2(managedPath(backupDir, name), targetPath);
+      }
+    } catch (error) {
+      rollbackErrors.push(error);
+    }
+  }
+  if (rollbackErrors.length > 0) {
+    throw new AggregateError(rollbackErrors, "Unable to restore the previous Tileflow generation.");
+  }
+}
+async function readTileflowArtifactInventory(outDir) {
+  const inventoryPath = managedPath(outDir, tileflowArtifactInventoryFileName);
+  let source;
+  try {
+    source = await readFile(inventoryPath, "utf8");
+  } catch (error) {
+    if (hasErrorCode2(error, "ENOENT")) return void 0;
+    throw error;
+  }
+  let candidate;
+  try {
+    candidate = JSON.parse(source);
+  } catch {
+    throw new Error(`Invalid Tileflow artifact inventory: ${inventoryPath}`);
+  }
+  if (!candidate || typeof candidate !== "object" || candidate.schemaVersion !== 1 || typeof candidate.generation !== "string" || !/^[a-f0-9]{64}$/.test(candidate.generation) || !Array.isArray(candidate.files) || candidate.files.length > 1e4) {
+    throw new Error(`Invalid Tileflow artifact inventory: ${inventoryPath}`);
+  }
+  const files = candidate.files;
+  if (!files.every((name) => typeof name === "string")) {
+    throw new Error(`Invalid Tileflow artifact inventory: ${inventoryPath}`);
+  }
+  try {
+    for (const name of files) assertTileflowArtifactFileName(name);
+  } catch {
+    throw new Error(`Invalid Tileflow artifact inventory: ${inventoryPath}`);
+  }
+  if (new Set(files).size !== files.length || files.includes(tileflowArtifactInventoryFileName)) {
+    throw new Error(`Invalid Tileflow artifact inventory: ${inventoryPath}`);
+  }
+  return {
+    files: [...files],
+    generation: candidate.generation,
+    schemaVersion: 1
+  };
+}
+async function assertManagedTargetIsSafe(outDir, fileName) {
+  assertSafeManagedFileName(fileName);
+  const rootStats = await lstat2(outDir);
+  if (rootStats.isSymbolicLink()) {
+    throw new Error(`Tileflow refuses to write through a symbolic link: ${outDir}`);
+  }
+  if (!rootStats.isDirectory()) {
+    throw new Error(`Tileflow artifact output is not a directory: ${outDir}`);
+  }
+  const segments = fileName.split("/");
+  let current = outDir;
+  for (let index = 0; index < segments.length; index += 1) {
+    current = resolve3(current, segments[index]);
+    try {
+      const stats = await lstat2(current);
+      if (stats.isSymbolicLink()) {
+        throw new Error(`Tileflow refuses to write through a symbolic link: ${fileName}`);
+      }
+      if (index < segments.length - 1 && !stats.isDirectory()) {
+        throw new Error(`Tileflow artifact parent is not a directory: ${fileName}`);
+      }
+      if (index === segments.length - 1 && !stats.isFile()) {
+        throw new Error(`Tileflow artifact target is not a file: ${fileName}`);
+      }
+    } catch (error) {
+      if (hasErrorCode2(error, "ENOENT")) return;
+      throw error;
+    }
+  }
+}
+async function prepareTileflowOutputDirectory(cwd, requestedOutDir) {
+  const logicalRoot = resolve3(cwd);
+  const logicalOutDir = resolve3(logicalRoot, requestedOutDir);
+  if (!isPathWithin(logicalRoot, logicalOutDir)) {
+    throw new Error(`Tileflow artifact output escapes its working directory: ${logicalOutDir}`);
+  }
+  const rootStats = await lstat2(logicalRoot);
+  if (!rootStats.isDirectory()) {
+    throw new Error(`Tileflow artifact working directory is not a directory: ${logicalRoot}`);
+  }
+  const rootDir = await realpath2(logicalRoot);
+  const relativeOutDir = relative2(logicalRoot, logicalOutDir);
+  const segments = relativeOutDir ? relativeOutDir.split(sep2) : [];
+  let current = rootDir;
+  for (const segment of segments) {
+    current = resolve3(current, segment);
+    let stats;
+    try {
+      stats = await lstat2(current);
+    } catch (error) {
+      if (!hasErrorCode2(error, "ENOENT")) throw error;
+      await mkdir2(current);
+      stats = await lstat2(current);
+    }
+    if (stats.isSymbolicLink()) {
+      throw new Error(`Tileflow refuses to write through a symbolic link: ${current}`);
+    }
+    if (!stats.isDirectory()) {
+      throw new Error(`Tileflow artifact output ancestor is not a directory: ${current}`);
+    }
+  }
+  const outDir = await realpath2(current);
+  const output = { outDir, rootDir };
+  await assertTileflowOutputDirectoryIsSafe(output);
+  return output;
+}
+async function assertTileflowOutputDirectoryIsSafe(output) {
+  if (!isPathWithin(output.rootDir, output.outDir)) {
+    throw new Error(`Tileflow artifact output escapes its working directory: ${output.outDir}`);
+  }
+  const stats = await lstat2(output.outDir);
+  if (stats.isSymbolicLink()) {
+    throw new Error(`Tileflow refuses to write through a symbolic link: ${output.outDir}`);
+  }
+  if (!stats.isDirectory()) {
+    throw new Error(`Tileflow artifact output is not a directory: ${output.outDir}`);
+  }
+  const canonicalOutDir = await realpath2(output.outDir);
+  if (canonicalOutDir !== output.outDir || !isPathWithin(output.rootDir, canonicalOutDir)) {
+    throw new Error(`Tileflow artifact output escapes its working directory: ${output.outDir}`);
+  }
+}
+function assertSafeManagedFileName(fileName) {
+  if (!fileName || fileName.includes("\\") || fileName.includes("\0") || fileName.startsWith("/") || fileName.endsWith("/") || fileName.split("/").some((segment) => !segment || segment === "." || segment === "..")) {
+    throw new Error(`Unsafe Tileflow artifact file name: ${fileName}`);
+  }
+}
+function assertTileflowArtifactFileName(fileName) {
+  assertSafeManagedFileName(fileName);
+  const logicalName = fileName.replace(/^generations\/[a-f0-9]{64}\//, "");
+  const styleMatch = /^styles\/([^/]+)\/([^/]+)\.json$/u.exec(logicalName);
+  const iconMatch = /^icons\/([^/]+)\/sprite(?:@2x)?\.(?:json|png)$/u.exec(logicalName);
+  if (fileName === "manifest.json" || fileName === tileflowMapBuildManifestFileName || styleMatch && tileflowMapIdSchema.safeParse(styleMatch[1]).success && tileflowThemeNameSchema.safeParse(styleMatch[2]).success || iconMatch && tileflowMapIdSchema.safeParse(iconMatch[1]).success || /^tilesets\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.pmtiles$/u.test(logicalName) || /^fonts\/[a-z0-9]+(?:-[a-z0-9]+)*-[a-f0-9]{64}\.(?:otf|ttf|woff2)$/.test(logicalName) || /^fonts\/licenses\/license-[a-f0-9]{64}\.txt$/.test(logicalName)) {
+    return;
+  }
+  throw new Error(`Unexpected Tileflow managed artifact file name: ${fileName}`);
+}
+function managedPath(root, fileName) {
+  assertSafeManagedFileName(fileName);
+  const path = resolve3(root, ...fileName.split("/"));
+  if (!isPathWithin(root, path)) {
+    throw new Error(`Unsafe Tileflow artifact file name: ${fileName}`);
+  }
+  return path;
+}
+async function writeFileDurably(path, source) {
+  const handle = await open2(path, "wx");
+  try {
+    await handle.writeFile(source);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function isFile(path) {
+  try {
+    return (await lstat2(path)).isFile();
+  } catch (error) {
+    if (hasErrorCode2(error, "ENOENT")) return false;
+    throw error;
+  }
+}
+async function removeManagedFile(path) {
+  try {
+    const stats = await lstat2(path);
+    if (!stats.isFile()) throw new Error(`Refusing to remove non-file artifact target: ${path}`);
+    await unlink(path);
+  } catch (error) {
+    if (!hasErrorCode2(error, "ENOENT")) throw error;
+  }
+}
+function hashArtifactGeneration(files) {
+  const hash = createHash("sha256");
+  for (const file of files) {
+    const source = typeof file.source === "string" ? Buffer.from(file.source, "utf8") : Buffer.from(file.source);
+    hash.update(`${file.fileName}\0${file.contentType}\0${source.byteLength}\0`, "utf8");
+    hash.update(source);
+  }
+  return hash.digest("hex");
+}
+function resolveAssetBaseUrl(options) {
+  if (options.assetBaseUrl !== void 0) return options.assetBaseUrl;
+  if (options.styleBaseUrl && !isRelativePublicUrl(options.styleBaseUrl)) {
+    return options.styleBaseUrl;
+  }
+  return "../..";
+}
+function isRelativePublicUrl(value) {
+  return !(value.startsWith("http://") || value.startsWith("https://") || value.startsWith("/") || value.startsWith("data:"));
+}
+function uniqueStrings(values) {
+  return [...new Set(values)].sort(compareCodeUnits2);
+}
+function hasErrorCode2(error, code) {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
+}
+function canonicalInputPath(path) {
+  const resolved = resolve3(path);
+  try {
+    return realpathSync2.native(resolved);
+  } catch {
+    try {
+      return resolve3(realpathSync2.native(dirname2(resolved)), resolved.split(/[\\/]/).at(-1));
+    } catch {
+      return resolved;
+    }
+  }
+}
+
+export {
+  prepareTileflowLocalTilesets,
+  tileflowArtifactSessionSchemaVersion,
+  createTileflowArtifactDiagnostics,
+  tileflowArtifactPlanSchemaVersion,
+  tileflowArtifactInventoryFileName,
+  TileflowHostedManifestOverwriteError,
+  TileflowLocalTilesetProductionError,
+  createTileflowManifest,
+  createTileflowStyle,
+  createTileflowStyles,
+  createTileflowArtifactPlan,
+  createTileflowBuildArtifacts,
+  getTileflowArtifactFiles,
+  createTileflowBuildProvenance,
+  createTileflowArtifactSession,
+  getTileflowWatchPaths,
+  isTileflowArtifactInputPath,
+  refreshTileflowArtifactSession,
+  writeTileflowBuildArtifacts,
+  disposeTileflowBuildArtifacts,
+  writeTileflowArtifactPlan,
+  assertNoLocalTilesetsForProduction,
+  assertTileflowSelfHostedManifestTarget
+};