@escape-game-over/atlas 0.1.110 → 0.1.112

package/README.md

@@ -72,7 +72,10 @@ export const { project, redirects } = atlas.project(
 
         enabledLocales: ["el-GR", "en-US"],
         overrideRouting: { defaultLocale: "el-GR", prefixDefaultLocale: true },
-        clock: { "el-GR": "h23", "en-US": "h12" }, // how each language prints times
+        formats: {
+            clock: { "el-GR": "h23", "en-US": "h12" }, // how each language prints times
+            prices: { decimals: "always" }, // "18,00 €", each page in its own locale
+        },
 
         overrideMessages: {
             // Greek only — the English copy still falls through to the default catalog.
@@ -244,8 +247,9 @@ regression-tested by an `@ts-expect-error` suite.
 | A `robots` directive that is not a real one                                     | error — the vocabulary is a union            |
 | A project `url` that is not `https://`, or ends in a slash                      | error                                        |
 | `defaultLocale` not among the project's `enabledLocales`                        | error                                        |
-| A `clock` leaving out a published locale, or naming an unpublished one          | error                                        |
+| A `formats.clock` leaving out a published locale, or naming an unpublished one  | error                                        |
 | `site.clockFor` on a project that declares no clock                             | throws, naming the project                   |
+| `site.priceFormatFor` on a project that declares no price format                | throws, naming the project                   |
 | An unknown field in a project declaration                                       | error — a typo cannot sit there unread       |
 | Two routes resolving to the same URL                                            | build throws, naming both                    |
 | A site icon that is not square, a multiple of 48px, and PNG                     | build throws                                 |

package/docs/checks.md

@@ -42,7 +42,8 @@ sees.
 | unknown message key, or an override dropping a `{placeholder}`                            | two routes resolving to the same URL                                    |
 | a message the project declared mandatory and never wrote (`CatalogCovers`)                |                                                                         |
 | copy or a locale label written for a locale outside `enabledLocales`                      |                                                                         |
-| a `clock` leaving out a published locale, or naming one outside `enabledLocales`          | the same, for a project that was not type-checked first                 |
+| a `formats.clock` leaving out a published locale, or naming one outside `enabledLocales`  | the same, for a project that was not type-checked first                 |
+| a `formats.prices.locale` the project does not publish                                    | the same, for a project that was not type-checked first                 |
 | a slug whose translation sits at a different depth, in the registry or across the overlay | the same, when a slug is not a literal (computed, or from an env var)   |
 | unknown route id, or a locale the site does not ship                                      | a locale published twice                                                |
 | a malformed language tag (`en_US`, `en-us`, `EN-US`, bare `en`)                           | an icon that is not square, a multiple of 48, and PNG                   |
@@ -131,7 +132,7 @@ dependencies at all. Vitest type-checks them itself when it runs them.
 | `money.test.ts`            | a bare count widened to a band, the span of a table, the gaps and overlaps that throw, and an audience priced twice                                                                                  |
 | `url.test.ts`              | joining an origin to a path exactly once, and normalising the origin an `@id` is built from                                                                                                          |
 | `warn.test.ts`             | the shared prefix, and reducing a URL to its path                                                                                                                                                    |
-| `filters.test.ts`          | folding both sides of a query, how each kind narrows, the four URL decisions, and attach/detach                                                                                                      |
+| `filters.test.ts`          | folding both sides of a query, how each kind narrows, the four URL decisions, values no item holds, and attach/detach                                                                                |
 | `filters-view.test.ts`     | the write-back into the input and that it is skipped when unchanged, clear taking focus, and the nesting order                                                                                       |
 | `build-cache.test.ts`      | that an unset `CI_ASTRO_CACHE` yields nothing, so Astro's own `cacheDir` default survives                                                                                                            |
 

package/docs/client-scripts.md

@@ -241,6 +241,12 @@ instead of flashing the whole list back. Nothing writes to the URL before
 `attach`, because `attach` is what reads it — a `set` on an unattached instance
 would overwrite state nobody had loaded.
 
+A choice no item holds, or a flag no item carries, is a stale or mistyped link:
+reading it — on `attach` and on the back button — takes it as no choice, and
+replaces the URL without it. Otherwise `?category=castle` showed an empty list
+with nothing pressed, not even "All". A `text` query is left alone: it matches
+words, not values, and finding nothing is a fair answer to it.
+
 A flag is on by being there, as an HTML boolean attribute is: written as the bare
 `?featured`, and **absent** when off. Reading asks only whether the name is
 present, so `?featured=1` from an older link still reads as on — and so does a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.110",
+    "version": "0.1.112",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/astro/axon-event.ts

@@ -1,4 +1,4 @@
-import type { CurrencyCode } from "../money.ts";
+import type { CurrencyCode } from "../currency.ts";
 import { readConsent } from "./consent.ts";
 
 /**

package/src/astro/filters.ts

@@ -199,6 +199,18 @@ export function filters<const F extends FieldMap, T>(
         return { item, values, haystacks };
     });
 
+    // What the items hold, per choice and flag: a link asking for anything
+    // else is stale or mistyped, and is read as no choice rather than an empty
+    // list with nothing pressed.
+    const held = new Map<string, ReadonlySet<unknown>>();
+    for (const name of names) {
+        if (kindOf(name) === "text") continue;
+        held.set(
+            name,
+            new Set(entries.flatMap((entry) => entry.values[name] as unknown))
+        );
+    }
+
     const empty = (name: keyof F & string): StateValue<F[typeof name]> =>
         (kindOf(name) === "flag" ? false : "") as StateValue<F[typeof name]>;
 
@@ -287,9 +299,11 @@ export function filters<const F extends FieldMap, T>(
         matched = next;
     }
 
-    function readUrl(): void {
+    /** Applies the URL; says whether it asked for anything no item holds. */
+    function readUrl(): boolean {
         const search = new URLSearchParams(window.location.search);
         const next: Record<string, string | boolean> = {};
+        let dropped = false;
         for (const name of names) {
             if (!inUrl.includes(name)) {
                 // A state-only field is not in the URL, so the URL has nothing
@@ -300,12 +314,17 @@ export function filters<const F extends FieldMap, T>(
             }
             // A flag is on by being there, as an HTML boolean attribute is:
             // `?featured`, and `?featured=1` from an older link, alike.
-            next[name] =
+            const value =
                 kindOf(name) === "flag"
                     ? search.has(name)
                     : (search.get(name) ?? "");
+            const unheld =
+                value !== empty(name) && held.get(name)?.has(value) === false;
+            next[name] = unheld ? empty(name) : value;
+            if (unheld) dropped = true;
         }
         state = next as FilterState<F>;
+        return dropped;
     }
 
     function writeUrl(history: "push" | "replace"): void {
@@ -424,8 +443,9 @@ export function filters<const F extends FieldMap, T>(
             window.addEventListener(
                 "popstate",
                 () => {
-                    readUrl();
+                    const dropped = readUrl();
                     recompute();
+                    if (dropped) writeUrl("replace");
                     announce();
                 },
                 { signal: events.signal }
@@ -435,8 +455,11 @@ export function filters<const F extends FieldMap, T>(
             // Read before the first announcement: the URL may already carry a
             // state, and announcing the empty one first flashes the unfiltered
             // list over it.
-            readUrl();
+            // A value no item holds leaves the address bar as well, replaced
+            // rather than pushed: it is a correction, not a step to go back to.
+            const dropped = readUrl();
             recompute();
+            if (dropped) writeUrl("replace");
             announce();
 
             return () => {

package/src/astro/google-event.ts

@@ -2,7 +2,7 @@ import {
     GOOGLE_EVENT_GLOBAL,
     type GoogleEventSink,
 } from "../analytics/google.ts";
-import type { CurrencyCode } from "../money.ts";
+import type { CurrencyCode } from "../currency.ts";
 import type { DeclaredEvent, EventDataArgs } from "./event-data.ts";
 
 /** GA4's recommended events that carry items and revenue. */

package/src/astro/meta-event.ts

@@ -1,4 +1,4 @@
-import type { CurrencyCode } from "../money.ts";
+import type { CurrencyCode } from "../currency.ts";
 import type { DeclaredEvent, EventDataArgs } from "./event-data.ts";
 
 /** Meta's standard events, which its ad optimisation understands by name. */

package/src/astro/snap-event.ts

@@ -1,4 +1,4 @@
-import type { CurrencyCode } from "../money.ts";
+import type { CurrencyCode } from "../currency.ts";
 import { readConsent } from "./consent.ts";
 
 /** Snap's standard events that a website sends. */

package/src/astro/tiktok-event.ts

@@ -1,4 +1,4 @@
-import type { CurrencyCode } from "../money.ts";
+import type { CurrencyCode } from "../currency.ts";
 import type { DeclaredEvent, EventDataArgs } from "./event-data.ts";
 
 /** TikTok's standard events, by their current names (May 2025 onwards). */

package/src/config.ts

@@ -1,8 +1,9 @@
+import type { CountryCode } from "./countries.ts";
 import type { Fonts } from "./fonts.ts";
 import type { LlmsConfig } from "./llms.ts";
 import type { RobotsConfig } from "./robots.ts";
 import type { SitemapConfig } from "./sitemap.ts";
-import type { NoExcessKeys, StringKeys } from "./types.ts";
+import type { Letter, NoExcessKeys, StringKeys } from "./types.ts";
 
 export interface LocaleMeta {
     /** Name of the language, written in that language. */
@@ -22,29 +23,47 @@ export interface ResolvedLocaleMeta {
     readonly ogLocale: string;
 }
 
+/** A language subtag: two or three lowercase letters, `en`, `ast`. */
+type LanguageSubtag =
+    | `${Lowercase<Letter>}${Lowercase<Letter>}`
+    | `${Lowercase<Letter>}${Lowercase<Letter>}${Lowercase<Letter>}`;
 /**
- * A well-formed language tag, or `never`.
+ * A region subtag: a country, as `CountryCode` lists them, `US`. Not the
+ * three-digit areas (`419`, Latin America): a locale names the one country a
+ * site serves, and it is a URL segment.
+ */
+type RegionSubtag = CountryCode;
+
+/**
+ * A well-formed language tag, or `never`: a language of two or three
+ * lowercase letters and a region that is a country's code, `en-US`, `ast-ES`.
  *
  * The region is required: `en` is rejected, `en-US` accepted. A bare language
  * leaves the territory to the reader, and `en-US` and `en-GB` differ in spelling,
  * currency and date order — decisions worth stating rather than inferring.
  *
- * Checks shape and casing only, so `en_US`, `en-us` and `EN-US` are all
- * rejected. It deliberately does not check that the subtags are *real*: the
+ * So `en_US`, `en-us`, `EN-US`, `-US`, `en-U-S`, `es-419` and `en-XX` are all
+ * rejected, and so is a script subtag (`sr-Latn-RS`). The region is checked
+ * against the real countries; the language only for its shape: the
  * authoritative list is the IANA Language Subtag Registry, thousands of entries
  * that would go stale the moment they were copied into this folder.
+ *
+ * A check on one literal rather than a type of all tags: as a single type the
+ * shape spells out to more strings than TypeScript represents.
  */
 export type LanguageTag<T extends string> =
-    T extends `${infer Lang}-${infer Region}`
-        ? Lang extends Lowercase<Lang>
-            ? Region extends Uppercase<Region>
+    T extends `${infer Language}-${infer Region}`
+        ? Language extends LanguageSubtag
+            ? Region extends RegionSubtag
                 ? T
                 : never
             : never
         : never;
 
+/** The same rule at run time, for a project that was not type-checked first. */
+
 interface MalformedLanguageTag<T extends string> {
-    readonly __MALFORMED_LANGUAGE_TAG__: `"${T}" is not a well-formed language tag: expected a lowercase language and an uppercase region, like "en-US"`;
+    readonly __MALFORMED_LANGUAGE_TAG__: `"${T}" is not a well-formed language tag: expected a language of two or three lowercase letters and a country's code as its region, like "en-US"`;
 }
 
 /**

package/src/currency.ts

@@ -0,0 +1,165 @@
+/**
+ * An ISO 4217 currency code: `"EUR"`, `"RON"`, `"GBP"`.
+ *
+ * A code rather than a symbol — `€`, `lei` — because two currencies can share a
+ * symbol, and `priceCurrency` is read as a code.
+ *
+ * Circulating currencies from ISO 4217 List One (SIX, published 2026-09-17):
+ * fund, precious-metal, testing and accounting-unit codes left out.
+ */
+export type CurrencyCode =
+    | "AED"
+    | "AFN"
+    | "ALL"
+    | "AMD"
+    | "AOA"
+    | "ARS"
+    | "AUD"
+    | "AWG"
+    | "AZN"
+    | "BAM"
+    | "BBD"
+    | "BDT"
+    | "BHD"
+    | "BIF"
+    | "BMD"
+    | "BND"
+    | "BOB"
+    | "BRL"
+    | "BSD"
+    | "BTN"
+    | "BWP"
+    | "BYN"
+    | "BZD"
+    | "CAD"
+    | "CDF"
+    | "CHF"
+    | "CLP"
+    | "CNY"
+    | "COP"
+    | "CRC"
+    | "CUP"
+    | "CVE"
+    | "CZK"
+    | "DJF"
+    | "DKK"
+    | "DOP"
+    | "DZD"
+    | "EGP"
+    | "ERN"
+    | "ETB"
+    | "EUR"
+    | "FJD"
+    | "FKP"
+    | "GBP"
+    | "GEL"
+    | "GHS"
+    | "GIP"
+    | "GMD"
+    | "GNF"
+    | "GTQ"
+    | "GYD"
+    | "HKD"
+    | "HNL"
+    | "HTG"
+    | "HUF"
+    | "IDR"
+    | "ILS"
+    | "INR"
+    | "IQD"
+    | "IRR"
+    | "ISK"
+    | "JMD"
+    | "JOD"
+    | "JPY"
+    | "KES"
+    | "KGS"
+    | "KHR"
+    | "KMF"
+    | "KPW"
+    | "KRW"
+    | "KWD"
+    | "KYD"
+    | "KZT"
+    | "LAK"
+    | "LBP"
+    | "LKR"
+    | "LRD"
+    | "LSL"
+    | "LYD"
+    | "MAD"
+    | "MDL"
+    | "MGA"
+    | "MKD"
+    | "MMK"
+    | "MNT"
+    | "MOP"
+    | "MRU"
+    | "MUR"
+    | "MVR"
+    | "MWK"
+    | "MXN"
+    | "MYR"
+    | "MZN"
+    | "NAD"
+    | "NGN"
+    | "NIO"
+    | "NOK"
+    | "NPR"
+    | "NZD"
+    | "OMR"
+    | "PAB"
+    | "PEN"
+    | "PGK"
+    | "PHP"
+    | "PKR"
+    | "PLN"
+    | "PYG"
+    | "QAR"
+    | "RON"
+    | "RSD"
+    | "RUB"
+    | "RWF"
+    | "SAR"
+    | "SBD"
+    | "SCR"
+    | "SDG"
+    | "SEK"
+    | "SGD"
+    | "SHP"
+    | "SLE"
+    | "SOS"
+    | "SRD"
+    | "SSP"
+    | "STN"
+    | "SVC"
+    | "SYP"
+    | "SZL"
+    | "THB"
+    | "TJS"
+    | "TMT"
+    | "TND"
+    | "TOP"
+    | "TRY"
+    | "TTD"
+    | "TWD"
+    | "TZS"
+    | "UAH"
+    | "UGX"
+    | "USD"
+    | "UYU"
+    | "UZS"
+    | "VED"
+    | "VES"
+    | "VND"
+    | "VUV"
+    | "WST"
+    | "XAF"
+    | "XCD"
+    | "XCG"
+    | "XOF"
+    | "XPF"
+    | "YER"
+    | "ZAR"
+    | "ZMW"
+    | "ZWG";

package/src/index.ts

@@ -146,6 +146,12 @@ export {
     countriesFor,
     type NamedCountry,
 } from "./countries.ts";
+// `quantitiesOf`, `quantityRange` and `isContiguous` are deliberately not here.
+// They are how lib decides between "2–6" and "2, 4, 6", and a consumer holding
+// them writes that decision a second time — which is how `llms.txt` came to
+// advertise a range for a room that skips sizes. `formatQuantities` answers it
+// for prose and `quantitiesFor` for structured data; both read the same tiers.
+export type { CurrencyCode } from "./currency.ts";
 export type { GeneratedFile } from "./file.ts";
 export type { PublicFilePath, PublicFileRegistry } from "./files.ts";
 export type { Font, Fonts } from "./fonts.ts";
@@ -250,19 +256,12 @@ export {
     type ShareImage,
     type SiteVerification,
 } from "./meta/index.ts";
-// `quantitiesOf`, `quantityRange` and `isContiguous` are deliberately not here.
-// They are how lib decides between "2–6" and "2, 4, 6", and a consumer holding
-// them writes that decision a second time — which is how `llms.txt` came to
-// advertise a range for a room that skips sizes. `formatQuantities` answers it
-// for prose and `quantitiesFor` for structured data; both read the same tiers.
 export {
     type AudiencePrice,
     type AudienceTier,
     amountAt,
     assertAudiences,
     assertPriceTiers,
-    type CurrencyCode,
-    formatPrice,
     formatQuantities,
     type Price,
     type PriceTier,
@@ -272,6 +271,11 @@ export {
     type TieredPrice,
     tierRange,
 } from "./money.ts";
+export {
+    formatPrice,
+    type PriceDecimals,
+    type PriceFormat,
+} from "./price-format.ts";
 export type {
     AddedCatalog,
     DefinedProject,

package/src/money.ts

@@ -1,171 +1,6 @@
+import type { CurrencyCode } from "./currency.ts";
 import type { NonEmpty } from "./types.ts";
 
-/**
- * An ISO 4217 currency code: `"EUR"`, `"RON"`, `"GBP"`.
- *
- * A code rather than a symbol — `€`, `lei` — because two currencies can share a
- * symbol, and `priceCurrency` is read as a code.
- *
- * Circulating currencies from ISO 4217 List One (SIX, published 2026-09-17):
- * fund, precious-metal, testing and accounting-unit codes left out.
- */
-export type CurrencyCode =
-    | "AED"
-    | "AFN"
-    | "ALL"
-    | "AMD"
-    | "AOA"
-    | "ARS"
-    | "AUD"
-    | "AWG"
-    | "AZN"
-    | "BAM"
-    | "BBD"
-    | "BDT"
-    | "BHD"
-    | "BIF"
-    | "BMD"
-    | "BND"
-    | "BOB"
-    | "BRL"
-    | "BSD"
-    | "BTN"
-    | "BWP"
-    | "BYN"
-    | "BZD"
-    | "CAD"
-    | "CDF"
-    | "CHF"
-    | "CLP"
-    | "CNY"
-    | "COP"
-    | "CRC"
-    | "CUP"
-    | "CVE"
-    | "CZK"
-    | "DJF"
-    | "DKK"
-    | "DOP"
-    | "DZD"
-    | "EGP"
-    | "ERN"
-    | "ETB"
-    | "EUR"
-    | "FJD"
-    | "FKP"
-    | "GBP"
-    | "GEL"
-    | "GHS"
-    | "GIP"
-    | "GMD"
-    | "GNF"
-    | "GTQ"
-    | "GYD"
-    | "HKD"
-    | "HNL"
-    | "HTG"
-    | "HUF"
-    | "IDR"
-    | "ILS"
-    | "INR"
-    | "IQD"
-    | "IRR"
-    | "ISK"
-    | "JMD"
-    | "JOD"
-    | "JPY"
-    | "KES"
-    | "KGS"
-    | "KHR"
-    | "KMF"
-    | "KPW"
-    | "KRW"
-    | "KWD"
-    | "KYD"
-    | "KZT"
-    | "LAK"
-    | "LBP"
-    | "LKR"
-    | "LRD"
-    | "LSL"
-    | "LYD"
-    | "MAD"
-    | "MDL"
-    | "MGA"
-    | "MKD"
-    | "MMK"
-    | "MNT"
-    | "MOP"
-    | "MRU"
-    | "MUR"
-    | "MVR"
-    | "MWK"
-    | "MXN"
-    | "MYR"
-    | "MZN"
-    | "NAD"
-    | "NGN"
-    | "NIO"
-    | "NOK"
-    | "NPR"
-    | "NZD"
-    | "OMR"
-    | "PAB"
-    | "PEN"
-    | "PGK"
-    | "PHP"
-    | "PKR"
-    | "PLN"
-    | "PYG"
-    | "QAR"
-    | "RON"
-    | "RSD"
-    | "RUB"
-    | "RWF"
-    | "SAR"
-    | "SBD"
-    | "SCR"
-    | "SDG"
-    | "SEK"
-    | "SGD"
-    | "SHP"
-    | "SLE"
-    | "SOS"
-    | "SRD"
-    | "SSP"
-    | "STN"
-    | "SVC"
-    | "SYP"
-    | "SZL"
-    | "THB"
-    | "TJS"
-    | "TMT"
-    | "TND"
-    | "TOP"
-    | "TRY"
-    | "TTD"
-    | "TWD"
-    | "TZS"
-    | "UAH"
-    | "UGX"
-    | "USD"
-    | "UYU"
-    | "UZS"
-    | "VED"
-    | "VES"
-    | "VND"
-    | "VUV"
-    | "WST"
-    | "XAF"
-    | "XCD"
-    | "XCG"
-    | "XOF"
-    | "XPF"
-    | "YER"
-    | "ZAR"
-    | "ZMW"
-    | "ZWG";
-
 /**
  * An amount and what it is denominated in, kept together.
  *
@@ -501,22 +336,3 @@ export function amountAt(
     }
     return undefined;
 }
-
-/**
- * A price as a reader in `locale` writes it: the currency's symbol and that
- * language's separators, and no decimals on a whole amount — "£25", not
- * "£25.00", while "€12.50" keeps its cents.
- *
- * Whole amounts drop the decimals because that is how a price list reads; a
- * table of "25.00, 22.00, 20.00" says nothing "25, 22, 20" does not. An amount
- * with cents shows two, so a price is never rounded on the way to the page.
- */
-export function formatPrice(price: Price, locale: string): string {
-    const whole = Number.isInteger(price.amount);
-    return new Intl.NumberFormat(locale, {
-        style: "currency",
-        currency: price.currency,
-        minimumFractionDigits: whole ? 0 : 2,
-        maximumFractionDigits: whole ? 0 : 2,
-    }).format(price.amount);
-}

package/src/price-format.ts

@@ -0,0 +1,49 @@
+import type { Price } from "./money.ts";
+
+/**
+ * Whether a whole amount shows its decimals: `"always"` writes "18,00 €" and
+ * "$18.00"; `"whenNeeded"` writes "£18" and "18 €". Either way an amount with
+ * cents shows the currency's digits, so a price is never rounded on the way to
+ * the page.
+ */
+export type PriceDecimals = "always" | "whenNeeded";
+
+/**
+ * How a site writes its prices: a project's `formats.prices`. The decimals are
+ * the store's, from its price list and currency, so one rule serves every
+ * language. The locale is optional: without it each page writes prices in its
+ * own language's way ("€18.00" in English, "18,00 €" in Portuguese); with it,
+ * every page writes them the way of that one of the site's languages.
+ */
+export interface PriceFormat<L extends string = string> {
+    readonly decimals: PriceDecimals;
+    /**
+     * The locale every page writes prices in: one the project publishes, so
+     * an English page can write them the store's own way, `"pt-PT"`. Each
+     * page's own without.
+     */
+    readonly locale?: L;
+}
+
+/**
+ * A price as `locale` writes it: the currency's symbol and that locale's
+ * separators, and whole amounts with or without their decimals as `decimals`
+ * says. Pages take both from `site.priceFormatFor(locale)`.
+ */
+export function formatPrice(
+    price: Price,
+    locale: string,
+    decimals: PriceDecimals
+): string {
+    // The currency's own digits otherwise, as Intl knows them: two for the
+    // euro, three for the Kuwaiti dinar, none for the yen.
+    const whole =
+        decimals === "whenNeeded" && Number.isInteger(price.amount)
+            ? { minimumFractionDigits: 0, maximumFractionDigits: 0 }
+            : {};
+    return new Intl.NumberFormat(locale, {
+        style: "currency",
+        currency: price.currency,
+        ...whole,
+    }).format(price.amount);
+}

package/src/project.ts

@@ -16,6 +16,7 @@ import type {
 } from "./i18n/define.ts";
 import type { ImageAsset } from "./image.ts";
 import type { SiteVerification, ThemeColor } from "./meta/index.ts";
+import type { PriceFormat } from "./price-format.ts";
 import type {
     ProjectRedirects,
     RedirectRule,
@@ -39,6 +40,28 @@ import type { HttpsUrl, ValidSiteUrl } from "./url.ts";
  * here. A project exports those separately, typed by the template's own
  * contract, so lib never carries data it cannot reason about.
  */
+/** How a project writes what it formats: a project's `formats`. */
+export interface ProjectFormats<L extends string> {
+    /**
+     * The clock each published language prints times on: `"h23"` for 18:00,
+     * `"h12"` for 6:00 PM. Read back with `site.clockFor(locale)`.
+     *
+     * One entry for every locale in `enabledLocales`, and none for any other,
+     * so what each page prints is written down beside the languages that print
+     * it: a bilingual Canadian site reads `{ "en-CA": "h12", "fr-CA": "h23" }`.
+     * Not taken from the locale's own default (`Intl`'s) on purpose: a site may
+     * print a 24-hour clock where its language's default is 12-hour, and that
+     * choice is the site's to state.
+     */
+    readonly clock?: Readonly<Partial<Record<L, HourCycle>>>;
+    /**
+     * How the site writes prices, one rule for every page: whether whole
+     * amounts show their decimals, and optionally the one locale they are all
+     * written in. Read back with `site.priceFormatFor(locale)`.
+     */
+    readonly prices?: PriceFormat<L>;
+}
+
 export interface ProjectInput<L extends string, Routes> {
     /**
      * Absolute origin, e.g. `https://example.com`.
@@ -107,20 +130,11 @@ export interface ProjectInput<L extends string, Routes> {
      */
     readonly enabledLocales: readonly L[];
     /**
-     * The clock each published language prints times on: `"h23"` for 18:00,
-     * `"h12"` for 6:00 PM. Read back with `site.clockFor(locale)`.
-     *
-     * One entry for every locale in `enabledLocales`, and none for any other,
-     * so what each page prints is written down beside the languages that print
-     * it: a bilingual Canadian site reads `{ "en-CA": "h12", "fr-CA": "h23" }`.
-     * Not taken from the locale's own default (`Intl`'s) on purpose: a site may
-     * print a 24-hour clock where its language's default is 12-hour, and that
-     * choice is the site's to state.
-     *
-     * Optional: a project that prints no times declares none, and
-     * `clockFor` refuses to answer for it.
+     * How this site writes what it formats: times and prices. Each format is
+     * optional, and its reader refuses to answer for a project that declares
+     * none, so one that prints times or prices has to say how.
      */
-    readonly clock?: Readonly<Partial<Record<L, HourCycle>>>;
+    readonly formats?: ProjectFormats<L>;
     /**
      * Replaces parts of the site's `defaultRouting` for this project.
      *
@@ -302,19 +316,41 @@ export type ProjectChecks<
             ? NoExcessKeys<T["overrideLocaleMeta"][K], keyof LocaleMetaOverride>
             : LocaleNotEnabled<K>;
     };
-    // The locales written must be ones this project publishes, as for
+    // The clock's locales must be ones this project publishes, as for
     // `overrideLocaleMeta` above. That every one it publishes is there is
     // checked in `ProjectOverrideChecks`: a conditional on `T` here would make
     // the constraint circular.
-    readonly clock?: {
-        readonly [K in StringKeys<
-            T["clock"]
-        >]: K extends T["enabledLocales"][number]
-            ? HourCycle
-            : LocaleNotEnabled<K>;
+    readonly formats?: {
+        readonly clock?: {
+            readonly [K in StringKeys<
+                NonNullable<T["formats"]>["clock"]
+            >]: K extends T["enabledLocales"][number]
+                ? HourCycle
+                : LocaleNotEnabled<K>;
+        };
+        // Its locale too must be one this project publishes.
+        readonly prices?: PriceFormat & {
+            readonly locale?: PriceLocaleCheck<T>;
+        };
     };
 };
 
+/** A project's price locale as written, or `never` when it names none. */
+type PriceLocaleOf<T> = T extends {
+    readonly formats?: { readonly prices?: { readonly locale?: infer Locale } };
+}
+    ? Exclude<Locale, undefined> & string
+    : never;
+
+/** The price locale, if the project publishes it; else an error naming it. */
+type PriceLocaleCheck<T> = T extends {
+    readonly enabledLocales: readonly (infer Published)[];
+}
+    ? PriceLocaleOf<T> extends Published
+        ? PriceLocaleOf<T>
+        : LocaleNotEnabled<PriceLocaleOf<T>>
+    : never;
+
 /** The same checks that map the whole override objects, in parameter position. */
 export type ProjectOverrideChecks<
     L extends string,
@@ -331,7 +367,14 @@ export type ProjectOverrideChecks<
         Routes,
         T["overrideRoutes"]
     >;
-} & (T extends { readonly addMessages: infer A }
+} & AdditionsCheck<Catalog, T> &
+    ClockCheck<T>;
+
+/** A project's own messages, checked like the catalog's: when it adds any. */
+type AdditionsCheck<
+    Catalog,
+    T extends ProjectInput<string, unknown>,
+> = T extends { readonly addMessages: infer A }
     ? {
           readonly addMessages: ValidateAdditions<
               A,
@@ -339,16 +382,23 @@ export type ProjectOverrideChecks<
               T["enabledLocales"][number]
           >;
       }
-    : unknown) &
-    (T extends { readonly clock: object }
-        ? {
-              // A clock, once declared, is declared for every page: a locale
-              // left out would have no clock to print its times on.
+    : unknown;
+
+/**
+ * A clock, once declared, is declared for every page: a locale left out would
+ * have no clock to print its times on.
+ */
+type ClockCheck<T extends ProjectInput<string, unknown>> = T extends {
+    readonly formats: { readonly clock: object };
+}
+    ? {
+          readonly formats: {
               readonly clock: {
                   readonly [K in T["enabledLocales"][number]]: HourCycle;
               };
-          }
-        : unknown);
+          };
+      }
+    : unknown;
 
 /** A project's own messages, as a catalog: none when it adds none. */
 export type AddedCatalog<P> = P extends { readonly addMessages: infer A }
@@ -406,17 +456,16 @@ export function defineProject<
         }
     }
     // The clock's rule, for the same reason.
-    if (project.clock !== undefined) {
+    const clock = project.formats?.clock;
+    if (clock !== undefined) {
         const published: readonly string[] = project.enabledLocales;
-        const missing = published.filter(
-            (locale) => !(locale in (project.clock ?? {}))
-        );
+        const missing = published.filter((locale) => !(locale in clock));
         if (missing.length > 0) {
             throw new Error(
                 `Project "${project.siteName}": clock has no ${missing.join(", ")}. A project that declares a clock gives one for every locale it publishes.`
             );
         }
-        const extra = Object.keys(project.clock).filter(
+        const extra = Object.keys(clock).filter(
             (locale) => !published.includes(locale)
         );
         if (extra.length > 0) {
@@ -425,5 +474,15 @@ export function defineProject<
             );
         }
     }
+    // The price locale's rule, for the same reason.
+    const priceLocale: string | undefined = project.formats?.prices?.locale;
+    if (
+        priceLocale !== undefined &&
+        !(project.enabledLocales as readonly string[]).includes(priceLocale)
+    ) {
+        throw new Error(
+            `Project "${project.siteName}": formats.prices.locale names ${priceLocale}, which this project does not publish.`
+        );
+    }
     return project;
 }

package/src/site/api.ts

@@ -11,6 +11,7 @@ import type { HourCycle } from "../hours.ts";
 import type { TranslateFor } from "../i18n/translate.ts";
 import type { LlmsSection } from "../llms.ts";
 import type { ThemeColor } from "../meta/index.ts";
+import type { PriceDecimals } from "../price-format.ts";
 import type {
     RedirectRule,
     ResolvedRedirect,
@@ -229,6 +230,19 @@ export interface Site<
      */
     clockFor(locale: L): HourCycle;
 
+    /**
+     * How a locale's pages write prices, as the project's `formats.prices`
+     * states it: hand both to `formatPrice`. The locale is the page's own,
+     * unless the project names one for every page.
+     *
+     * Throws for a project that declares no price format: one that prints
+     * prices has to say how.
+     */
+    priceFormatFor(locale: L): {
+        readonly decimals: PriceDecimals;
+        readonly locale: L;
+    };
+
     /** Absolute path of a route in one locale, e.g. `/el/sxetika-me-emas`. */
     pathFor(id: RouteId, locale: L, options?: LinkOptions): UrlPath;
     /** The same, prefixed with the site origin — for canonicals and sitemaps. */

package/src/site/create.ts

@@ -24,6 +24,7 @@ import {
     buildNotFoundMeta,
     resolveShareImage,
 } from "../meta/index.ts";
+import type { PriceDecimals } from "../price-format.ts";
 import type { AddedCatalog, ProjectInput, ProjectRouteId } from "../project.ts";
 import {
     buildRedirects,
@@ -194,17 +195,35 @@ export function createSite<
     const resolved = mergeRoutes<L, Routes>(routes, project.overrideRoutes);
 
     function clockFor(locale: L): HourCycle {
-        const cycle = project.clock?.[locale];
+        const clock = project.formats?.clock;
+        const cycle = clock?.[locale];
         if (cycle === undefined) {
             throw new Error(
-                project.clock === undefined
-                    ? `Project "${project.siteName}" declares no clock, so it cannot print a time. Add \`clock\`, with an hour cycle for each locale it publishes.`
-                    : `Project "${project.siteName}": clock has no ${locale}.`
+                clock === undefined
+                    ? `Project "${project.siteName}" declares no clock, so it cannot print a time. Add \`formats.clock\`, with an hour cycle for each locale it publishes.`
+                    : `Project "${project.siteName}": formats.clock has no ${locale}.`
             );
         }
         return cycle;
     }
 
+    function priceFormatFor(locale: L): {
+        readonly decimals: PriceDecimals;
+        readonly locale: L;
+    } {
+        const prices = project.formats?.prices;
+        if (prices === undefined) {
+            throw new Error(
+                `Project "${project.siteName}" declares no price format, so it cannot print a price. Add \`formats.prices\`, with its decimals.`
+            );
+        }
+        // Found among the published locales, which the project's checks hold
+        // it to, so it is typed as one of them; else the page's own.
+        const written =
+            locales.find((each) => each === prices.locale) ?? locale;
+        return { decimals: prices.decimals, locale: written };
+    }
+
     function pathFor(id: RouteId, locale: L, options?: LinkOptions): UrlPath {
         const route = resolved[id];
         if (route === undefined) {
@@ -881,6 +900,7 @@ export function createSite<
             }),
 
         clockFor,
+        priceFormatFor,
         pathFor,
         urlFor,
         fileUrl,