@unmap/themes 0.16.0 → 0.17.0

package/README.md

@@ -32,8 +32,8 @@ const doc = await decodeTheme(code)                 // validated ThemeDoc, or th
 ## What is in a theme
 
 - `base` picks the style: `base`, `muted`, `outdoor`, `blueprint`, `blush`, `orchid`, `canopy`, `lagoon`, `tropic`, `sunset`, `bold`, `pastel`, `atlas` or `swiss`. Each of `light` and `dark` carries
-  sparse overrides on that style, so a theme with no overrides renders exactly like its
-  `flavor=` twin.
+  sparse overrides on that style, so a theme with no overrides renders exactly like the style
+  itself at `/styles/<style>.json`.
 - `basemap` overrides are colours on the style's recipe (land, water, vegetation, roads, labels,
   points of interest, landcover). `marker` styles the geocoding pin (`color`, `scale` 0.5 to 2).
   `route` styles the routing line (`color`, `width` 1 to 12, `opacity`, and a casing).
@@ -45,7 +45,9 @@ const doc = await decodeTheme(code)                 // validated ThemeDoc, or th
 - `encodeTheme(doc)` and `decodeTheme(code)`: async, validate on both sides, throw `ThemeError`
   with a `detail` array naming each problem. Simple themes encode as a short `u…` preset
   (three characters and up); advanced overrides stay `ut1.` + deflate. Codes are at most 4096
-  characters. Existing `ut1.` codes keep decoding.
+  characters. The `ut1` prefix is the wire version and bumps on a breaking change to the
+  document format. The short codes pack a style slot and a preset index; both tables grow only
+  at the end and keep their positions, and a retired slot is a tombstone that does not decode.
 - `validateTheme(input)`: the synchronous validator, returns a typed `ThemeDoc`.
 - `resolveTheme(doc, mode)`: what the gateway calls. Returns the style's flavor name, the
   composed colour flavor, and the resolved `marker` and `route` styles with defaults filled in.

package/dist/index.d.ts

@@ -174,9 +174,9 @@ declare const mist: {
     readonly 980: "#0D0D0D";
 };
 /**
- * Jade, hue 163. The `decimal` pair: one green family on near-black (dark) or near-white
- * (light), nothing else. Same lightness ladder as `ink`, so every label step the other styles
- * rely on clears the floors here too. Chroma rises with lightness up to the mid steps
+ * Jade, hue 163. The emerald and mint greens of `orchid`'s woods and of the parks and woods in
+ * `tropic`, `bold` and `pastel`. Same lightness ladder as `ink`, so every label step the other
+ * styles rely on clears the floors here too. Chroma rises with lightness up to the mid steps
  * (`0.16·L`) and eases off toward white (`0.42·(1−L)`), which is the profile of the
  * reference's own four greens (`#142a21` → `#50a882`).
  */
@@ -460,15 +460,11 @@ declare const swissRelief: {
  * The shipped styles. Appended, never inserted: this array's order drives the style picker in
  * the unmap.dev builder, so inserting a style mid-array silently reorders a control people have
  * already learned.
- *
- * `relief`, `street` and `decimal` were retired; they are not listed here. Short preset codes
- * still decode those slots via `normalizeThemeBase` / the slot table in `preset.ts`. `decimal`
- * (2026-09-09) maps onto `blueprint`: the two single-hue styles read as the same map.
  */
 declare const THEME_BASES: readonly ["base", "muted", "outdoor", "blueprint", "blush", "orchid", "canopy", "lagoon", "tropic", "sunset", "bold", "pastel", "atlas", "swiss"];
 type ThemeBase = (typeof THEME_BASES)[number];
-/** Map a theme `base` — living or retired — onto a shipped style. `null` if unknown. */
-declare function normalizeThemeBase(base: string): ThemeBase | null;
+/** Whether `base` names a shipped style. */
+declare function isThemeBase(base: unknown): base is ThemeBase;
 declare const MODES: readonly ["light", "dark"];
 type ThemeMode = (typeof MODES)[number];
 interface RoadRamp {
@@ -707,8 +703,8 @@ declare function validateTheme(input: unknown): ThemeDoc;
  * `deflate-raw`, which Node 20 — the repo floor — does not implement; the wrapper costs six
  * bytes and buys a checksum.
  *
- * `ut1` is the wire version. Bump it only for a breaking change, and keep decoding old
- * prefixes forever: codes get hardcoded into customers' pages.
+ * `ut1` is the wire version. A breaking change to the document format bumps it, and the decoder
+ * reads the current prefix only.
  */
 declare const THEME_CODE_PREFIX = "ut1.";
 declare const MAX_CODE_LENGTH = 4096;
@@ -726,8 +722,7 @@ declare function decodeTheme(code: string): Promise<ThemeDoc>;
  * enumerated choices that starts at three characters and grows only when the theme leaves the
  * curated set.
  *
- *   u00 … u0C       the style slots, in lineup order (`u03` was `decimal`, retired 2026-09-09;
- *                   it decodes to `blueprint`, and `blueprint` still encodes as `u04`)
+ *   u00 … u0E       the style slots, in lineup order (`u03` is a tombstone and does not decode)
  *   u0W, u4e, …     a named theme preset on a style (three characters for the first fifteen
  *                   presets; `tamarack`, the sixteenth, is the first to take four)
  *   six to eight    a style or preset with layer groups hidden or reordered
@@ -746,10 +741,10 @@ declare function decodeTheme(code: string): Promise<ThemeDoc>;
  *              by a 13-bit Lehmer index of the draw order (0 = stock order)
  *
  * 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.)
+ * than decoding to a theme nobody asked for. Both lookup tables only grow at the end and never
+ * reuse a position: the index is bit-packed into every code, so removing an entry would
+ * renumber every code after it. A retired entry stays as a `null` tombstone that fails to
+ * decode. (The layout itself was re-cut on 2026-09-07.)
  */
 declare const PRESET_CODE_PREFIX = "u";
 declare const PRESET_CODE_RE: RegExp;
@@ -867,7 +862,8 @@ declare function contrastWarnings(doc: ThemeDoc): ContrastWarning[];
 
 /**
  * The shipped styles as starting-point themes: zero overrides, so each is guaranteed identical
- * to its `flavor=` twin (asserted in the gateway theme tests). The builder opens on these.
+ * to the style it names, served at `/styles/<style>.json` (asserted in the gateway theme tests).
+ * The builder opens on these.
  *
  * Named after the style itself — `base`, `muted`, `outdoor`, `blueprint`, `blush`, … — the same word the homepage, the
  * SDK's `style` option and the gateway URL use. The theme presets (`process ink`, `boreal`, …)
@@ -956,4 +952,4 @@ interface PaletteColor {
  */
 declare function seedsFromPalette(colors: PaletteColor[]): Required<ThemeSeeds>;
 
-export { BUILDINGS_3D_LAYER_ID, type BasemapOverrides, type ContrastWarning, DEFAULT_LAYER_VISIBILITY, DEFAULT_MARKER, DEFAULT_ROUTE, DEFAULT_SEEDS, type DeepPartial, LABEL_PAIRS, LAYER_GROUPS, type LabelRamp, type LayerGroup, MAX_CODE_LENGTH, MODES, type MarkerTheme, type Oklch, PRESET_CODE_PREFIX, PRESET_CODE_RE, type PaletteColor, RECIPES, type RampSet, type Recipe, type ResolvedTheme, type RoadRamp, type RouteTheme, STOCK_RAMPS, STYLE_THEMES, THEME_BASES, THEME_CODE_PREFIX, THEME_PRESETS, type ThemeBase, type ThemeDoc, ThemeError, type ThemeHalf, type ThemeLayers, type ThemeMode, type ThemePreset, type ThemeSeeds, amber, applyThemeLayers, aqua, atlasGreen, atlasPaper, atlasRelief, atlasRoad, atlasWater, azure, buildRecipes, cobalt, contrast, contrastWarnings, coral, decodePreset, decodeTheme, effectiveLayerOrder, ember, encodePreset, encodeTheme, fern, generateTheme, graphite, hexToOklch, indigo, ink, isLayerVisible, isStockLayerOrder, isStockLayers, isThemePresetCode, jade, layerGroupOf, lilac, linen, makeFlavor, mergeRecipe, mist, normalizeThemeBase, oklchToHex, paper, peach, presetId, registryThemeKey, resolveTheme, rose, sandstone, seedsFromPalette, shuffleSeeds, sky, swissGreen, swissPaper, swissRelief, swissRoad, swissWater, validateTheme, verdant, wave };
+export { BUILDINGS_3D_LAYER_ID, type BasemapOverrides, type ContrastWarning, DEFAULT_LAYER_VISIBILITY, DEFAULT_MARKER, DEFAULT_ROUTE, DEFAULT_SEEDS, type DeepPartial, LABEL_PAIRS, LAYER_GROUPS, type LabelRamp, type LayerGroup, MAX_CODE_LENGTH, MODES, type MarkerTheme, type Oklch, PRESET_CODE_PREFIX, PRESET_CODE_RE, type PaletteColor, RECIPES, type RampSet, type Recipe, type ResolvedTheme, type RoadRamp, type RouteTheme, STOCK_RAMPS, STYLE_THEMES, THEME_BASES, THEME_CODE_PREFIX, THEME_PRESETS, type ThemeBase, type ThemeDoc, ThemeError, type ThemeHalf, type ThemeLayers, type ThemeMode, type ThemePreset, type ThemeSeeds, amber, applyThemeLayers, aqua, atlasGreen, atlasPaper, atlasRelief, atlasRoad, atlasWater, azure, buildRecipes, cobalt, contrast, contrastWarnings, coral, decodePreset, decodeTheme, effectiveLayerOrder, ember, encodePreset, encodeTheme, fern, generateTheme, graphite, hexToOklch, indigo, ink, isLayerVisible, isStockLayerOrder, isStockLayers, isThemeBase, isThemePresetCode, jade, layerGroupOf, lilac, linen, makeFlavor, mergeRecipe, mist, oklchToHex, paper, peach, presetId, registryThemeKey, resolveTheme, rose, sandstone, seedsFromPalette, shuffleSeeds, sky, swissGreen, swissPaper, swissRelief, swissRoad, swissWater, validateTheme, verdant, wave };

package/dist/index.js

@@ -366,14 +366,8 @@ var THEME_BASES = [
   "atlas",
   "swiss"
 ];
-var RETIRED_BASES = {
-  relief: "outdoor",
-  street: "base",
-  decimal: "blueprint"
-};
-function normalizeThemeBase(base) {
-  if (THEME_BASES.includes(base)) return base;
-  return RETIRED_BASES[base] ?? null;
+function isThemeBase(base) {
+  return typeof base === "string" && THEME_BASES.includes(base);
 }
 var MODES = ["light", "dark"];
 function makeFlavor(r) {
@@ -2506,8 +2500,7 @@ function validateTheme(input) {
     if (!DOC_KEYS.includes(key)) errors.push(`${key}: unknown field`);
   }
   if (input.v !== 1) errors.push("v: must be 1");
-  const base = typeof input.base === "string" ? normalizeThemeBase(input.base) : null;
-  if (!base) {
+  if (!isThemeBase(input.base)) {
     errors.push(`base: must be one of ${THEME_BASES.join(", ")}`);
   }
   if (input.name !== void 0) {
@@ -2546,7 +2539,6 @@ function validateTheme(input) {
     }
   }
   if (errors.length > 0) throw new ThemeError("invalid theme", errors);
-  if (base && base !== input.base) return { ...input, base };
   return input;
 }
 
@@ -3032,7 +3024,8 @@ var STYLE_SLOTS = [
   "base",
   "muted",
   "outdoor",
-  "decimal",
+  null,
+  // u03, retired 2026-09-09
   "blueprint",
   "blush",
   "orchid",
@@ -3175,7 +3168,7 @@ function unpackLayers(bits) {
   return layers;
 }
 function encodePreset(doc) {
-  const slot = STYLE_SLOTS.indexOf(doc.base);
+  const slot = isThemeBase(doc.base) ? STYLE_SLOTS.indexOf(doc.base) : -1;
   if (slot < 0) return null;
   let kind;
   let payload = 0n;
@@ -3217,9 +3210,10 @@ function decodePreset(code) {
     rest >>= bits;
     return value;
   };
-  const slot = STYLE_SLOTS[Number(take(STYLE_BITS))];
-  const base = slot ? normalizeThemeBase(slot) : null;
-  if (!base) throw new ThemeError("invalid theme", ["preset style is out of range"]);
+  const slot = Number(take(STYLE_BITS));
+  const base = STYLE_SLOTS[slot];
+  if (base === void 0) throw new ThemeError("invalid theme", ["preset style is out of range"]);
+  if (base === null) throw new ThemeError("invalid theme", [`preset style slot ${slot} is retired`]);
   const kind = take(KIND_BITS);
   const hasLayers = take(1n) === 1n;
   let doc;
@@ -3456,6 +3450,7 @@ export {
   isLayerVisible,
   isStockLayerOrder,
   isStockLayers,
+  isThemeBase,
   isThemePresetCode,
   jade,
   layerGroupOf,
@@ -3464,7 +3459,6 @@ export {
   makeFlavor,
   mergeRecipe,
   mist,
-  normalizeThemeBase,
   oklchToHex,
   paper,
   peach,