@unmap/themes 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -508,29 +508,42 @@ declare function validateTheme(input: unknown): ThemeDoc;
  */
 declare const THEME_CODE_PREFIX = "ut1.";
 declare const MAX_CODE_LENGTH = 4096;
-/** Validate and encode a theme document. Curated/simple themes become a short `u…` preset; anything else is `ut1.` + deflate. Throws `ThemeError`. */
+/**
+ * Validate and encode a theme document. Curated/simple themes — a style, a named preset or
+ * custom seeds, with or without layer groups hidden or reordered — become a short `u…` preset;
+ * anything with hand-edited colours is `ut1.` + deflate. Throws `ThemeError`.
+ */
 declare function encodeTheme(doc: ThemeDoc): Promise<string>;
 /** Decode and validate a compact theme code (`u…` preset or `ut1.` document). Every failure lands as `ThemeError`. */
 declare function decodeTheme(code: string): Promise<ThemeDoc>;
 
 /**
- * Short preset codes, the same idea as shadcn's `b0` / `a2r6bw`: a versioned base62 packing of
+ * Short preset codes, the same idea as shadcn's `b0` / `a2r6bw`: a base62 packing of
  * enumerated choices that starts at three characters and grows only when the theme leaves the
  * curated set.
  *
- *   u00, u01, u04   living styles from the original lineup (base, muted, outdoor)
- *   u02, u03        retired styles (relief → outdoor, street → base)
- *   u05, u06        the second wave (decimal, blueprint)
- *   u5K, u5N, …     the third wave (blush, orchid, canopy, lagoon) and any style after them
- *   u08…            named theme preset on one of the original style slots
- *   u5L…            named theme preset on a later style
- *   longer          custom seed colours (4× RGB) on any style
+ *   u00 … u08       the nine styles, in lineup order
+ *   u0W, u4e, …     a named theme preset on a style (three characters for every pair)
+ *   six to eight    a style or preset with layer groups hidden or reordered
+ *   up to 23        custom seed colours (4× RGB) on any style, layers included
  *
  * Advanced overrides — anything `generateTheme` would not emit — still use the `ut1.` deflate
- * document. `ut1.` is checked first on decode so an existing customer code never collides.
+ * document. `ut1.` is checked first on decode so the two forms never collide.
+ *
+ * Layout, low bits first, of the number the base62 digits spell:
+ *
+ *   bits 0–4   style slot (`STYLE_SLOTS`; 32 styles)
+ *   bits 5–6   kind: 0 bare style, 1 named preset, 2 custom seeds (3 unassigned)
+ *   bit  7     layers flag
+ *   bits 8…    kind payload: preset → 8-bit preset index; custom → 4 × 24-bit RGB seeds
+ *   then       if the flag is set, 7 visibility bits (one per `LAYER_GROUPS` entry) followed
+ *              by a 13-bit Lehmer index of the draw order (0 = stock order)
  *
- * Slot numbers are permanent once a code is published, which is why the layout below is a set
- * of appended regions rather than one formula: every code ever printed keeps decoding.
+ * Anything left above the last field is an error, so a truncated or padded code fails rather
+ * than decoding to a theme nobody asked for. Both lookup tables are append-only: a new style
+ * or preset goes on the end, so a code already printed keeps meaning the same theme.
+ * (The layout itself was re-cut on 2026-09-07 with no compatibility for the codes the earlier
+ * region-and-lane scheme printed; that is the one time it happens.)
  */
 declare const PRESET_CODE_PREFIX = "u";
 declare const PRESET_CODE_RE: RegExp;

package/dist/index.js

@@ -2153,51 +2153,119 @@ function shuffleSeeds(rng = Math.random) {
   };
 }
 
+// src/layers.ts
+var DEFAULT_LAYER_VISIBILITY = {
+  land: true,
+  water: true,
+  buildings: true,
+  roads: true,
+  boundaries: true,
+  buildings3d: false,
+  labels: true
+};
+var BUILDINGS_3D_LAYER_ID = "buildings_3d";
+var LAND_LINES = /* @__PURE__ */ new Set(["roads_runway", "roads_taxiway"]);
+function layerGroupOf(layer) {
+  const { id, type } = layer;
+  if (type === "symbol") return "labels";
+  if (id === "background") return null;
+  if (id === BUILDINGS_3D_LAYER_ID) return "buildings3d";
+  if (id === "buildings") return "buildings";
+  if (id.startsWith("water")) return "water";
+  if (id.startsWith("boundaries")) return "boundaries";
+  if (LAND_LINES.has(id)) return "land";
+  if (id.startsWith("roads")) return "roads";
+  if (id === "earth" || id === "landcover" || id.startsWith("landuse")) return "land";
+  return null;
+}
+function isLayerVisible(layers, group) {
+  return layers?.visible?.[group] ?? DEFAULT_LAYER_VISIBILITY[group];
+}
+function effectiveLayerOrder(layers) {
+  return layers?.order ?? LAYER_GROUPS;
+}
+function isStockLayerOrder(order) {
+  return !order || order.length === LAYER_GROUPS.length && order.every((g, i) => g === LAYER_GROUPS[i]);
+}
+function isStockLayers(layers) {
+  if (!layers) return true;
+  if (!isStockLayerOrder(layers.order)) return false;
+  return LAYER_GROUPS.every((g) => isLayerVisible(layers, g) === DEFAULT_LAYER_VISIBILITY[g]);
+}
+function buildings3dLayer(source, color) {
+  return {
+    id: BUILDINGS_3D_LAYER_ID,
+    type: "fill-extrusion",
+    source,
+    "source-layer": "buildings",
+    minzoom: 13,
+    filter: ["in", "kind", "building", "building_part"],
+    paint: {
+      "fill-extrusion-color": color,
+      "fill-extrusion-height": ["coalesce", ["get", "height"], 6],
+      "fill-extrusion-base": ["coalesce", ["get", "min_height"], 0],
+      "fill-extrusion-opacity": 0.85
+    }
+  };
+}
+function applyThemeLayers(styleLayers, layers, buildingsColor) {
+  if (isStockLayers(layers)) return styleLayers;
+  const visible = (g) => isLayerVisible(layers, g);
+  const tagged = styleLayers.map((layer) => ({ layer, group: layerGroupOf(layer) }));
+  const source = styleLayers.find((l) => l.id === "buildings")?.source ?? "unmap";
+  const extrusion = visible("buildings3d") ? buildings3dLayer(source, buildingsColor) : null;
+  if (isStockLayerOrder(layers?.order)) {
+    const kept = tagged.filter(({ group }) => group === null || visible(group)).map((t) => t.layer);
+    if (!extrusion) return kept;
+    const firstLabel = kept.findIndex((l) => layerGroupOf(l) === "labels");
+    const at = firstLabel === -1 ? kept.length : firstLabel;
+    return [...kept.slice(0, at), extrusion, ...kept.slice(at)];
+  }
+  const out = tagged.filter(({ group }) => group === null).map((t) => t.layer);
+  for (const group of effectiveLayerOrder(layers)) {
+    if (!visible(group)) continue;
+    if (group === "buildings3d") {
+      if (extrusion) out.push(extrusion);
+      continue;
+    }
+    for (const t of tagged) if (t.group === group) out.push(t.layer);
+  }
+  return out;
+}
+
 // src/preset.ts
 var PRESET_CODE_PREFIX = "u";
 var PRESET_CODE_RE = /^u[0-9A-Za-z]{2,24}$/;
 var BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 var SEED_KEYS = ["land", "water", "nature", "accent"];
-var STYLE_ENCODE = {
-  base: 0,
-  muted: 1,
-  outdoor: 4,
-  decimal: 5,
-  blueprint: 6,
-  blush: 8,
-  orchid: 9,
-  canopy: 10,
-  lagoon: 11
-};
-var STYLE_DECODE = [
+var STYLE_SLOTS = [
   "base",
   "muted",
   "outdoor",
-  "base",
-  "outdoor",
   "decimal",
   "blueprint",
-  void 0,
   "blush",
   "orchid",
   "canopy",
   "lagoon"
 ];
-var PRESET_OFFSET = 8n;
-var ORIGINAL_SLOTS = 5n;
-var ORIGINAL_PRESET_LIMIT = 64n;
-var LATER_OFFSET = PRESET_OFFSET + ORIGINAL_PRESET_LIMIT * ORIGINAL_SLOTS;
-var LATER_LANES = 3n;
-var LATER_ROWS = 232n;
-var WAVE2_BASE = 5;
-var WAVE3_BASE = 8;
-var WAVE3_BARE_ROWS = 32n;
-var WAVE3_STYLE_COLUMNS = 20n;
-var WAVE3_PRESET_LIMIT = (LATER_ROWS - WAVE3_BARE_ROWS) / WAVE3_STYLE_COLUMNS;
-var CUSTOM_OFFSET = 1024n;
-var ESCAPE_SLOT = 7n;
-var ESCAPE_BITS = 5n;
+var STYLE_BITS = 5n;
+var KIND_BITS = 2n;
+var KIND_BARE = 0n;
+var KIND_PRESET = 1n;
+var KIND_CUSTOM = 2n;
+var PRESET_INDEX_BITS = 8n;
+var RGB_BITS = 24n;
+var VISIBILITY_BITS = BigInt(LAYER_GROUPS.length);
+var ORDER_BITS = 13n;
+var ORDER_COUNT = factorial(LAYER_GROUPS.length);
+var mask = (bits) => (1n << bits) - 1n;
 var sameHex = (a, b) => a.toLowerCase() === b.toLowerCase();
+function factorial(n) {
+  let f = 1n;
+  for (let i = 2n; i <= BigInt(n); i++) f *= i;
+  return f;
+}
 function isThemePresetCode(code) {
   return PRESET_CODE_RE.test(code);
 }
@@ -2261,105 +2329,121 @@ function generatedMatch(doc) {
 function findPresetIndex(seeds) {
   return THEME_PRESETS.findIndex((p) => seedsMatch(p.seeds, { ...DEFAULT_SEEDS, ...seeds }));
 }
-function encodeBits(bits) {
-  return PRESET_CODE_PREFIX + toBase62(bits);
+function orderIndex(order) {
+  const remaining = [...LAYER_GROUPS];
+  let index = 0n;
+  let radix = factorial(remaining.length);
+  for (const group of order) {
+    const at = remaining.indexOf(group);
+    radix /= BigInt(remaining.length);
+    index += BigInt(at) * radix;
+    remaining.splice(at, 1);
+  }
+  return index;
+}
+function orderAt(index) {
+  const remaining = [...LAYER_GROUPS];
+  const order = [];
+  let rest = index;
+  let radix = factorial(remaining.length);
+  while (remaining.length > 0) {
+    radix /= BigInt(remaining.length);
+    const at = Number(rest / radix);
+    rest %= radix;
+    order.push(remaining.splice(at, 1)[0]);
+  }
+  return order;
+}
+function packLayers(layers) {
+  let bits = 0n;
+  LAYER_GROUPS.forEach((group, i) => {
+    const visible = layers.visible?.[group] ?? DEFAULT_LAYER_VISIBILITY[group];
+    if (visible) bits |= 1n << BigInt(i);
+  });
+  const order = isStockLayerOrder(layers.order) ? 0n : orderIndex(layers.order);
+  return bits | order << VISIBILITY_BITS;
+}
+function unpackLayers(bits) {
+  const layers = {};
+  const visible = {};
+  LAYER_GROUPS.forEach((group, i) => {
+    const on = (bits >> BigInt(i) & 1n) === 1n;
+    if (on !== DEFAULT_LAYER_VISIBILITY[group]) visible[group] = on;
+  });
+  if (Object.keys(visible).length > 0) layers.visible = visible;
+  const order = bits >> VISIBILITY_BITS;
+  if (order >= ORDER_COUNT) {
+    throw new ThemeError("invalid theme", ["preset layer order is out of range"]);
+  }
+  if (order !== 0n) layers.order = orderAt(order);
+  return layers;
 }
 function encodePreset(doc) {
-  const index = STYLE_ENCODE[doc.base];
-  if (index === void 0) return null;
-  const s = BigInt(index);
+  const slot = STYLE_SLOTS.indexOf(doc.base);
+  if (slot < 0) return null;
+  let kind;
+  let payload = 0n;
+  let payloadBits = 0n;
   if (isBareStyle(doc)) {
-    if (index < WAVE3_BASE) return encodeBits(s);
-    return encodeBits(LATER_OFFSET + (s - BigInt(WAVE3_BASE)) * LATER_LANES + 2n);
-  }
-  if (!doc.seeds || !generatedMatch(doc)) return null;
-  const presetIndex = findPresetIndex(doc.seeds);
-  if (presetIndex >= 0) {
-    const p = BigInt(presetIndex);
-    if (index < WAVE2_BASE) {
-      if (p < ORIGINAL_PRESET_LIMIT) return encodeBits(PRESET_OFFSET + p * ORIGINAL_SLOTS + s);
-    } else if (index < WAVE3_BASE) {
-      if (p < LATER_ROWS) {
-        return encodeBits(LATER_OFFSET + p * LATER_LANES + (s - BigInt(WAVE2_BASE)));
+    kind = KIND_BARE;
+  } else {
+    if (!doc.seeds || !generatedMatch(doc)) return null;
+    const presetIndex = findPresetIndex(doc.seeds);
+    if (presetIndex >= 0 && presetIndex < Number(mask(PRESET_INDEX_BITS))) {
+      kind = KIND_PRESET;
+      payload = BigInt(presetIndex);
+      payloadBits = PRESET_INDEX_BITS;
+    } else {
+      if (!doc.seeds.accent) return null;
+      kind = KIND_CUSTOM;
+      const filled = { ...DEFAULT_SEEDS, ...doc.seeds };
+      for (const key of SEED_KEYS) {
+        payload |= rgb24(filled[key]) << payloadBits;
+        payloadBits += RGB_BITS;
       }
-    } else if (p < WAVE3_PRESET_LIMIT && s - BigInt(WAVE3_BASE) < WAVE3_STYLE_COLUMNS) {
-      const row = WAVE3_BARE_ROWS + p * WAVE3_STYLE_COLUMNS + (s - BigInt(WAVE3_BASE));
-      return encodeBits(LATER_OFFSET + row * LATER_LANES + 2n);
     }
   }
-  if (!doc.seeds.accent) return null;
-  const filled = { ...DEFAULT_SEEDS, ...doc.seeds };
-  let bits;
-  let shift;
-  if (index < WAVE3_BASE) {
-    bits = CUSTOM_OFFSET + s;
-    shift = 3n;
-  } else {
-    bits = CUSTOM_OFFSET + ESCAPE_SLOT + (s - BigInt(WAVE3_BASE) << 3n);
-    shift = 3n + ESCAPE_BITS;
-  }
-  for (const key of SEED_KEYS) {
-    bits += rgb24(filled[key]) << shift;
-    shift += 24n;
-  }
-  return encodeBits(bits);
+  const hasLayers = !isStockLayers(doc.layers);
+  let bits = BigInt(slot) | kind << STYLE_BITS | (hasLayers ? 1n : 0n) << STYLE_BITS + KIND_BITS;
+  let shift = STYLE_BITS + KIND_BITS + 1n;
+  bits |= payload << shift;
+  shift += payloadBits;
+  if (hasLayers) bits |= packLayers(doc.layers) << shift;
+  return PRESET_CODE_PREFIX + toBase62(bits);
 }
 function decodePreset(code) {
   if (!isThemePresetCode(code)) {
     throw new ThemeError("invalid theme", ["code is not a valid preset"]);
   }
-  const bits = fromBase62(code.slice(PRESET_CODE_PREFIX.length));
-  const styleAt = (index) => {
-    const base2 = STYLE_DECODE[index];
-    if (!base2) throw new ThemeError("invalid theme", ["preset style is out of range"]);
-    return base2;
+  let rest = fromBase62(code.slice(PRESET_CODE_PREFIX.length));
+  const take = (bits) => {
+    const value = rest & mask(bits);
+    rest >>= bits;
+    return value;
   };
-  const presetAt = (index) => {
-    const preset = THEME_PRESETS[index];
+  const base = STYLE_SLOTS[Number(take(STYLE_BITS))];
+  if (!base) throw new ThemeError("invalid theme", ["preset style is out of range"]);
+  const kind = take(KIND_BITS);
+  const hasLayers = take(1n) === 1n;
+  let doc;
+  if (kind === KIND_BARE) {
+    doc = structuredClone(STYLE_THEMES[base]);
+  } else if (kind === KIND_PRESET) {
+    const preset = THEME_PRESETS[Number(take(PRESET_INDEX_BITS))];
     if (!preset) throw new ThemeError("invalid theme", ["preset is out of range"]);
-    return preset;
-  };
-  if (bits < PRESET_OFFSET) {
-    return structuredClone(STYLE_THEMES[styleAt(Number(bits))]);
-  }
-  if (bits < LATER_OFFSET) {
-    const n = bits - PRESET_OFFSET;
-    return generateTheme(styleAt(Number(n % ORIGINAL_SLOTS)), presetAt(Number(n / ORIGINAL_SLOTS)).seeds);
-  }
-  if (bits < CUSTOM_OFFSET) {
-    const n = bits - LATER_OFFSET;
-    const lane = Number(n % LATER_LANES);
-    const row = n / LATER_LANES;
-    if (lane < 2) {
-      return generateTheme(styleAt(WAVE2_BASE + lane), presetAt(Number(row)).seeds);
-    }
-    if (row < WAVE3_BARE_ROWS) {
-      return structuredClone(STYLE_THEMES[styleAt(WAVE3_BASE + Number(row))]);
-    }
-    const j = row - WAVE3_BARE_ROWS;
-    const base2 = styleAt(WAVE3_BASE + Number(j % WAVE3_STYLE_COLUMNS));
-    return generateTheme(base2, presetAt(Number(j / WAVE3_STYLE_COLUMNS)).seeds);
-  }
-  const payload = bits - CUSTOM_OFFSET;
-  const slot = payload & 7n;
-  let base;
-  let rest;
-  if (slot === ESCAPE_SLOT) {
-    base = styleAt(WAVE3_BASE + Number(payload >> 3n & (1n << ESCAPE_BITS) - 1n));
-    rest = payload >> 3n + ESCAPE_BITS;
+    doc = generateTheme(base, preset.seeds);
+  } else if (kind === KIND_CUSTOM) {
+    const seeds = { ...DEFAULT_SEEDS };
+    for (const key of SEED_KEYS) seeds[key] = fromRgb24(take(RGB_BITS));
+    doc = generateTheme(base, seeds);
   } else {
-    base = styleAt(Number(slot));
-    rest = payload >> 3n;
-  }
-  const seeds = { ...DEFAULT_SEEDS };
-  for (const key of SEED_KEYS) {
-    seeds[key] = fromRgb24(rest & 0xffffffn);
-    rest >>= 24n;
+    throw new ThemeError("invalid theme", ["preset kind is unassigned"]);
   }
+  if (hasLayers) doc.layers = unpackLayers(take(VISIBILITY_BITS + ORDER_BITS));
   if (rest !== 0n) {
     throw new ThemeError("invalid theme", ["preset payload has unused bits"]);
   }
-  return generateTheme(base, seeds);
+  return doc;
 }
 function registryThemeKey(doc) {
   if (isBareStyle(doc)) return STYLE_THEMES[doc.base]?.name;
@@ -2369,86 +2453,6 @@ function registryThemeKey(doc) {
   return presetId(THEME_PRESETS[presetIndex].name);
 }
 
-// src/layers.ts
-var DEFAULT_LAYER_VISIBILITY = {
-  land: true,
-  water: true,
-  buildings: true,
-  roads: true,
-  boundaries: true,
-  buildings3d: false,
-  labels: true
-};
-var BUILDINGS_3D_LAYER_ID = "buildings_3d";
-var LAND_LINES = /* @__PURE__ */ new Set(["roads_runway", "roads_taxiway"]);
-function layerGroupOf(layer) {
-  const { id, type } = layer;
-  if (type === "symbol") return "labels";
-  if (id === "background") return null;
-  if (id === BUILDINGS_3D_LAYER_ID) return "buildings3d";
-  if (id === "buildings") return "buildings";
-  if (id.startsWith("water")) return "water";
-  if (id.startsWith("boundaries")) return "boundaries";
-  if (LAND_LINES.has(id)) return "land";
-  if (id.startsWith("roads")) return "roads";
-  if (id === "earth" || id === "landcover" || id.startsWith("landuse")) return "land";
-  return null;
-}
-function isLayerVisible(layers, group) {
-  return layers?.visible?.[group] ?? DEFAULT_LAYER_VISIBILITY[group];
-}
-function effectiveLayerOrder(layers) {
-  return layers?.order ?? LAYER_GROUPS;
-}
-function isStockLayerOrder(order) {
-  return !order || order.length === LAYER_GROUPS.length && order.every((g, i) => g === LAYER_GROUPS[i]);
-}
-function isStockLayers(layers) {
-  if (!layers) return true;
-  if (!isStockLayerOrder(layers.order)) return false;
-  return LAYER_GROUPS.every((g) => isLayerVisible(layers, g) === DEFAULT_LAYER_VISIBILITY[g]);
-}
-function buildings3dLayer(source, color) {
-  return {
-    id: BUILDINGS_3D_LAYER_ID,
-    type: "fill-extrusion",
-    source,
-    "source-layer": "buildings",
-    minzoom: 13,
-    filter: ["in", "kind", "building", "building_part"],
-    paint: {
-      "fill-extrusion-color": color,
-      "fill-extrusion-height": ["coalesce", ["get", "height"], 6],
-      "fill-extrusion-base": ["coalesce", ["get", "min_height"], 0],
-      "fill-extrusion-opacity": 0.85
-    }
-  };
-}
-function applyThemeLayers(styleLayers, layers, buildingsColor) {
-  if (isStockLayers(layers)) return styleLayers;
-  const visible = (g) => isLayerVisible(layers, g);
-  const tagged = styleLayers.map((layer) => ({ layer, group: layerGroupOf(layer) }));
-  const source = styleLayers.find((l) => l.id === "buildings")?.source ?? "unmap";
-  const extrusion = visible("buildings3d") ? buildings3dLayer(source, buildingsColor) : null;
-  if (isStockLayerOrder(layers?.order)) {
-    const kept = tagged.filter(({ group }) => group === null || visible(group)).map((t) => t.layer);
-    if (!extrusion) return kept;
-    const firstLabel = kept.findIndex((l) => layerGroupOf(l) === "labels");
-    const at = firstLabel === -1 ? kept.length : firstLabel;
-    return [...kept.slice(0, at), extrusion, ...kept.slice(at)];
-  }
-  const out = tagged.filter(({ group }) => group === null).map((t) => t.layer);
-  for (const group of effectiveLayerOrder(layers)) {
-    if (!visible(group)) continue;
-    if (group === "buildings3d") {
-      if (extrusion) out.push(extrusion);
-      continue;
-    }
-    for (const t of tagged) if (t.group === group) out.push(t.layer);
-  }
-  return out;
-}
-
 // src/codec.ts
 var THEME_CODE_PREFIX = "ut1.";
 var MAX_CODE_LENGTH = 4096;
@@ -2493,7 +2497,7 @@ async function through(bytes, transform, cap) {
 }
 async function encodeTheme(doc) {
   const valid = validateTheme(doc);
-  const preset = isStockLayers(valid.layers) ? encodePreset(valid) : null;
+  const preset = encodePreset(valid);
   if (preset) return preset;
   const json = new TextEncoder().encode(JSON.stringify(valid));
   const packed = await through(json, new CompressionStream("deflate"), Number.POSITIVE_INFINITY);