@tileflow/dev 0.1.0-alpha.25 → 0.1.0-alpha.27

package/dist/{chunk-D2QWYYIF.js → chunk-EJPVUSX4.js}

@@ -8,7 +8,10 @@ import { readdir as readdir2, readFile, realpath as realpath3, stat } from "fs/p
 import { extname, isAbsolute as isAbsolute2, relative as relative2, resolve as resolvePath, sep as sep2 } from "path";
 import { SaxesParser } from "saxes";
 import {
+  assertTileflowIconLayoutBounds as assertTileflowIconLayoutBounds2,
   collectTileflowIconSetReferences as collectTileflowIconSetReferences2,
+  tileflowIconAuthorMetadataSchema,
+  tileflowIconMetadataFileName,
   TileflowIconSetError as TileflowIconSetError5,
   tileflowIconsLockfileName as tileflowIconsLockfileName3,
   tileflowIconSpriteIndexSchema
@@ -18,7 +21,7 @@ import {
   hashTileflowRenderedIconPixels as hashTileflowRenderedIconPixels3,
   parseResolvedTileflowMap,
   parseTileflowIconJson as parseTileflowIconJson2,
-  serializeCanonicalJson as serializeCanonicalJson2,
+  serializeCanonicalJson as serializeCanonicalJson3,
   sha256Hex as sha256Hex3,
   tileflowIconIdPattern,
   tileflowIconPackageLimits as tileflowIconPackageLimits4
@@ -33,8 +36,8 @@ import {
   compareCodeUnits as compareCodeUnits3,
   parseTileflowIconComposition,
   parseTileflowIconsLockfile as parseTileflowIconsLockfile2,
-  TileflowIconSetError as TileflowIconSetError4,
-  tileflowIconPackageLimits as tileflowIconPackageLimits3
+  tileflowIconPackageLimits as tileflowIconPackageLimits3,
+  TileflowIconSetError as TileflowIconSetError4
 } from "@tileflow/core";
 
 // src/icon-cache.ts
@@ -53,21 +56,28 @@ import {
   tileflowIconSpriteIndexSchema as indexSchema
 } from "@tileflow/core";
 import {
+  assertTileflowSdfPixels as assertTileflowSdfPixels2,
   compareCodeUnits as compareCodeUnits2,
   hashTileflowIconPackageManifest as hashTileflowIconPackageManifest2,
   hashTileflowRenderedIconPixels as hashTileflowRenderedIconPixels2,
   parseTileflowIconJson,
+  readTileflowIconLayout,
+  scaleTileflowIconLayout as scaleTileflowIconLayout2,
+  serializeCanonicalJson as serializeCanonicalJson2,
   sha256Hex as sha256Hex2,
-  TileflowIconSetError,
   tileflowIconPackageLimits as tileflowIconPackageLimits2,
-  tileflowIconPackageManifestSchema as tileflowIconPackageManifestSchema2
+  tileflowIconPackageManifestSchema as tileflowIconPackageManifestSchema2,
+  TileflowIconSetError
 } from "@tileflow/core";
 
 // src/icon-sprite.ts
 import {
+  assertTileflowIconLayoutBounds,
+  assertTileflowSdfPixels,
   compareCodeUnits,
   hashTileflowIconPackageManifest,
   hashTileflowRenderedIconPixels,
+  scaleTileflowIconLayout,
   serializeCanonicalJson,
   sha256Hex,
   tileflowIconIdSchema,
@@ -77,22 +87,41 @@ import {
 async function packTileflowRenderedIcons(input) {
   const icons = [...input].sort((left, right) => compareCodeUnits(left.id, right.id));
   if (icons.length < 1 || icons.length > tileflowIconPackageLimits.maxIconCount || new Set(icons.map((icon) => icon.id)).size !== icons.length)
-    throw new Error("Expected 1 through 256 unique rendered icons");
+    throw new Error(
+      `Expected 1 through ${tileflowIconPackageLimits.maxIconCount} unique rendered icons`
+    );
   const renderedIcons = [];
   for (const icon of icons) {
     tileflowIconIdSchema.parse(icon.id);
+    if (icon.layout) assertTileflowIconLayoutBounds(icon.layout, icon.oneX.width, icon.oneX.height);
+    if (icon.appearance) {
+      assertTileflowSdfPixels({ ...icon.oneX, pixelRatio: 1 });
+      assertTileflowSdfPixels({ ...icon.twoX, pixelRatio: 2 });
+    }
     if (icon.twoX.width !== icon.oneX.width * 2 || icon.twoX.height !== icon.oneX.height * 2)
       throw new Error("Rendered density geometry must double exactly");
     renderedIcons.push({
       name: icon.id,
+      ...icon.appearance ? { appearance: icon.appearance } : {},
+      ...icon.layout ? { layout: icon.layout } : {},
       pixelSha256: {
         oneX: await hashTileflowRenderedIconPixels({ ...icon.oneX, pixelRatio: 1 }),
         twoX: await hashTileflowRenderedIconPixels({ ...icon.twoX, pixelRatio: 2 })
       }
     });
   }
-  const oneX = icons.map((icon) => ({ ...icon.oneX, name: icon.id }));
-  const twoX = icons.map((icon) => ({ ...icon.twoX, name: icon.id }));
+  const oneX = icons.map((icon) => ({
+    ...icon.oneX,
+    name: icon.id,
+    appearance: icon.appearance,
+    layout: icon.layout
+  }));
+  const twoX = icons.map((icon) => ({
+    ...icon.twoX,
+    name: icon.id,
+    appearance: icon.appearance,
+    layout: icon.layout
+  }));
   const layoutOneX = createSpriteLayout(oneX, 1);
   const layoutTwoX = createSpriteLayout(twoX, 2);
   if (layoutTwoX.width !== layoutOneX.width * 2 || layoutTwoX.height !== layoutOneX.height * 2)
@@ -123,7 +152,7 @@ async function packTileflowRenderedIcons(input) {
   ];
   assertGeneratedFileLimits(files);
   const manifest = tileflowIconPackageManifestSchema.parse({
-    format: "tileflow-icon-package-v1",
+    format: icons.some((icon) => icon.appearance || icon.layout) ? "tileflow-icon-package-v2" : "tileflow-icon-package-v1",
     files: await Promise.all(
       files.map(async (file) => ({
         name: file.fileName,
@@ -174,7 +203,15 @@ function createSpriteLayout(icons, pixelRatio) {
       const placement = placements[ordinal];
       return [
         icon.name,
-        { height: icon.height, pixelRatio, width: icon.width, x: placement.left, y: placement.top }
+        {
+          height: icon.height,
+          pixelRatio,
+          width: icon.width,
+          x: placement.left,
+          y: placement.top,
+          ...icon.appearance ? { sdf: true, tileflow: icon.appearance } : {},
+          ...icon.layout ? scaleTileflowIconLayout(icon.layout, pixelRatio) : {}
+        }
       ];
     })
   );
@@ -279,6 +316,16 @@ async function verifyTileflowIconArtifact(input) {
     for (const name of manifest.iconNames) {
       const one = oneIndex[name];
       const two = twoIndex[name];
+      const declared = manifest.renderedIcons.find((icon) => icon.name === name).appearance;
+      const declaredLayout = manifest.renderedIcons.find((icon) => icon.name === name).layout;
+      const oneLayout = readTileflowIconLayout(one);
+      const twoLayout = readTileflowIconLayout(two);
+      if (serializeCanonicalJson2(oneLayout ?? null) !== serializeCanonicalJson2(declaredLayout ?? null) || serializeCanonicalJson2(twoLayout ?? null) !== serializeCanonicalJson2(oneLayout ? scaleTileflowIconLayout2(oneLayout, 2) : null))
+        throw new Error(
+          "Sprite layout must match the manifest and scale exactly between densities"
+        );
+      if (serializeCanonicalJson2(one.tileflow ?? null) !== serializeCanonicalJson2(two.tileflow ?? null) || serializeCanonicalJson2(one.tileflow ?? null) !== serializeCanonicalJson2(declared ?? null))
+        throw new Error("Sprite appearance must match at both densities and in the manifest");
       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");
     }
@@ -291,7 +338,19 @@ async function verifyTileflowIconArtifact(input) {
       const expected = manifest.renderedIcons[ordinal].pixelSha256;
       if (await hashTileflowRenderedIconPixels2({ ...oneX, pixelRatio: 1 }) !== expected.oneX || await hashTileflowRenderedIconPixels2({ ...twoX, pixelRatio: 2 }) !== expected.twoX)
         throw new Error(`Rendered pixels do not match the manifest for ${id}`);
-      icons.push({ id, oneX, twoX });
+      const appearance = oneIndex[id].tileflow;
+      if (appearance) {
+        assertTileflowSdfPixels2({ ...oneX, pixelRatio: 1 });
+        assertTileflowSdfPixels2({ ...twoX, pixelRatio: 2 });
+      }
+      const layout = readTileflowIconLayout(oneIndex[id]);
+      icons.push({
+        id,
+        oneX,
+        twoX,
+        ...appearance ? { appearance } : {},
+        ...layout ? { layout } : {}
+      });
     }
     return { package: { contentHash, manifest, files }, icons };
   } catch (cause) {
@@ -702,7 +761,9 @@ async function composeTileflowIconSources(input, options) {
             id: icon.id,
             width: icon.oneX.width,
             height: icon.oneX.height,
-            pixelSha256: { ...pixels }
+            pixelSha256: { ...pixels },
+            ...icon.appearance ? { appearance: icon.appearance } : {},
+            ...icon.layout ? { layout: icon.layout } : {}
           },
           null
         );
@@ -731,7 +792,7 @@ async function composeTileflowIconSources(input, options) {
       if (winners.size + selected.length > tileflowIconPackageLimits3.maxIconCount)
         throw new TileflowIconSetError4(
           "ICON_COMPOSITION_INVALID",
-          "Composed icon set exceeds 256 effective icons"
+          `Composed icon set exceeds ${tileflowIconPackageLimits3.maxIconCount} effective icons`
         );
       for (const item of await directory.render(selected)) {
         localSourceBytes += item.sourceBytes;
@@ -749,8 +810,8 @@ async function composeTileflowIconSources(input, options) {
   );
   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,
+    format: sorted.some((winner) => winner.icon.appearance || winner.icon.layout) ? "tileflow-icon-composition-v2" : "tileflow-icon-composition-v1",
+    compositionVersion: sorted.some((winner) => winner.icon.appearance || winner.icon.layout) ? 2 : 1,
     packageHash: iconPackage.contentHash,
     contributors,
     winners: sorted.map(({ ordinal, icon }, index) => ({
@@ -758,7 +819,9 @@ async function composeTileflowIconSources(input, options) {
       contributor: ordinal,
       width: icon.oneX.width,
       height: icon.oneX.height,
-      pixelSha256: iconPackage.manifest.renderedIcons[index].pixelSha256
+      pixelSha256: iconPackage.manifest.renderedIcons[index].pixelSha256,
+      ...icon.appearance ? { appearance: icon.appearance } : {},
+      ...icon.layout ? { layout: icon.layout } : {}
     }))
   }) : null;
   const previous = /* @__PURE__ */ new Map();
@@ -801,6 +864,90 @@ function isPathInside(root, candidate) {
   return pathFromRoot === "" || !isAbsolute(pathFromRoot) && pathFromRoot !== ".." && !pathFromRoot.startsWith(`..${sep}`);
 }
 
+// src/icon-distance.ts
+var infinity = 1e20;
+function createIconDistanceField(rgba, width, height, ratio) {
+  if (width !== 24 * ratio || height !== 24 * ratio || rgba.length !== width * height * 4)
+    throw new Error("SDF icons require a 24px logical cell at each density.");
+  const outer = new Float64Array(width * height);
+  const inner = new Float64Array(width * height);
+  let occupied = false;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const index = y * width + x;
+      const alpha = rgba[index * 4 + 3] / 255;
+      if (alpha && (x < 6 * ratio || y < 6 * ratio || x >= width - 6 * ratio || y >= height - 6 * ratio))
+        throw new Error(
+          "SDF icons require six transparent pixels of padding inside the 24px cell. Add a transparent border to the source."
+        );
+      occupied ||= alpha > 0;
+      outer[index] = alpha === 1 ? 0 : alpha === 0 ? infinity : Math.max(0, 0.5 - alpha) ** 2;
+      inner[index] = alpha === 1 ? infinity : alpha === 0 ? 0 : Math.max(0, alpha - 0.5) ** 2;
+    }
+  }
+  if (!occupied) throw new Error("An SDF silhouette must contain visible pixels.");
+  transform(outer, width, height);
+  transform(inner, width, height);
+  const result = new Uint8Array(rgba.length);
+  for (let i = 0; i < outer.length; i++) {
+    const distance = Math.sqrt(outer[i]) - Math.sqrt(inner[i]);
+    const alpha = Math.round(255 * Math.max(0, Math.min(1, 0.75 - distance / (8 * ratio))));
+    result.set([255, 255, 255, alpha], i * 4);
+  }
+  return result;
+}
+function transform(grid, width, height) {
+  const size = Math.max(width, height);
+  const samples = new Float64Array(size);
+  const result = new Float64Array(size);
+  const sites = new Uint32Array(size);
+  const bounds = new Float64Array(size + 1);
+  const line = (length) => {
+    let count = 0;
+    sites[0] = 0;
+    bounds[0] = -infinity;
+    bounds[1] = infinity;
+    for (let position = 1; position < length; position++) {
+      let intersection;
+      do {
+        const site = sites[count];
+        intersection = (samples[position] + position ** 2 - samples[site] - site ** 2) / (2 * (position - site));
+        if (intersection > bounds[count]) break;
+        count--;
+      } while (count >= 0);
+      count++;
+      sites[count] = position;
+      bounds[count] = intersection;
+      bounds[count + 1] = infinity;
+    }
+    count = 0;
+    for (let position = 0; position < length; position++) {
+      while (bounds[count + 1] < position) count++;
+      result[position] = (position - sites[count]) ** 2 + samples[sites[count]];
+    }
+  };
+  for (let x = 0; x < width; x++) {
+    for (let y = 0; y < height; y++) samples[y] = grid[y * width + x];
+    line(height);
+    for (let y = 0; y < height; y++) grid[y * width + x] = result[y];
+  }
+  for (let y = 0; y < height; y++) {
+    samples.set(grid.subarray(y * width, (y + 1) * width));
+    line(width);
+    grid.set(result.subarray(0, width), y * width);
+  }
+}
+
+// src/icon-preview.ts
+import { renderTileflowIconAtlasPixels } from "@tileflow/core";
+async function renderTileflowIconAtlasPreview(source, index) {
+  if (!Object.values(index).some((entry) => entry.sdf)) return source;
+  const sharp = await loadSharp();
+  const { data, info } = await sharp(source, { limitInputPixels: 2048 * 2048 }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  const rendered = renderTileflowIconAtlasPixels(data, info.width, info.height, index);
+  return sharp(rendered, { raw: { width: info.width, height: info.height, channels: 4 } }).png().toBuffer();
+}
+
 // src/icons.ts
 var TileflowIconCompilationError = class extends Error {
   code = "ICON_INVALID";
@@ -838,9 +985,15 @@ async function compileTileflowIconPackages(project, options) {
     if (!composed?.package) {
       throw new Error(`Missing compiled icon package for map ${request.mapName}`);
     }
+    const appearances = Object.fromEntries(
+      composed.package.manifest.renderedIcons.flatMap(
+        (icon) => icon.appearance ? [[icon.name, icon.appearance]] : []
+      )
+    );
     return [
       {
         iconIds: composed.package.manifest.iconNames,
+        ...Object.keys(appearances).length ? { appearances } : {},
         label: request.mapName,
         mapName: request.mapName,
         packageHash: composed.package.contentHash
@@ -912,6 +1065,8 @@ async function inspectTileflowIconCatalogs(project, options) {
             }
             return {
               id: winner.id,
+              ...manifestIcon.appearance ? { appearance: manifestIcon.appearance } : {},
+              ...manifestIcon.layout ? { layout: manifestIcon.layout } : {},
               rendered: {
                 oneX: {
                   atlas: atlasRectangle(oneXAtlas),
@@ -1036,7 +1191,13 @@ async function prepareTileflowCatalogIcons(project, options) {
     const iconPackage = packagesByHash.get(binding.packageHash);
     if (!iconPackage) throw new Error(`Missing compiled icon package for map ${binding.mapName}`);
     const spriteUrl = joinUrl(options.assetBaseUrl, `icons/${binding.mapName}/sprite`);
-    mapAssets[binding.mapName] = { icons: { ids: binding.iconIds, sprite: spriteUrl } };
+    mapAssets[binding.mapName] = {
+      icons: {
+        ids: binding.iconIds,
+        sprite: spriteUrl,
+        ...binding.appearances ? { appearances: binding.appearances } : {}
+      }
+    };
     mapIconSources[binding.mapName] = compiled.sourceIdentities[binding.mapName] ?? [];
     const composition = compiled.compositions[binding.mapName];
     if (composition) mapIconCompositions[binding.mapName] = composition;
@@ -1092,7 +1253,7 @@ function getMapIconRequests(project, mapNames) {
     const mapConfig = project.maps[mapName];
     if (!mapConfig) throw new Error(`Unknown Tileflow map: ${mapName}`);
     const sources = parseResolvedTileflowMap(mapConfig).icons ?? [];
-    return { mapName, sequenceKey: serializeCanonicalJson2(sources), sources };
+    return { mapName, sequenceKey: serializeCanonicalJson3(sources), sources };
   });
 }
 function uniqueSequences(requests) {
@@ -1161,6 +1322,10 @@ async function inspectIconSource(directory, target, issues) {
   entries.sort((left, right) => compareCodeUnits4(left.name, right.name));
   const candidates = [];
   const names = /* @__PURE__ */ new Set();
+  let metadata = {
+    schemaVersion: 1,
+    icons: {}
+  };
   for (const entry of entries) {
     const entryPath = resolvePath(directory.realPath, entry.name);
     const path = `${directory.configPath}/${entry.name}`;
@@ -1188,6 +1353,24 @@ async function inspectIconSource(directory, target, issues) {
       continue;
     }
     const extension = extname(entry.name).toLowerCase();
+    if (entry.name === tileflowIconMetadataFileName) {
+      try {
+        if (entryStat.size > tileflowIconPackageLimits4.maxSourceFileBytes)
+          throw new Error("Icon metadata exceeds its byte limit");
+        metadata = tileflowIconAuthorMetadataSchema.parse(
+          parseTileflowIconJson2(
+            await readFile(realEntryPath, "utf8"),
+            tileflowIconPackageLimits4.maxSourceFileBytes
+          )
+        );
+      } catch (error) {
+        issues.push({
+          path,
+          message: `Invalid icon metadata: ${error instanceof Error ? error.message : String(error)}`
+        });
+      }
+      continue;
+    }
     if (!iconFileExtensions.has(extension)) {
       continue;
     }
@@ -1225,6 +1408,13 @@ async function inspectIconSource(directory, target, issues) {
     });
   }
   candidates.sort((left, right) => compareCodeUnits4(left.name, right.name));
+  for (const id of Object.keys(metadata.icons)) {
+    if (!names.has(id))
+      issues.push({
+        path: `${directory.configPath}/${tileflowIconMetadataFileName}`,
+        message: `Icon metadata references unknown ID "${id}"`
+      });
+  }
   if (candidates.length === 0) {
     issues.push({
       message: "No supported .svg, .png, .jpg, .jpeg, or .webp icon files were found",
@@ -1245,7 +1435,10 @@ async function inspectIconSource(directory, target, issues) {
       if (target === "hosted" && extname(candidate.fileName).toLowerCase() === ".svg") {
         validateHostedSvg(source, displayPath);
       }
+      const declared = metadata.icons[candidate.name];
       icons.push({
+        ...declared?.representation === "sdf" ? { appearance: { representation: declared.representation, defaults: declared.defaults } } : {},
+        ...declared?.layout ? { layout: declared.layout } : {},
         displayPath,
         fileName: candidate.fileName,
         format: candidate.format,
@@ -1300,8 +1493,27 @@ async function renderIcon(icon, dimensions, pixelRatio) {
   if (info.channels !== 4 || info.width !== targetWidth || info.height !== targetHeight) {
     throw new Error(`Rendered icon ${icon.fileName} did not produce canonical RGBA pixels`);
   }
-  const rgba = new Uint8Array(data);
-  const png = await sharp(data, {
+  let rgba;
+  try {
+    if (icon.appearance && icon.kind === "pattern")
+      throw new Error("SDF metadata is only supported for icons, not patterns.");
+    if (icon.layout) {
+      if (icon.kind === "pattern")
+        throw new Error("Text-fitting metadata is only supported for icons, not patterns.");
+      assertTileflowIconLayoutBounds2(
+        icon.layout,
+        info.width / pixelRatio,
+        info.height / pixelRatio
+      );
+    }
+    rgba = icon.appearance ? createIconDistanceField(new Uint8Array(data), info.width, info.height, pixelRatio) : new Uint8Array(data);
+  } catch (error) {
+    throw new Error(
+      `${icon.displayPath}: ${error instanceof Error ? error.message : "Invalid icon capabilities"}`,
+      { cause: error }
+    );
+  }
+  const png = await sharp(rgba, {
     raw: { channels: 4, height: info.height, width: info.width }
   }).png({ adaptiveFiltering: false, compressionLevel: 9, palette: false }).toBuffer();
   return { height: info.height, png, rgba, width: info.width };
@@ -1500,7 +1712,9 @@ async function renderIconInputs(inputs) {
           width: twoX.width
         })
       },
-      sourceSha256: await sha256Hex3(icon.source),
+      sourceSha256: icon.appearance || icon.layout ? await sha256Hex3(
+        `tileflow-icon-source-v2\0${await sha256Hex3(icon.source)}\0${serializeCanonicalJson3({ ...icon.appearance ? { appearance: icon.appearance } : {}, ...icon.layout ? { layout: icon.layout } : {} })}`
+      ) : await sha256Hex3(icon.source),
       twoX
     };
   });
@@ -1522,7 +1736,10 @@ async function readTileflowIconDirectory(source, options) {
   if (!inspected || issues.length) throw new TileflowIconCompilationError(issues);
   if (inspected.icons.length > tileflowIconPackageLimits4.maxIconCount)
     throw new TileflowIconCompilationError([
-      { path: configPath, message: "One icon contributor supports at most 256 exports" }
+      {
+        path: configPath,
+        message: `One icon contributor supports at most ${tileflowIconPackageLimits4.maxIconCount} exports`
+      }
     ]);
   const entries = inspected.icons.map(
     (icon) => ({
@@ -1553,6 +1770,8 @@ async function readTileflowIconDirectory(source, options) {
       return (await renderIconInputs(inputs)).map((rendered) => ({
         icon: {
           id: rendered.input.name,
+          ...rendered.input.appearance ? { appearance: rendered.input.appearance } : {},
+          ...rendered.input.layout ? { layout: rendered.input.layout } : {},
           oneX: {
             height: rendered.oneX.height,
             width: rendered.oneX.width,
@@ -1595,6 +1814,7 @@ export {
   readTileflowIconsLockfile,
   writeTileflowIconsLockfile,
   composeTileflowIconSources,
+  renderTileflowIconAtlasPreview,
   TileflowIconCompilationError,
   iconFileExtensions,
   compileTileflowIconPackages,