@unmap/themes 0.1.2 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maps & Apps Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -20,21 +20,21 @@ import { encodeTheme, decodeTheme, validateTheme, ThemeError } from '@unmap/them
 const code = await encodeTheme({
   v: 1,
   name: 'copper',
-  base: 'street',                                   // base | muted | relief | street | outdoor
+  base: 'outdoor',                                  // base | muted | outdoor | decimal | blueprint
   light: { basemap: { water: '#9CCFD2' }, route: { color: '#B85C00', width: 4 } },
   dark:  { basemap: { water: '#12303A' }, route: { color: '#FFA24D', width: 4 } },
 })
-// 'ut1.eJy…' — pass as `theme` to new Unmap({ ... }) or ?theme= on a style URL
+// 'u00' for a bare style, or 'ut1.eJy…' once you leave the curated set.
 
 const doc = await decodeTheme(code)                 // validated ThemeDoc, or throws ThemeError
 ```
 
 ## What is in a theme
 
-- `base` picks the chassis: one of the five shipped styles. Each of `light` and `dark` carries
-  sparse overrides on that chassis, so a theme with no overrides renders exactly like its
+- `base` picks the style: `base`, `muted`, `outdoor`, `decimal` or `blueprint`. Each of `light` and `dark` carries
+  sparse overrides on that style, so a theme with no overrides renders exactly like its
   `flavor=` twin.
-- `basemap` overrides are colours on the chassis recipe (land, water, vegetation, roads, labels,
+- `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).
 - Colours are `#RRGGBB` or `#RRGGBBAA`. Unknown fields, URLs, and expressions are rejected: a
@@ -43,11 +43,13 @@ const doc = await decodeTheme(code)                 // validated ThemeDoc, or th
 ## Exports
 
 - `encodeTheme(doc)` and `decodeTheme(code)`: async, validate on both sides, throw `ThemeError`
-  with a `detail` array naming each problem. Codes are at most 4096 characters.
+  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.
 - `validateTheme(input)`: the synchronous validator, returns a typed `ThemeDoc`.
-- `resolveTheme(doc, mode)`: what the gateway calls. Returns the chassis flavor name, the
+- `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.
-- `PRESET_THEMES`: the five shipped styles as zero-override documents.
+- `STYLE_THEMES`: the shipped styles as zero-override documents.
 - `generateTheme(base, seeds)` and `contrastWarnings(doc)`: the pieces the builder uses to
   derive a coherent light and dark pair from a few seed colours, and to flag label contrast
   below 4.5:1 and 3:1.

package/dist/index.d.ts

@@ -22,7 +22,7 @@ declare const ember: {
     readonly 600: "#e07b2e";
     readonly 700: "#b45309";
 };
-/** Cool neutrals, hue 212. The spine of every Process Ink flavour. */
+/** Cool neutrals, hue 212. The spine of every Process Ink flavour except `base`. */
 declare const ink: {
     readonly 25: "#F1F8FA";
     readonly 50: "#EAF2F3";
@@ -39,6 +39,29 @@ declare const ink: {
     readonly 950: "#0E191C";
     readonly 1000: "#030E10";
 };
+/**
+ * Warm off-white neutrals, hue 50, chroma 0.008. The `base` pair only.
+ *
+ * Same lightness ladder as `ink`, re-hued to the land of the Mapbox Streets reference `base`
+ * follows (`hsl(20, 20%, 95%)`): a faint warm tint rather than the cream it had, so parks,
+ * water and the motorway orange read as colour against it instead of competing with it.
+ */
+declare const paper: {
+    readonly 25: "#FBF5F2";
+    readonly 50: "#F5EFEC";
+    readonly 100: "#ECE6E3";
+    readonly 200: "#E1DBD8";
+    readonly 300: "#D4CECB";
+    readonly 400: "#C3BDBA";
+    readonly 500: "#A9A3A0";
+    readonly 600: "#8A8582";
+    readonly 700: "#696361";
+    readonly 800: "#4A4543";
+    readonly 850: "#373330";
+    readonly 900: "#272220";
+    readonly 950: "#1A1614";
+    readonly 1000: "#0E0B09";
+};
 /** Water, hue 200. Cooler and more chromatic than the land it meets. */
 declare const wave: {
     readonly 100: "#C7F1F3";
@@ -53,6 +76,26 @@ declare const wave: {
     readonly 950: "#001C1E";
     readonly 980: "#001012";
 };
+/**
+ * Sky water, hue 230. The `base` pair only.
+ *
+ * Same lightness ladder as `wave`, re-hued and brightened to the Streets reference's water
+ * (`hsl(200, 100%, 80%)`). `sky.200` is that colour; the rest of the ladder is the dark-mode
+ * inversion and the ocean-label step.
+ */
+declare const sky: {
+    readonly 100: "#CCEEFF";
+    readonly 200: "#A7E2FF";
+    readonly 300: "#8ACFF0";
+    readonly 400: "#73B7D7";
+    readonly 500: "#5A9CBC";
+    readonly 600: "#387D9C";
+    readonly 700: "#155F7C";
+    readonly 800: "#004057";
+    readonly 900: "#002837";
+    readonly 950: "#001B27";
+    readonly 980: "#000F17";
+};
 /** Vegetation, hue 152: park, wood, scrub. */
 declare const verdant: {
     readonly 100: "#D3F1DA";
@@ -74,19 +117,8 @@ declare const sandstone: {
     readonly 500: "#A19070";
 };
 /**
- * Pure neutrals, zero chroma. The `muted` pair only.
- *
- * `ink` carries a hue-212 cool cast, which is right for every other flavour and wrong for this
- * one: `muted` exists to vanish under a customer's data, and a basemap with *any* hue biases the
- * colours laid on top of it. So muted gets its own ramp where R=G=B exactly.
- *
- * Calibrated against Mapbox Light and Protomaps' `WHITE`, whose land/water/building relationships
- * this flavour follows: land a light grey, roads *brighter* than the land rather than darker,
- * buildings a single step down, and water the only tone with any real weight.
- *
- * Their label colours are deliberately NOT copied. Protomaps `WHITE` puts `state_label` #b3b3b3
- * on #ffffff, roughly 2:1, which fails the 4.5:1 floor `cartography.test.ts` enforces. The
- * structure is worth borrowing; the label contrast is not.
+ * Pure neutrals, zero chroma. Everything on `muted` except its water (see `mist`), plus the
+ * road casings on `base`. Kept R=G=B so `muted` is greyscale in fact rather than in name.
  */
 declare const graphite: {
     readonly 25: "#FAFAFA";
@@ -102,6 +134,71 @@ declare const graphite: {
     readonly 900: "#232323";
     readonly 1000: "#0B0B0B";
 };
+/**
+ * Muted water: the `wave` lightness ladder at zero chroma. `muted` is greyscale end to end,
+ * water included, so this ramp exists for one reason — it is the ramp the *water* seed
+ * recolours when a theme is applied to `muted`, which the land ramp (`graphite`) is not.
+ * `mist.200` is the light-mode fill; `mist.980` the dark-mode inversion so water stays darker
+ * than land.
+ */
+declare const mist: {
+    readonly 100: "#E7E7E7";
+    readonly 200: "#D7D7D7";
+    readonly 300: "#C4C4C4";
+    readonly 400: "#ACACAC";
+    readonly 500: "#929292";
+    readonly 600: "#757575";
+    readonly 700: "#575757";
+    readonly 800: "#3A3A3A";
+    readonly 900: "#242424";
+    readonly 950: "#171717";
+    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
+ * (`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`).
+ */
+declare const jade: {
+    readonly 25: "#F1F9F4";
+    readonly 50: "#E6F4ED";
+    readonly 100: "#D7EEE2";
+    readonly 200: "#C3E6D4";
+    readonly 300: "#ACDDC4";
+    readonly 400: "#8BCFAF";
+    readonly 500: "#56BB90";
+    readonly 600: "#459975";
+    readonly 700: "#327357";
+    readonly 800: "#21513D";
+    readonly 850: "#173C2C";
+    readonly 900: "#0E2A1E";
+    readonly 950: "#071C13";
+    readonly 1000: "#030F09";
+};
+/**
+ * Cobalt, hue 267. The `blueprint` pair: royal blue field with navy roads and pale blue water
+ * in dark, blue lines on blue-white paper in light. Same lightness ladder as `ink`. Chroma
+ * peaks at the field step (`700`, `0.23` — the reference's `#1c44dc`) and falls away on both
+ * sides, so the pale steps stay paper-like and the navy steps stay ink-like.
+ */
+declare const cobalt: {
+    readonly 25: "#F4F7FB";
+    readonly 50: "#ECF0F9";
+    readonly 100: "#E1E8F7";
+    readonly 200: "#D2DCF5";
+    readonly 300: "#C0CFF3";
+    readonly 400: "#A8BDF1";
+    readonly 500: "#84A2EE";
+    readonly 600: "#587EEA";
+    readonly 700: "#2C4EE5";
+    readonly 800: "#243D93";
+    readonly 850: "#1D2F65";
+    readonly 900: "#162241";
+    readonly 950: "#0F1629";
+    readonly 1000: "#080B15";
+};
 
 /**
  * The unmap cartography authoring surface, moved here from apps/gateway/src/flavors.ts so the
@@ -113,11 +210,17 @@ declare const graphite: {
  * cannot drift out of step with the surface roads they mirror.
  */
 /**
- * Appended, never inserted. This array's order drives the style picker in the unmap.dev builder,
- * so inserting a base mid-array silently reorders a control people have already learned.
+ * 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` and `street` were retired; they are not listed here. Short preset codes still
+ * decode those slots via `normalizeThemeBase` / the slot table in `preset.ts`.
  */
-declare const THEME_BASES: readonly ["base", "muted", "relief", "street", "outdoor"];
+declare const THEME_BASES: readonly ["base", "muted", "outdoor", "decimal", "blueprint"];
 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;
 declare const MODES: readonly ["light", "dark"];
 type ThemeMode = (typeof MODES)[number];
 interface RoadRamp {
@@ -198,21 +301,26 @@ interface Recipe {
 declare function makeFlavor(r: Recipe): Flavor;
 
 /**
- * The five ramp families (plus ember) a recipe draws from. `buildRecipes` is parameterized on
+ * The ramp families (plus ember) a recipe draws from. `buildRecipes` is parameterized on
  * this so the theme generator can re-emit the same recipes from *generated* ramps — same
  * lightness ladders, a customer's hues — while the stock `RECIPES` stay byte-identical to the
  * hand-tuned originals (they are `buildRecipes(STOCK_RAMPS)`).
  */
 interface RampSet {
     ink: typeof ink;
+    paper: typeof paper;
     wave: typeof wave;
+    sky: typeof sky;
     verdant: typeof verdant;
     sandstone: typeof sandstone;
     graphite: typeof graphite;
+    mist: typeof mist;
+    jade: typeof jade;
+    cobalt: typeof cobalt;
     ember: typeof ember;
 }
 declare const STOCK_RAMPS: RampSet;
-/** Build the eight recipes from a ramp set. Stock ramps in → the shipped cartography out. */
+/** Build the shipped recipes from a ramp set. Stock ramps in → the shipped cartography out. */
 declare function buildRecipes(r: RampSet): Record<ThemeBase, Record<ThemeMode, Recipe>>;
 declare const RECIPES: Record<ThemeBase, Record<ThemeMode, Recipe>>;
 
@@ -224,8 +332,8 @@ declare const RECIPES: Record<ThemeBase, Record<ThemeMode, Recipe>>;
  * arrive on public query strings and are composed into style JSON the gateway signs its own
  * asset URLs into. `validateTheme` is the only door in.
  *
- * `base` names the structural chassis (one of the five shipped styles); each half carries only
- * sparse overrides on that chassis, so presets are near-empty documents and codes stay short.
+ * `base` names the style (one of the shipped styles); each half carries only sparse overrides
+ * on that style, so presets are near-empty documents and codes stay short.
  */
 type DeepPartial<T> = {
     [K in keyof T]?: NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
@@ -309,11 +417,48 @@ declare function validateTheme(input: unknown): ThemeDoc;
  */
 declare const THEME_CODE_PREFIX = "ut1.";
 declare const MAX_CODE_LENGTH = 4096;
-/** Validate and encode a theme document to its compact `ut1.` code. Throws `ThemeError`. */
+/** Validate and encode a theme document. Curated/simple themes become a short `u…` preset; anything else is `ut1.` + deflate. Throws `ThemeError`. */
 declare function encodeTheme(doc: ThemeDoc): Promise<string>;
-/** Decode and validate a compact `ut1.` code. Every failure lands as `ThemeError`. */
+/** 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
+ * 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        styles added later (decimal, blueprint); u07 is the one spare slot
+ *   u08…            named theme preset on one of the original style slots
+ *   u5K…            named theme preset on one of the later slots
+ *   longer          custom seed colours (4× RGB) on any style
+ *
+ * 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.
+ *
+ * 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.
+ */
+declare const PRESET_CODE_PREFIX = "u";
+declare const PRESET_CODE_RE: RegExp;
+declare function isThemePresetCode(code: string): boolean;
+/** Registry key for a preset name: `process ink` → `processInk`. */
+declare function presetId(name: string): string;
+/**
+ * Pack a theme into a short preset code, or `null` when the document is not one of the
+ * representable shapes (caller falls back to `ut1.`).
+ */
+declare function encodePreset(doc: ThemeDoc): string | null;
+/** Expand a short preset code to a validated ThemeDoc. Throws `ThemeError`. */
+declare function decodePreset(code: string): ThemeDoc;
+/**
+ * Registry key for a curated preset (`base`, `processInk`, `boreal`, …), or `undefined` when
+ * the theme is a custom code that is not one of the named `MAP_THEMES` entries (named presets
+ * are published on the `base` style only).
+ */
+declare function registryThemeKey(doc: ThemeDoc): string | undefined;
+
 /**
  * Platform drawing defaults for the two client-side overlays a theme styles. These are exactly
  * the convention the unmap.dev hero has always drawn: a magenta pin, and a route as a solid
@@ -322,7 +467,7 @@ declare function decodeTheme(code: string): Promise<ThemeDoc>;
 declare const DEFAULT_MARKER: Required<MarkerTheme>;
 declare const DEFAULT_ROUTE: Required<RouteTheme>;
 interface ResolvedTheme {
-    /** `<base>-<mode>`, the chassis name — what selects sprites and terrain behaviour. */
+    /** `<base>-<mode>`, the flavour name — what selects sprites and terrain behaviour. */
     flavorName: `${ThemeBase}-${ThemeMode}`;
     flavor: Flavor;
     marker: Required<MarkerTheme>;
@@ -336,7 +481,7 @@ interface ResolvedTheme {
 declare function mergeRecipe(base: Recipe, overrides?: BasemapOverrides): Recipe;
 /**
  * Resolve one half of a theme into everything a renderer needs: the expanded Flavor, the
- * chassis name, and marker/route styles with defaults filled in.
+ * flavour name, and marker/route styles with defaults filled in.
  */
 declare function resolveTheme(doc: ThemeDoc, mode: ThemeMode): ResolvedTheme;
 
@@ -360,8 +505,12 @@ 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.
+ *
+ * Named after the style itself — `base`, `muted`, `outdoor`, `decimal`, `blueprint` — the same word the homepage, the
+ * SDK's `style` option and the gateway URL use. The theme presets (`process ink`, `boreal`, …)
+ * are a separate set layered on a style; a style never borrows one's name.
  */
-declare const PRESET_THEMES: Record<ThemeBase, ThemeDoc>;
+declare const STYLE_THEMES: Record<ThemeBase, ThemeDoc>;
 
 /**
  * Minimal sRGB ↔ OKLCH conversion (Björn Ottosson's OKLab constants), plus a chroma-reducing
@@ -395,25 +544,28 @@ declare const DEFAULT_SEEDS: Required<ThemeSeeds>;
  * Generate a full theme from seed colours. Deterministic; the result always clears the label
  * floors in both modes (enforced, and asserted by the hue-sweep test).
  *
- * Family mapping: `land` recolours the neutral spine (and `muted`'s graphite, at a whisper of
- * chroma — that flavour exists to vanish under data), `water` the wave ramp, `nature` the
- * verdant ramp. Warm landcover (sandstone), POI accents, white road fills and the street
- * motorway orange stay stock: they are tuned relationships, not identity. `accent` styles the
- * marker and route overlays only — it never enters the basemap, same rule as the brand magenta.
+ * Family mapping: `land` recolours the land spines — `ink`, `base`'s `paper`, `muted`'s
+ * `graphite` at a whisper of chroma (that style exists to vanish under data), and the
+ * single-hue families of `decimal` (`jade`) and `blueprint` (`cobalt`) at full chroma, so a
+ * seed can carry them to any hue. `water` recolours the wave, sky, and mist ramps (`mist` is
+ * greyscale in stock `muted` and takes the water seed's hue outright), `nature` the verdant
+ * ramp. Warm landcover (sandstone), POI accents and white road fills stay stock: they
+ * are tuned relationships, not identity. `accent` styles the marker and route overlays only —
+ * it never enters the basemap, same rule as the brand magenta.
  */
 declare function generateTheme(base: ThemeBase, seeds: ThemeSeeds): ThemeDoc;
 
 /**
- * Curated seed palettes for the builder's simple mode — the hand-picked starting points, named
+ * The named theme presets of the builder's simple mode — the hand-picked starting points, named
  * for Canadian landscapes. Each is just a seed trio + accent; `generateTheme` does the rest,
  * and its contrast guarantee holds for these like any other seeds (asserted in tests).
  */
-interface SeedPalette {
-    /** Display name, lowercase like the flavour names. Not translated — these are names. */
+interface ThemePreset {
+    /** Display name, lowercase like the style names. Not translated — these are names. */
     name: string;
     seeds: Required<ThemeSeeds>;
 }
-declare const SEED_PALETTES: SeedPalette[];
+declare const THEME_PRESETS: ThemePreset[];
 /**
  * A random but *harmonic* seed trio — the shuffle button. Hues are related (water lands
  * cool-of-complementary, nature analogous-of-triadic, the accent opposes the land) and chroma
@@ -424,4 +576,4 @@ declare const SEED_PALETTES: SeedPalette[];
  */
 declare function shuffleSeeds(rng?: () => number): Required<ThemeSeeds>;
 
-export { type BasemapOverrides, type ContrastWarning, DEFAULT_MARKER, DEFAULT_ROUTE, DEFAULT_SEEDS, type DeepPartial, LABEL_PAIRS, type LabelRamp, MAX_CODE_LENGTH, MODES, type MarkerTheme, type Oklch, PRESET_THEMES, RECIPES, type RampSet, type Recipe, type ResolvedTheme, type RoadRamp, type RouteTheme, SEED_PALETTES, STOCK_RAMPS, type SeedPalette, THEME_BASES, THEME_CODE_PREFIX, type ThemeBase, type ThemeDoc, ThemeError, type ThemeHalf, type ThemeMode, type ThemeSeeds, buildRecipes, contrast, contrastWarnings, decodeTheme, ember, encodeTheme, generateTheme, graphite, hexToOklch, ink, makeFlavor, mergeRecipe, oklchToHex, resolveTheme, sandstone, shuffleSeeds, validateTheme, verdant, wave };
+export { type BasemapOverrides, type ContrastWarning, DEFAULT_MARKER, DEFAULT_ROUTE, DEFAULT_SEEDS, type DeepPartial, LABEL_PAIRS, type LabelRamp, MAX_CODE_LENGTH, MODES, type MarkerTheme, type Oklch, PRESET_CODE_PREFIX, PRESET_CODE_RE, 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 ThemeMode, type ThemePreset, type ThemeSeeds, buildRecipes, cobalt, contrast, contrastWarnings, decodePreset, decodeTheme, ember, encodePreset, encodeTheme, generateTheme, graphite, hexToOklch, ink, isThemePresetCode, jade, makeFlavor, mergeRecipe, mist, normalizeThemeBase, oklchToHex, paper, presetId, registryThemeKey, resolveTheme, sandstone, shuffleSeeds, sky, validateTheme, verdant, wave };