@tileflow/dev 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   readBoundedTileflowResponse,
   renderTileflowPreviewHtml,
   resolveTileflowPreview
-} from "./chunk-MIGBHCXX.js";
+} from "./chunk-6OJICHB3.js";
 import {
   createTileflowArtifactStatus,
   createTileflowComparisonRequestHandler,
@@ -31,7 +31,7 @@ import {
   isTileflowRequestUrl,
   tileflowComparisonSchemaVersion,
   writeTileflowNodeResponse
-} from "./chunk-KH7CMHT3.js";
+} from "./chunk-XS5Q4IS2.js";
 import {
   TileflowHostedManifestOverwriteError,
   TileflowLocalTilesetProductionError,
@@ -56,7 +56,7 @@ import {
   tileflowArtifactSessionSchemaVersion,
   writeTileflowArtifactPlan,
   writeTileflowBuildArtifacts
-} from "./chunk-XTRHREXO.js";
+} from "./chunk-XXVI42UZ.js";
 import {
   inspectTileflowPmtiles,
   inspectTileflowPmtilesForLocalUse
@@ -79,8 +79,11 @@ import {
   getTileflowIconWatchPaths,
   iconFileExtensions,
   inspectTileflowIconCatalogs,
-  prepareTileflowCatalogIcons
-} from "./chunk-CENQR5Q2.js";
+  loadSharp,
+  packTileflowRenderedIcons,
+  prepareTileflowCatalogIcons,
+  readTileflowIconDirectory
+} from "./chunk-NUHSYLLS.js";
 import "./chunk-BL3FK4GO.js";
 import {
   TileflowStyleValidationError,
@@ -102,6 +105,577 @@ import {
   loadValidTileflowConfigWithInputs
 } from "./chunk-6MGFMKG3.js";
 import "./chunk-D4OE4ITL.js";
+
+// src/icon-composition.ts
+import { resolve as resolve3 } from "path";
+import { tileflowIconsLockfileName as tileflowIconsLockfileName2 } from "@tileflow/core";
+import {
+  collectTileflowIconSetReferences,
+  compareCodeUnits as compareCodeUnits2,
+  parseTileflowIconComposition,
+  parseTileflowIconsLockfile as parseTileflowIconsLockfile2,
+  TileflowIconSetError as TileflowIconSetError4,
+  tileflowIconPackageLimits as tileflowIconPackageLimits2
+} from "@tileflow/core";
+
+// src/icon-cache.ts
+import { hashTileflowIconPackageManifest as hashTileflowIconPackageManifest2 } from "@tileflow/core";
+import { constants } from "fs";
+import { lstat, mkdir, mkdtemp, open, readdir, realpath, rename, rm } from "fs/promises";
+import { homedir, platform } from "os";
+import { join, resolve } from "path";
+import {
+  TileflowIconSetError as TileflowIconSetError2,
+  tileflowIconSetPinSchema
+} from "@tileflow/core";
+
+// src/icon-artifact.ts
+import {
+  tileflowIconSpriteIndexSchema as indexSchema
+} from "@tileflow/core";
+import {
+  compareCodeUnits,
+  hashTileflowIconPackageManifest,
+  hashTileflowRenderedIconPixels,
+  parseTileflowIconJson,
+  sha256Hex,
+  TileflowIconSetError,
+  tileflowIconPackageLimits,
+  tileflowIconPackageManifestSchema
+} from "@tileflow/core";
+async function verifyTileflowIconArtifact(input) {
+  try {
+    const manifest = tileflowIconPackageManifestSchema.parse(input.manifest);
+    const contentHash = input.contentHash;
+    if (input.files.length !== 4 || new Set(input.files.map((file) => file.fileName)).size !== 4)
+      throw new Error("An artifact must contain exactly the four generated files");
+    const files = manifest.files.map((expected) => {
+      const source = input.files.find((file) => file.fileName === expected.name);
+      if (!source || source.contentType !== expected.contentType || source.source.byteLength !== expected.byteLength)
+        throw new Error("Generated file identity does not match the manifest");
+      return {
+        contentType: source.contentType,
+        fileName: source.fileName,
+        source: new Uint8Array(source.source)
+      };
+    });
+    if (await hashTileflowIconPackageManifest(manifest) !== contentHash)
+      throw new Error("Artifact manifest hash mismatch");
+    for (const [index, file] of files.entries()) {
+      if (await sha256Hex(file.source) !== manifest.files[index].sha256)
+        throw new Error(`Generated ${file.fileName} checksum mismatch`);
+    }
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    const oneIndex = indexSchema.parse(
+      parseTileflowIconJson(
+        decoder.decode(files[0].source),
+        tileflowIconPackageLimits.maxGeneratedFileBytes
+      )
+    );
+    const twoIndex = indexSchema.parse(
+      parseTileflowIconJson(
+        decoder.decode(files[2].source),
+        tileflowIconPackageLimits.maxGeneratedFileBytes
+      )
+    );
+    for (const index of [oneIndex, twoIndex]) {
+      const names = Object.keys(index).sort(compareCodeUnits);
+      if (names.length !== manifest.iconNames.length || names.some((name, ordinal) => name !== manifest.iconNames[ordinal]))
+        throw new Error("Sprite index does not exactly match the manifest icon names");
+    }
+    for (const [index, dimensions, ratio] of [
+      [oneIndex, manifest.sprites.oneX, 1],
+      [twoIndex, manifest.sprites.twoX, 2]
+    ]) {
+      const rectangles = Object.values(index);
+      for (const [ordinal, rect] of rectangles.entries()) {
+        if (rect.pixelRatio !== ratio || rect.x + rect.width > dimensions.width || rect.y + rect.height > dimensions.height)
+          throw new Error("Sprite rectangle is outside the atlas or has the wrong density");
+        for (const other of rectangles.slice(0, ordinal)) {
+          if (rect.x < other.x + other.width && other.x < rect.x + rect.width && rect.y < other.y + other.height && other.y < rect.y + rect.height)
+            throw new Error("Sprite rectangles must not overlap");
+        }
+      }
+    }
+    for (const name of manifest.iconNames) {
+      const one = oneIndex[name];
+      const two = twoIndex[name];
+      if (two.x !== one.x * 2 || two.y !== one.y * 2 || two.width !== one.width * 2 || two.height !== one.height * 2)
+        throw new Error("Sprite densities must have exactly doubled geometry");
+    }
+    const oneAtlas = await decodeAtlas(files[1].source, manifest.sprites.oneX);
+    const twoAtlas = await decodeAtlas(files[3].source, manifest.sprites.twoX);
+    const icons = [];
+    for (const [ordinal, id] of manifest.iconNames.entries()) {
+      const oneX = extractCell(oneAtlas, oneIndex[id]);
+      const twoX = extractCell(twoAtlas, twoIndex[id]);
+      const expected = manifest.renderedIcons[ordinal].pixelSha256;
+      if (await hashTileflowRenderedIconPixels({ ...oneX, pixelRatio: 1 }) !== expected.oneX || await hashTileflowRenderedIconPixels({ ...twoX, pixelRatio: 2 }) !== expected.twoX)
+        throw new Error(`Rendered pixels do not match the manifest for ${id}`);
+      icons.push({ id, oneX, twoX });
+    }
+    return { package: { contentHash, manifest, files }, icons };
+  } catch (cause) {
+    throw new TileflowIconSetError(
+      "ICON_PACKAGE_INTEGRITY",
+      "Generated icon artifact verification failed",
+      { cause }
+    );
+  }
+}
+async function decodeAtlas(bytes, dimensions) {
+  if ([137, 80, 78, 71, 13, 10, 26, 10].some((byte, index) => bytes[index] !== byte))
+    throw new Error("Expected PNG bytes");
+  const sharp = await loadSharp();
+  const image = sharp(bytes, {
+    failOn: "error",
+    limitInputPixels: tileflowIconPackageLimits.maxAtlasDimension ** 2
+  });
+  const metadata = await image.metadata();
+  if (metadata.format !== "png" || (metadata.pages ?? 1) !== 1 || metadata.width !== dimensions.width || metadata.height !== dimensions.height)
+    throw new Error("PNG geometry does not match the manifest");
+  const { data, info } = await image.ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  if (info.channels !== 4 || info.width !== dimensions.width || info.height !== dimensions.height || data.length !== dimensions.width * dimensions.height * 4)
+    throw new Error("Expected bounded RGBA atlas pixels");
+  return { ...dimensions, rgba: new Uint8Array(data) };
+}
+function extractCell(atlas, rect) {
+  const rgba = new Uint8Array(rect.width * rect.height * 4);
+  const rowBytes = rect.width * 4;
+  for (let row = 0; row < rect.height; row += 1) {
+    const start = ((rect.y + row) * atlas.width + rect.x) * 4;
+    rgba.set(atlas.rgba.subarray(start, start + rowBytes), row * rowBytes);
+  }
+  return { height: rect.height, width: rect.width, rgba };
+}
+
+// src/icon-cache.ts
+function getTileflowIconCacheDirectory(options = {}) {
+  const defaultRoot = platform() === "darwin" ? join(homedir(), "Library", "Caches") : platform() === "win32" ? process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local") : process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+  return join(
+    resolve(options.cacheRoot ?? process.env.TILEFLOW_ICON_CACHE_DIR ?? defaultRoot),
+    "tileflow",
+    "icons",
+    "v1"
+  );
+}
+async function loadTileflowIconSetArtifact(input, options = {}) {
+  const pin = tileflowIconSetPinSchema.parse(input);
+  if (await hashTileflowIconPackageManifest2(pin.manifest) !== pin.contentHash)
+    throw new TileflowIconSetError2("ICON_LOCK_INVALID", "Locked manifest hash mismatch");
+  let cacheFailure;
+  try {
+    return await readCached(pin, options);
+  } catch (cause) {
+    if (cause instanceof TileflowIconSetError2 && cause.code === "ICON_CACHE_UNSAFE") throw cause;
+    cacheFailure = cause;
+  }
+  if (options.offline) {
+    throw new TileflowIconSetError2(
+      isMissing(cacheFailure) ? "ICON_CACHE_MISS" : "ICON_PACKAGE_INTEGRITY",
+      "The exact verified icon artifact is unavailable offline; hydrate this pin explicitly",
+      { cause: cacheFailure }
+    );
+  }
+  const url = new URL(pin.spriteUrl);
+  const allowed = options.deliveryOrigins ?? ["https://api.tileflow.dev"];
+  if (!allowed.some((origin) => origin === url.origin && new URL(origin).href === `${origin}/`)) {
+    throw new TileflowIconSetError2(
+      "ICON_DOWNLOAD_FAILED",
+      "Icon artifact delivery origin is not trusted"
+    );
+  }
+  const files = [];
+  const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(3e4)]) : AbortSignal.timeout(3e4);
+  try {
+    for (const expected of pin.manifest.files) {
+      signal.throwIfAborted();
+      const fileUrl = `${pin.spriteUrl}${expected.name.slice("sprite".length)}`;
+      const response = await (options.fetch ?? globalThis.fetch)(fileUrl, {
+        method: "GET",
+        credentials: "omit",
+        redirect: "error",
+        headers: { Accept: expected.contentType, "Accept-Encoding": "identity" },
+        signal
+      });
+      if (response.status !== 200 || response.redirected || response.url && response.url !== fileUrl || !response.body)
+        throw new Error("Unexpected artifact response");
+      const type = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
+      const length = response.headers.get("content-length");
+      const encoding = response.headers.get("content-encoding")?.trim().toLowerCase();
+      const isIdentityEncoding = encoding === void 0 || encoding === "" || encoding === "identity";
+      if (type !== expected.contentType || length !== null && (!/^\d+$/u.test(length) || isIdentityEncoding && Number(length) !== expected.byteLength)) {
+        await response.body.cancel();
+        throw new Error("Artifact response headers do not match the manifest");
+      }
+      const reader = response.body.getReader();
+      const source = new Uint8Array(expected.byteLength);
+      let offset = 0;
+      try {
+        while (true) {
+          const chunk = await reader.read();
+          if (chunk.done) break;
+          if (offset + chunk.value.byteLength > source.byteLength)
+            throw new Error("Artifact response exceeds its exact byte length");
+          source.set(chunk.value, offset);
+          offset += chunk.value.byteLength;
+        }
+        if (offset !== source.byteLength) throw new Error("Artifact response was truncated");
+      } catch (cause) {
+        await reader.cancel().catch(() => void 0);
+        throw cause;
+      } finally {
+        reader.releaseLock();
+      }
+      files.push({ fileName: expected.name, contentType: expected.contentType, source });
+    }
+  } catch (cause) {
+    throw new TileflowIconSetError2("ICON_DOWNLOAD_FAILED", "Exact icon artifact download failed", {
+      cause
+    });
+  }
+  return storeTileflowIconSetArtifact(
+    pin,
+    { contentHash: pin.contentHash, manifest: pin.manifest, files },
+    options
+  );
+}
+async function storeTileflowIconSetArtifact(input, artifact, options = {}) {
+  const pin = tileflowIconSetPinSchema.parse(input);
+  if (await hashTileflowIconPackageManifest2(pin.manifest) !== pin.contentHash)
+    throw new TileflowIconSetError2("ICON_LOCK_INVALID", "Locked manifest hash mismatch");
+  if (artifact.contentHash !== pin.contentHash)
+    throw new TileflowIconSetError2(
+      "ICON_PACKAGE_INTEGRITY",
+      "Artifact does not match the selected pin"
+    );
+  const verified = await verifyTileflowIconArtifact({
+    contentHash: pin.contentHash,
+    manifest: pin.manifest,
+    files: artifact.files
+  });
+  const root = await safeCacheRoot(options, true);
+  const target = join(root, pin.contentHash);
+  const temporary = await mkdtemp(join(root, `.incoming-${pin.contentHash}-`));
+  try {
+    for (const file of verified.package.files) {
+      const handle = await open(join(temporary, file.fileName), "wx", 384);
+      try {
+        await handle.writeFile(file.source);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+    }
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      try {
+        await rename(temporary, target);
+        return verified;
+      } catch (cause) {
+        if (!hasCode(cause, "EEXIST") && !hasCode(cause, "ENOTEMPTY") && !hasCode(cause, "EPERM"))
+          throw cause;
+      }
+      try {
+        return await readCached(pin, options);
+      } catch (cause) {
+        if (cause instanceof TileflowIconSetError2 && cause.code === "ICON_CACHE_UNSAFE")
+          throw cause;
+      }
+      try {
+        await assertDirectory(target);
+        const retired = await mkdtemp(join(root, `.retired-${pin.contentHash}-`));
+        try {
+          await rename(target, join(retired, "entry"));
+        } catch (cause) {
+          if (!isMissing(cause)) throw cause;
+        } finally {
+          await rm(retired, { recursive: true, force: true });
+        }
+      } catch (cause) {
+        if (!isMissing(cause)) throw cause;
+      }
+    }
+    throw new TileflowIconSetError2(
+      "ICON_CACHE_UNSAFE",
+      "Concurrent cache repairs did not converge; retry this exact pin"
+    );
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}
+async function readCached(pin, options) {
+  const root = await safeCacheRoot(options, false);
+  const directory = join(root, pin.contentHash);
+  await assertDirectory(directory);
+  const entries = (await readdir(directory)).sort();
+  const expectedNames = pin.manifest.files.map((file) => file.name).sort();
+  if (entries.length !== 4 || entries.some((name, index) => name !== expectedNames[index]))
+    throw new TileflowIconSetError2(
+      "ICON_PACKAGE_INTEGRITY",
+      "Cache entry does not contain exactly four generated files"
+    );
+  const files = [];
+  for (const expected of pin.manifest.files) {
+    files.push({
+      fileName: expected.name,
+      contentType: expected.contentType,
+      source: await readSafeFile(join(directory, expected.name), expected.byteLength)
+    });
+  }
+  return verifyTileflowIconArtifact({ contentHash: pin.contentHash, manifest: pin.manifest, files });
+}
+async function safeCacheRoot(options, create) {
+  const root = getTileflowIconCacheDirectory(options);
+  const base = resolve(root, "..", "..", "..");
+  if (create) await mkdir(base, { recursive: true, mode: 448 });
+  await assertDirectory(base);
+  let current = await realpath(base);
+  for (const segment of ["tileflow", "icons", "v1"]) {
+    current = join(current, segment);
+    if (create)
+      await mkdir(current, { mode: 448 }).catch((cause) => {
+        if (!hasCode(cause, "EEXIST")) throw cause;
+      });
+    await assertDirectory(current);
+  }
+  return current;
+}
+async function assertDirectory(path) {
+  const entry = await lstat(path);
+  if (!entry.isDirectory() || entry.isSymbolicLink())
+    throw new TileflowIconSetError2(
+      "ICON_CACHE_UNSAFE",
+      "Icon cache paths must be directories, not symlinks"
+    );
+}
+async function readSafeFile(path, maximumBytes, exact = true) {
+  const entry = await lstat(path);
+  if (!entry.isFile() || entry.isSymbolicLink())
+    throw new TileflowIconSetError2(
+      "ICON_CACHE_UNSAFE",
+      "Icon files must be regular files, not symlinks"
+    );
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const opened = await handle.stat();
+    if (!opened.isFile() || opened.ino !== entry.ino || opened.dev !== entry.dev || opened.size > maximumBytes || exact && opened.size !== maximumBytes)
+      throw new TileflowIconSetError2(
+        "ICON_PACKAGE_INTEGRITY",
+        "Icon file size or identity changed"
+      );
+    const buffer = new Uint8Array(maximumBytes + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, null);
+      if (bytesRead === 0) break;
+      offset += bytesRead;
+    }
+    if (offset > maximumBytes || exact && offset !== maximumBytes)
+      throw new TileflowIconSetError2("ICON_PACKAGE_INTEGRITY", "Icon file byte length changed");
+    return buffer.slice(0, offset);
+  } finally {
+    await handle.close();
+  }
+}
+function hasCode(error, code) {
+  return error !== null && typeof error === "object" && "code" in error && error.code === code;
+}
+function isMissing(error) {
+  return hasCode(error, "ENOENT");
+}
+
+// src/icon-lockfile.ts
+import { lstat as lstat2, mkdir as mkdir2, mkdtemp as mkdtemp2, open as open2, rename as rename2, rm as rm2, rmdir } from "fs/promises";
+import { join as join2, resolve as resolve2 } from "path";
+import {
+  parseTileflowIconsLockfile,
+  serializeTileflowIconsLockfile,
+  TileflowIconSetError as TileflowIconSetError3,
+  tileflowIconsLockfileMaximumBytes,
+  tileflowIconsLockfileName
+} from "@tileflow/core";
+async function readTileflowIconsLockfile(baseDirectory, sources) {
+  const text = await readLockText(join2(resolve2(baseDirectory), tileflowIconsLockfileName));
+  if (text === null)
+    throw new TileflowIconSetError3(
+      "ICON_LOCK_MISSING",
+      "Missing tileflow.icons.lock.json; install exact icon set revisions explicitly"
+    );
+  return parseTileflowIconsLockfile(text, sources);
+}
+async function writeTileflowIconsLockfile(baseDirectory, input, expectedContents) {
+  const content = await serializeTileflowIconsLockfile(input);
+  const directory = resolve2(baseDirectory);
+  const destination = join2(directory, tileflowIconsLockfileName);
+  const guard = join2(directory, `.${tileflowIconsLockfileName}.writing`);
+  try {
+    await mkdir2(guard, { mode: 448 });
+  } catch (cause) {
+    throw new TileflowIconSetError3(
+      "ICON_LOCK_CONFLICT",
+      "Another icon lock writer is active; a stale .writing guard may be removed only after confirming its writer has exited",
+      { cause }
+    );
+  }
+  let temporary;
+  try {
+    const actual = await readLockText(destination);
+    if (actual !== expectedContents)
+      throw new TileflowIconSetError3(
+        "ICON_LOCK_CONFLICT",
+        "Icon lock changed since it was read; reload and retry without discarding other pins"
+      );
+    if (actual === content) return;
+    temporary = await mkdtemp2(join2(directory, ".tileflow-icons-lock-"));
+    const file = join2(temporary, "lock");
+    const handle = await open2(file, "wx", 384);
+    try {
+      await handle.writeFile(content, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    if (await readLockText(destination) !== actual)
+      throw new TileflowIconSetError3(
+        "ICON_LOCK_CONFLICT",
+        "Icon lock changed while preparing an update"
+      );
+    await rename2(file, destination);
+  } finally {
+    if (temporary) await rm2(temporary, { recursive: true, force: true });
+    await rmdir(guard);
+  }
+}
+async function readLockText(path) {
+  try {
+    const entry = await lstat2(path);
+    if (!entry.isFile() || entry.isSymbolicLink())
+      throw new TileflowIconSetError3(
+        "ICON_LOCK_INVALID",
+        "The icon lock must be a regular file, not a symlink"
+      );
+    return new TextDecoder("utf-8", { fatal: true }).decode(
+      await readSafeFile(path, tileflowIconsLockfileMaximumBytes, false)
+    );
+  } catch (cause) {
+    if (cause !== null && typeof cause === "object" && "code" in cause && cause.code === "ENOENT")
+      return null;
+    throw cause;
+  }
+}
+
+// src/icon-composition.ts
+async function composeTileflowIconSources(input, options) {
+  const sources = structuredClone(input);
+  const references = collectTileflowIconSetReferences(sources);
+  const lock = references.length > 0 ? options.lock === void 0 ? await readTileflowIconsLockfile(options.baseDirectory ?? options.cwd, sources) : await parseTileflowIconsLockfile2(options.lock, sources) : await parseTileflowIconsLockfile2(options.lock ?? { lockfileVersion: 1, sets: {} }, sources);
+  const contributors = new Array(sources.length);
+  const winners = /* @__PURE__ */ new Map();
+  const watchPaths = /* @__PURE__ */ new Set();
+  if (references.length > 0 && options.lock === void 0)
+    watchPaths.add(resolve3(options.baseDirectory ?? options.cwd, tileflowIconsLockfileName2));
+  let reused;
+  let pixelBytes = 0;
+  let localSourceBytes = 0;
+  for (let ordinal = sources.length - 1; ordinal >= 0; ordinal -= 1) {
+    const source = sources[ordinal];
+    if (typeof source === "object" && source.kind === "icon-set") {
+      const pin = lock.sets[source.reference];
+      const loaded = await loadTileflowIconSetArtifact(pin, options);
+      contributors[ordinal] = {
+        kind: "icon-set",
+        reference: source.reference,
+        teamId: pin.teamId,
+        setId: pin.setId,
+        versionId: pin.versionId,
+        version: pin.version,
+        packageId: pin.packageId,
+        contentHash: pin.contentHash,
+        iconIds: [...pin.manifest.iconNames]
+      };
+      if (sources.length === 1) reused = loaded.package;
+      for (const icon of loaded.icons) {
+        if (winners.has(icon.id)) continue;
+        const pixels = pin.manifest.renderedIcons.find(
+          (entry) => entry.name === icon.id
+        ).pixelSha256;
+        addWinner(ordinal, icon, {
+          kind: "rendered-icon",
+          id: icon.id,
+          width: icon.oneX.width,
+          height: icon.oneX.height,
+          pixelSha256: { ...pixels }
+        });
+      }
+    } else {
+      const directory = await readTileflowIconDirectory(source, {
+        cwd: options.cwd,
+        baseDirectory: options.baseDirectory ?? options.cwd,
+        target: options.target ?? "local"
+      });
+      if (directory.watchPath) watchPaths.add(directory.watchPath);
+      contributors[ordinal] = typeof source === "string" ? { kind: "local", iconIds: directory.iconIds } : { kind: "package", package: source.package, iconIds: directory.iconIds };
+      const selected = directory.iconIds.filter((id) => !winners.has(id));
+      if (winners.size + selected.length > tileflowIconPackageLimits2.maxIconCount)
+        throw new TileflowIconSetError4(
+          "ICON_COMPOSITION_INVALID",
+          "Composed icon set exceeds 256 effective icons"
+        );
+      for (const item of await directory.render(selected)) {
+        localSourceBytes += item.sourceBytes;
+        if (localSourceBytes > tileflowIconPackageLimits2.maxSourceBytes)
+          throw new TileflowIconSetError4(
+            "ICON_COMPOSITION_INVALID",
+            "Effective local icon originals exceed the source-byte limit"
+          );
+        addWinner(ordinal, item.icon, item.identity);
+      }
+    }
+  }
+  const sorted = [...winners.values()].sort(
+    (left, right) => compareCodeUnits2(left.icon.id, right.icon.id)
+  );
+  const iconPackage = sorted.length ? reused ?? await packTileflowRenderedIcons(sorted.map((winner) => winner.icon)) : null;
+  const composition = references.length && iconPackage ? parseTileflowIconComposition({
+    format: "tileflow-icon-composition-v1",
+    compositionVersion: 1,
+    packageHash: iconPackage.contentHash,
+    contributors,
+    winners: sorted.map(({ ordinal, icon }, index) => ({
+      id: icon.id,
+      contributor: ordinal,
+      width: icon.oneX.width,
+      height: icon.oneX.height,
+      pixelSha256: iconPackage.manifest.renderedIcons[index].pixelSha256
+    }))
+  }) : null;
+  const previous = /* @__PURE__ */ new Map();
+  const replacements = [];
+  for (const [ordinal, contributor] of contributors.entries()) {
+    for (const id of contributor.iconIds) {
+      const replaced = previous.get(id);
+      if (replaced !== void 0) replacements.push({ id, replaced, winner: ordinal });
+      previous.set(id, ordinal);
+    }
+  }
+  return {
+    package: iconPackage,
+    composition,
+    sourceIdentities: sorted.map((winner) => winner.identity),
+    replacements,
+    watchPaths: [...watchPaths].sort(compareCodeUnits2)
+  };
+  function addWinner(ordinal, icon, identity) {
+    pixelBytes += icon.oneX.rgba.byteLength + icon.twoX.rgba.byteLength;
+    const maximumPixelBytes = (tileflowIconPackageLimits2.maxAtlasDimension ** 2 + (tileflowIconPackageLimits2.maxAtlasDimension / 2) ** 2) * 4;
+    if (winners.size >= tileflowIconPackageLimits2.maxIconCount || pixelBytes > maximumPixelBytes)
+      throw new TileflowIconSetError4(
+        "ICON_COMPOSITION_INVALID",
+        "Composed rendered cells exceed the final sprite capacity"
+      );
+    winners.set(icon.id, { ordinal, icon, identity });
+  }
+}
 export {
   TileflowConfigInspectionError,
   TileflowFontCompilationError,
@@ -117,6 +691,7 @@ export {
   assertValidTileflowStyle,
   bindTileflowStyleFontBundle,
   compileTileflowIconPackages,
+  composeTileflowIconSources,
   createTileflowArtifactDiagnostics,
   createTileflowArtifactPlan,
   createTileflowArtifactSession,
@@ -141,6 +716,7 @@ export {
   getTileflowAssetBasePath,
   getTileflowAssetFileName,
   getTileflowFontWatchPaths,
+  getTileflowIconCacheDirectory,
   getTileflowIconWatchPaths,
   getTileflowMapNames,
   getTileflowRequestPath,
@@ -159,15 +735,19 @@ export {
   joinTileflowPublicUrl,
   loadTileflowConfig,
   loadTileflowConfigWithInputs,
+  loadTileflowIconSetArtifact,
   loadValidTileflowConfig,
   loadValidTileflowConfigWithInputs,
   normalizeTileflowBasePath,
   normalizeTileflowLandmarkManifest,
+  packTileflowRenderedIcons,
   prepareTileflowCatalogIcons,
   prepareTileflowLocalTilesets,
   prepareTileflowStyleFonts,
   readBoundedTileflowJsonResponse,
   readBoundedTileflowResponse,
+  readTileflowIconDirectory,
+  readTileflowIconsLockfile,
   refreshTileflowArtifactSession,
   renderTileflowPreviewHtml,
   replaceTileflowStyleFontSources,
@@ -176,13 +756,16 @@ export {
   sanitizeDiagnosticSecrets,
   sanitizeTileflowInspectableValue,
   serializeTileflowCommandDocument,
+  storeTileflowIconSetArtifact,
   tileflowArtifactInventoryFileName,
   tileflowArtifactPlanSchemaVersion,
   tileflowArtifactSessionSchemaVersion,
   tileflowCommandDocumentSchemaVersion,
   tileflowComparisonSchemaVersion,
   validateTileflowStyle,
+  verifyTileflowIconArtifact,
   writeTileflowArtifactPlan,
   writeTileflowBuildArtifacts,
+  writeTileflowIconsLockfile,
   writeTileflowNodeResponse
 };