@chaosity/location-client 0.5.0 → 0.6.0

package/dist/cjs/utils/roundPosition.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Round coordinate arrays in command inputs so nearby callers share a server
+ * cache entry.
+ *
+ * `BiasPosition` is a hint about where to look, so collapsing it onto a grid
+ * lets two users in the same area reuse one upstream answer. `QueryPosition`
+ * is not a hint — reverse-geocode resolves an exact point a user clicked or a
+ * device reported, and rounding it returns a neighbour's address. It is left
+ * alone (RFC-0001 §2).
+ *
+ * WHY THE DEFAULT MOVED FROM 2 dp TO 3 dp
+ *
+ * 2 dp is a ~1.1 km grid, and that is not a coarser answer — it is a wrong
+ * one. Measured against Amazon Location directly, `QueryText: "cafe"` from
+ * Sydney CBD returns a completely different set of places when the bias moves
+ * 111 m:
+ *
+ *   base      -> Crepe de Paris | Deli Ziosa | CBD Patisserie
+ *   +111 m    -> Cafe Chocolat  | Paradiso Cafe | Incanto Coffee
+ *
+ * So two users a kilometre apart both received whichever places were nearest
+ * the FIRST of them, with nothing in the response saying so. The server moved
+ * to 3 dp in api#21 — but this library rounds BEFORE sending, on both the
+ * browser and server paths, so the precision was already gone by the time the
+ * request arrived and that fix never reached anyone using the SDK. This is
+ * what makes it reach them.
+ *
+ * The cost is hit rate: cells shrink 100x in area. RFC-0001 §5 expected only
+ * "single-digit to low-double-digit percent" in mixed traffic, so there was
+ * little to protect, and a miss costs one upstream call while a wrong answer
+ * costs trust.
+ */
+/** The server's floor (api#65). A request for less is clamped up to it. */
+export declare const DEFAULT_BIAS_DECIMALS = 3;
+/**
+ * The band the server enforces (api#65). Mirrored here so the value this
+ * library rounds to is the value the server will actually key its cache by —
+ * rounding to something outside the band just means being wrong about what
+ * was sent.
+ *
+ * The floor is correctness: below 3 dp the nearest places are not the ones
+ * returned. The ceiling is cost: cells shrink 100x in area per decimal, so
+ * finer precision collapses the cache hit rate and every miss is a billable
+ * upstream call.
+ */
+export declare const MIN_BIAS_DECIMALS = 3;
+export declare const MAX_BIAS_DECIMALS = 5;
+/**
+ * Clamp a requested precision into the allowed band.
+ *
+ * Anything absent or malformed becomes the default rather than throwing: this
+ * runs on every request, and a surprising token claim must not break geocoding
+ * for an application that is otherwise working.
+ */
+export declare function clampBiasDecimals(requested?: unknown): number;
+/**
+ * Shallow-clone the input and round position arrays that benefit from caching.
+ * Returns the original object if no position fields are present.
+ *
+ * @param input      the command input
+ * @param decimals   precision for this application; defaults to the floor.
+ *                   Comes from the `biasDecimals` JWT claim where the token
+ *                   carries one (api#65) — an application entitled to finer
+ *                   bias gets it without the caller configuring anything.
+ */
+export declare function roundPositionFields<T extends object>(input: T, decimals?: number): T;

package/dist/cjs/utils/roundPosition.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Round coordinate arrays in command inputs so nearby callers share a server
+ * cache entry.
+ *
+ * `BiasPosition` is a hint about where to look, so collapsing it onto a grid
+ * lets two users in the same area reuse one upstream answer. `QueryPosition`
+ * is not a hint — reverse-geocode resolves an exact point a user clicked or a
+ * device reported, and rounding it returns a neighbour's address. It is left
+ * alone (RFC-0001 §2).
+ *
+ * WHY THE DEFAULT MOVED FROM 2 dp TO 3 dp
+ *
+ * 2 dp is a ~1.1 km grid, and that is not a coarser answer — it is a wrong
+ * one. Measured against Amazon Location directly, `QueryText: "cafe"` from
+ * Sydney CBD returns a completely different set of places when the bias moves
+ * 111 m:
+ *
+ *   base      -> Crepe de Paris | Deli Ziosa | CBD Patisserie
+ *   +111 m    -> Cafe Chocolat  | Paradiso Cafe | Incanto Coffee
+ *
+ * So two users a kilometre apart both received whichever places were nearest
+ * the FIRST of them, with nothing in the response saying so. The server moved
+ * to 3 dp in api#21 — but this library rounds BEFORE sending, on both the
+ * browser and server paths, so the precision was already gone by the time the
+ * request arrived and that fix never reached anyone using the SDK. This is
+ * what makes it reach them.
+ *
+ * The cost is hit rate: cells shrink 100x in area. RFC-0001 §5 expected only
+ * "single-digit to low-double-digit percent" in mixed traffic, so there was
+ * little to protect, and a miss costs one upstream call while a wrong answer
+ * costs trust.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BIAS_DECIMALS = exports.MIN_BIAS_DECIMALS = exports.DEFAULT_BIAS_DECIMALS = void 0;
+exports.clampBiasDecimals = clampBiasDecimals;
+exports.roundPositionFields = roundPositionFields;
+/** The server's floor (api#65). A request for less is clamped up to it. */
+exports.DEFAULT_BIAS_DECIMALS = 3;
+/**
+ * The band the server enforces (api#65). Mirrored here so the value this
+ * library rounds to is the value the server will actually key its cache by —
+ * rounding to something outside the band just means being wrong about what
+ * was sent.
+ *
+ * The floor is correctness: below 3 dp the nearest places are not the ones
+ * returned. The ceiling is cost: cells shrink 100x in area per decimal, so
+ * finer precision collapses the cache hit rate and every miss is a billable
+ * upstream call.
+ */
+exports.MIN_BIAS_DECIMALS = 3;
+exports.MAX_BIAS_DECIMALS = 5;
+/**
+ * Clamp a requested precision into the allowed band.
+ *
+ * Anything absent or malformed becomes the default rather than throwing: this
+ * runs on every request, and a surprising token claim must not break geocoding
+ * for an application that is otherwise working.
+ */
+function clampBiasDecimals(requested) {
+    const n = Number(requested);
+    if ((typeof requested !== 'number' &&
+        !(typeof requested === 'string' && requested.trim() !== '')) ||
+        !Number.isFinite(n)) {
+        return exports.DEFAULT_BIAS_DECIMALS;
+    }
+    const floored = Math.floor(n);
+    if (floored < exports.MIN_BIAS_DECIMALS)
+        return exports.MIN_BIAS_DECIMALS;
+    if (floored > exports.MAX_BIAS_DECIMALS)
+        return exports.MAX_BIAS_DECIMALS;
+    return floored;
+}
+/** Known position field names and whether they should be rounded */
+const POSITION_FIELDS = {
+    BiasPosition: true, // geocode, autocomplete, search — round for cache
+    QueryPosition: false, // reverse geocode — keep full precision
+};
+function roundCoord(value, decimals) {
+    const factor = 10 ** decimals;
+    return Math.round(value * factor) / factor;
+}
+/**
+ * Shallow-clone the input and round position arrays that benefit from caching.
+ * Returns the original object if no position fields are present.
+ *
+ * @param input      the command input
+ * @param decimals   precision for this application; defaults to the floor.
+ *                   Comes from the `biasDecimals` JWT claim where the token
+ *                   carries one (api#65) — an application entitled to finer
+ *                   bias gets it without the caller configuring anything.
+ */
+function roundPositionFields(input, decimals = exports.DEFAULT_BIAS_DECIMALS) {
+    if (!input || typeof input !== 'object')
+        return input;
+    const dp = clampBiasDecimals(decimals);
+    let cloned = null;
+    for (const [field, shouldRound] of Object.entries(POSITION_FIELDS)) {
+        if (!shouldRound)
+            continue;
+        const value = input[field];
+        if (!Array.isArray(value))
+            continue;
+        if (!cloned)
+            cloned = { ...input };
+        cloned[field] = value.map((v) => typeof v === 'number' && Number.isFinite(v) ? roundCoord(v, dp) : v);
+    }
+    return cloned ?? input;
+}

package/dist/cjs/utils/tokenClaims.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Read advisory application config out of the access token (api#65).
+ *
+ * The API puts an application's own settings — `biasDecimals`, `countries` —
+ * into the JWT alongside `allowedDomain` and `allowedResources`, so this
+ * library can stop hard-coding values it has no other way of knowing.
+ *
+ * DELIBERATELY UNVERIFIED, and that is safe. This library has no signing key
+ * and does not need one: every claim here is re-read from the application row
+ * by the API on each request, and the API's answer is the one that counts. A
+ * forged token would fail at the authorizer long before any of this mattered.
+ * What is read here only decides how the request is SHAPED — a hint, never a
+ * permission.
+ *
+ * A JWT is signed, not encrypted, so the payload is plain base64url. Nothing
+ * secret is in it; these are the caller's own settings.
+ */
+export interface AppConfigClaims {
+    /**
+     * Bias precision this application is entitled to.
+     *
+     * Safe to act on: it only changes how a coordinate is rounded before
+     * sending, and the server re-rounds to its own configured value anyway. A
+     * stale value here costs precision, never correctness.
+     */
+    biasDecimals?: number;
+    /**
+     * Countries this application may search, ISO 3166-1 alpha-2.
+     *
+     * READ THIS, DO NOT ACT ON IT. It is here to be displayed — a country
+     * selector, a settings screen, a "this application serves AU and NZ" label.
+     *
+     * Do not inject it into requests and do not reject requests with it. The
+     * token is a snapshot up to fifteen minutes old; the API reads the scope
+     * fresh from the application row on every request. Acting on a stale value
+     * makes things WORSE, in both directions:
+     *
+     *   app is now scoped to NZ, token still says AU
+     *     send nothing         -> API injects [NZ]  -> 200
+     *     inject stale [AU]    -> outside scope     -> 400
+     *
+     * So a request that would have succeeded fails instead. Rejecting locally
+     * has the mirror-image bug: refusing something the API would now allow.
+     * Sending nothing and letting the API scope the request is always correct.
+     */
+    countries?: string[];
+}
+/**
+ * Decode a JWT payload without verifying it.
+ *
+ * Returns `{}` for anything unparseable. This runs on every request, so a
+ * surprising token must degrade to "no claims" rather than break geocoding
+ * for an application that is otherwise working.
+ */
+export declare function readAppConfigClaims(token?: string | null): AppConfigClaims;

package/dist/cjs/utils/tokenClaims.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Read advisory application config out of the access token (api#65).
+ *
+ * The API puts an application's own settings — `biasDecimals`, `countries` —
+ * into the JWT alongside `allowedDomain` and `allowedResources`, so this
+ * library can stop hard-coding values it has no other way of knowing.
+ *
+ * DELIBERATELY UNVERIFIED, and that is safe. This library has no signing key
+ * and does not need one: every claim here is re-read from the application row
+ * by the API on each request, and the API's answer is the one that counts. A
+ * forged token would fail at the authorizer long before any of this mattered.
+ * What is read here only decides how the request is SHAPED — a hint, never a
+ * permission.
+ *
+ * A JWT is signed, not encrypted, so the payload is plain base64url. Nothing
+ * secret is in it; these are the caller's own settings.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAppConfigClaims = readAppConfigClaims;
+/**
+ * Decode a JWT payload without verifying it.
+ *
+ * Returns `{}` for anything unparseable. This runs on every request, so a
+ * surprising token must degrade to "no claims" rather than break geocoding
+ * for an application that is otherwise working.
+ */
+function readAppConfigClaims(token) {
+    if (typeof token !== 'string')
+        return {};
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return {};
+    try {
+        // base64url -> base64: JWT omits padding and swaps two characters.
+        const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const padded = b64.padEnd(b64.length + ((4 - (b64.length % 4)) % 4), '=');
+        // `atob` exists in browsers and in Node 16+, so one path serves both.
+        const json = decodeURIComponent(Array.from(atob(padded), (c) => `%${c.charCodeAt(0).toString(16).padStart(2, '0')}`).join(''));
+        const payload = JSON.parse(json);
+        const claims = {};
+        if (typeof payload.biasDecimals === 'number') {
+            claims.biasDecimals = payload.biasDecimals;
+        }
+        else if (typeof payload.biasDecimals === 'string' &&
+            payload.biasDecimals.trim() !== '') {
+            const n = Number(payload.biasDecimals);
+            if (Number.isFinite(n))
+                claims.biasDecimals = n;
+        }
+        if (Array.isArray(payload.countries)) {
+            const list = payload.countries.filter((c) => typeof c === 'string');
+            if (list.length)
+                claims.countries = list;
+        }
+        return claims;
+    }
+    catch {
+        return {};
+    }
+}

package/dist/client/GeoPlacesClient.d.ts

@@ -1,6 +1,6 @@
-import type { RequestOptions } from '../transport/http';
-import type { ClientConfig } from '../types';
-import type { AppConfigClaims } from '../utils/tokenClaims';
+import type { RequestOptions } from '../transport/http.js';
+import type { ClientConfig } from '../types/index.js';
+import type { AppConfigClaims } from '../utils/tokenClaims.js';
 export type SendOptions = RequestOptions;
 /**
  * GeoPlacesClient — AWS Location Service compatible client with custom auth.

package/dist/client/GeoPlacesClient.js

@@ -1,8 +1,8 @@
 import debug from 'debug';
-import { resolveEndpoint } from '../transport/endpoints';
-import { requestJson } from '../transport/http';
-import { roundPositionFields } from '../utils/roundPosition';
-import { readAppConfigClaims } from '../utils/tokenClaims';
+import { resolveEndpoint } from '../transport/endpoints.js';
+import { requestJson } from '../transport/http.js';
+import { roundPositionFields } from '../utils/roundPosition.js';
+import { readAppConfigClaims } from '../utils/tokenClaims.js';
 const log = debug('location-client:api');
 /**
  * GeoPlacesClient — AWS Location Service compatible client with custom auth.

package/dist/index.d.ts

@@ -1,24 +1,24 @@
-export { GeoPlacesClient } from './client/GeoPlacesClient';
-export type { SendOptions } from './client/GeoPlacesClient';
-export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http';
-export type { RequestOptions } from './transport/http';
-export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh';
-export { LocationServiceException } from './errors/LocationServiceException';
-export type { LocationServiceExceptionOptions } from './errors/LocationServiceException';
+export { GeoPlacesClient } from './client/GeoPlacesClient.js';
+export type { SendOptions } from './client/GeoPlacesClient.js';
+export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http.js';
+export type { RequestOptions } from './transport/http.js';
+export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh.js';
+export { LocationServiceException } from './errors/LocationServiceException.js';
+export type { LocationServiceExceptionOptions } from './errors/LocationServiceException.js';
 export * from '@aws-sdk/client-geo-places';
 export * from '@aws/amazon-location-utilities-datatypes';
-export { GeoPlaces } from './adapters/GeoPlaces';
-export type { GeoPlacesDetailOptions, GeoPlacesOptions, } from './adapters/GeoPlaces';
-export { createTransformRequest } from './maps/createTransformRequest';
-export { applyMapLanguage } from './maps/mapLanguage';
-export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/mapPoi';
-export type { PoiCategory } from './maps/mapPoi';
-export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
-export type { MapStyleOptions } from './maps/mapStyle';
-export { buildStaticMapUrl, fetchStaticMap, staticMapAccept, } from './maps/staticMap';
-export type { StaticMapFileName, StaticMapOptions } from './maps/staticMap';
-export { BUILDINGS, COLOR_SCHEMES, CONTOUR_DENSITIES, LABEL_SIZES, MAP_FEATURE_MODES, MAP_STYLES, SCALE_BAR_UNITS, SPRITE_VARIANTS, STATIC_MAP_STYLES, TERRAINS, TRAFFIC_MODES, TRAVEL_MODES, } from './maps/mapEnums';
-export type { Buildings, ColorScheme, ContourDensity, LabelSize, MapFeatureMode, MapStyle, ScaleBarUnit, SpriteVariant, StaticMapStyle, Terrain, TrafficMode, TravelMode, } from './maps/mapEnums';
-export { transformRequest } from './maps/Utils';
-export type { ClientConfig, GeoPlacesCommand, MapLike } from './types';
-export type { AppConfigClaims } from './utils/tokenClaims';
+export { GeoPlaces } from './adapters/GeoPlaces.js';
+export type { GeoPlacesDetailOptions, GeoPlacesOptions, } from './adapters/GeoPlaces.js';
+export { createTransformRequest } from './maps/createTransformRequest.js';
+export { applyMapLanguage } from './maps/mapLanguage.js';
+export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/mapPoi.js';
+export type { PoiCategory } from './maps/mapPoi.js';
+export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle.js';
+export type { MapStyleOptions } from './maps/mapStyle.js';
+export { buildStaticMapUrl, fetchStaticMap, staticMapAccept, } from './maps/staticMap.js';
+export type { StaticMapFileName, StaticMapOptions } from './maps/staticMap.js';
+export { BUILDINGS, COLOR_SCHEMES, CONTOUR_DENSITIES, LABEL_SIZES, MAP_FEATURE_MODES, MAP_STYLES, SCALE_BAR_UNITS, SPRITE_VARIANTS, STATIC_MAP_STYLES, TERRAINS, TRAFFIC_MODES, TRAVEL_MODES, } from './maps/mapEnums.js';
+export type { Buildings, ColorScheme, ContourDensity, LabelSize, MapFeatureMode, MapStyle, ScaleBarUnit, SpriteVariant, StaticMapStyle, Terrain, TrafficMode, TravelMode, } from './maps/mapEnums.js';
+export { transformRequest } from './maps/Utils.js';
+export type { ClientConfig, GeoPlacesCommand, MapLike } from './types/index.js';
+export type { AppConfigClaims } from './utils/tokenClaims.js';

package/dist/index.js

@@ -1,25 +1,25 @@
 // Client (Custom - uses our auth instead of AWS SigV4)
-export { GeoPlacesClient } from './client/GeoPlacesClient';
+export { GeoPlacesClient } from './client/GeoPlacesClient.js';
 // Transport options — cancellation, per-attempt timeout, retry policy
-export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http';
+export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http.js';
 // Token refresh policy — shared by the server provider and the React provider
-export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh';
+export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh.js';
 // Errors
-export { LocationServiceException } from './errors/LocationServiceException';
+export { LocationServiceException } from './errors/LocationServiceException.js';
 // Re-export AWS SDK commands and types
 export * from '@aws-sdk/client-geo-places';
 // Re-export AWS Location Utilities (data type conversions)
 export * from '@aws/amazon-location-utilities-datatypes';
 // Adapters (Custom - for MapLibre integration)
-export { GeoPlaces } from './adapters/GeoPlaces';
+export { GeoPlaces } from './adapters/GeoPlaces.js';
 // Maps utilities
-export { createTransformRequest } from './maps/createTransformRequest';
-export { applyMapLanguage } from './maps/mapLanguage';
-export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/mapPoi';
-export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
-export { buildStaticMapUrl, fetchStaticMap, staticMapAccept, } from './maps/staticMap';
+export { createTransformRequest } from './maps/createTransformRequest.js';
+export { applyMapLanguage } from './maps/mapLanguage.js';
+export { POI_CATEGORIES, setAllPoiVisibility, setPoiVisibility, } from './maps/mapPoi.js';
+export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle.js';
+export { buildStaticMapUrl, fetchStaticMap, staticMapAccept, } from './maps/staticMap.js';
 // Accepted values for every map parameter, as VALUES so a picker can be built
 // from them, plus the matching types. Case sensitive — see mapEnums.ts.
-export { BUILDINGS, COLOR_SCHEMES, CONTOUR_DENSITIES, LABEL_SIZES, MAP_FEATURE_MODES, MAP_STYLES, SCALE_BAR_UNITS, SPRITE_VARIANTS, STATIC_MAP_STYLES, TERRAINS, TRAFFIC_MODES, TRAVEL_MODES, } from './maps/mapEnums';
-export { transformRequest } from './maps/Utils';
+export { BUILDINGS, COLOR_SCHEMES, CONTOUR_DENSITIES, LABEL_SIZES, MAP_FEATURE_MODES, MAP_STYLES, SCALE_BAR_UNITS, SPRITE_VARIANTS, STATIC_MAP_STYLES, TERRAINS, TRAFFIC_MODES, TRAVEL_MODES, } from './maps/mapEnums.js';
+export { transformRequest } from './maps/Utils.js';
 // Server-only utilities are available via '@chaosity/location-client/server'

package/dist/maps/Utils.d.ts

@@ -1,2 +1,2 @@
-import type { ClientConfig } from '../types';
+import type { ClientConfig } from '../types/index.js';
 export declare function transformRequest(url: string, config: ClientConfig): import("maplibre-gl").RequestParameters | Promise<import("maplibre-gl").RequestParameters> | undefined;

package/dist/maps/Utils.js

@@ -1,4 +1,4 @@
-import { createTransformRequest } from './createTransformRequest';
+import { createTransformRequest } from './createTransformRequest.js';
 export function transformRequest(url, config) {
     const token = config.getToken?.() ?? config.token;
     return createTransformRequest(config.apiUrl, () => token)(url);

package/dist/maps/createTransformRequest.js

@@ -7,7 +7,7 @@
  * @returns MapLibre transformRequest function
  */
 export function createTransformRequest(apiUrl, getToken) {
-    return (url, resourceType) => {
+    return (url, _resourceType) => {
         if (url.startsWith(apiUrl)) {
             const token = getToken();
             if (!token) {

package/dist/maps/mapLanguage.d.ts

@@ -1,14 +1,38 @@
-import type { MapLike } from '../types';
+import type { MapLike } from '../types/index.js';
 /**
- * Apply a preferred display language to all symbol layers on a MapLibre map.
- *
- * AWS GeoMaps vector tiles include language-specific name properties in `name:${lang}` format
- * (e.g. `name:en`, `name:fr`, `name:ja`). This function updates the `text-field` expression
- * on every symbol layer to prefer the requested language, falling back to English then the
- * default name if the preferred language is unavailable for a feature.
+ * The `text-field` expression that prefers `language`, then English, then the
+ * feature's default name.
  *
  * Based on the approach documented at:
  * https://docs.aws.amazon.com/location/latest/developerguide/how-to-set-preferred-language-map.html
+ */
+export declare function languageExpression(language: string): unknown[];
+/**
+ * Whether a `text-field` reads a name property — the only kind of label a
+ * language rewrite makes sense for (#28).
+ *
+ * The AWS Standard style has 62 symbol layers with a text-field and 30 of
+ * them do NOT label by name: `building_label_number` reads
+ * `addr_housenumber`, and the 29 `shield_*` layers read `shield_text` or
+ * `ref`. Replacing those with a `name:<lang>` coalesce points them at a
+ * property their features do not carry, and the house numbers and road
+ * shields disappear — for `en` too. Measured against the live sandbox on
+ * 2026-08-29; the testbed showed it as "one map has house numbers, the
+ * others don't".
+ *
+ * Serialising the expression is the simplest exact test: `name`, `name:en`,
+ * `name_en` and a literal `{name}` template all contain it, and none of the
+ * non-name properties do.
+ */
+export declare function labelsByName(textField: unknown): boolean;
+/**
+ * Apply a preferred display language to the name labels on a MapLibre map.
+ *
+ * AWS GeoMaps vector tiles carry `name:${lang}` properties (`name:en`,
+ * `name:fr`, `name:ja`, …). Every symbol layer whose `text-field` reads a
+ * name is rewritten to prefer the requested language, falling back to
+ * English then the default name. Layers that label by something else — house
+ * numbers, road shields — are left exactly as the style declared them.
  *
  * @param map - MapLibre Map instance (or any object matching the MapLike interface)
  * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja', 'zh', 'ar')

package/dist/maps/mapLanguage.js

@@ -1,13 +1,48 @@
 /**
- * Apply a preferred display language to all symbol layers on a MapLibre map.
- *
- * AWS GeoMaps vector tiles include language-specific name properties in `name:${lang}` format
- * (e.g. `name:en`, `name:fr`, `name:ja`). This function updates the `text-field` expression
- * on every symbol layer to prefer the requested language, falling back to English then the
- * default name if the preferred language is unavailable for a feature.
+ * The `text-field` expression that prefers `language`, then English, then the
+ * feature's default name.
  *
  * Based on the approach documented at:
  * https://docs.aws.amazon.com/location/latest/developerguide/how-to-set-preferred-language-map.html
+ */
+export function languageExpression(language) {
+    return language === 'en'
+        ? ['coalesce', ['get', 'name:en'], ['get', 'name']]
+        : [
+            'coalesce',
+            ['get', `name:${language}`],
+            ['get', 'name:en'],
+            ['get', 'name'],
+        ];
+}
+/**
+ * Whether a `text-field` reads a name property — the only kind of label a
+ * language rewrite makes sense for (#28).
+ *
+ * The AWS Standard style has 62 symbol layers with a text-field and 30 of
+ * them do NOT label by name: `building_label_number` reads
+ * `addr_housenumber`, and the 29 `shield_*` layers read `shield_text` or
+ * `ref`. Replacing those with a `name:<lang>` coalesce points them at a
+ * property their features do not carry, and the house numbers and road
+ * shields disappear — for `en` too. Measured against the live sandbox on
+ * 2026-08-29; the testbed showed it as "one map has house numbers, the
+ * others don't".
+ *
+ * Serialising the expression is the simplest exact test: `name`, `name:en`,
+ * `name_en` and a literal `{name}` template all contain it, and none of the
+ * non-name properties do.
+ */
+export function labelsByName(textField) {
+    return JSON.stringify(textField)?.includes('name') ?? false;
+}
+/**
+ * Apply a preferred display language to the name labels on a MapLibre map.
+ *
+ * AWS GeoMaps vector tiles carry `name:${lang}` properties (`name:en`,
+ * `name:fr`, `name:ja`, …). Every symbol layer whose `text-field` reads a
+ * name is rewritten to prefer the requested language, falling back to
+ * English then the default name. Layers that label by something else — house
+ * numbers, road shields — are left exactly as the style declared them.
  *
  * @param map - MapLibre Map instance (or any object matching the MapLike interface)
  * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja', 'zh', 'ar')
@@ -17,21 +52,16 @@
  */
 export function applyMapLanguage(map, language) {
     try {
-        const expression = language === 'en'
-            ? ['coalesce', ['get', 'name:en'], ['get', 'name']]
-            : [
-                'coalesce',
-                ['get', `name:${language}`],
-                ['get', 'name:en'],
-                ['get', 'name'],
-            ];
+        const expression = languageExpression(language);
         map.getStyle().layers.forEach((layer) => {
-            if (layer.type === 'symbol') {
-                const textField = map.getLayoutProperty(layer.id, 'text-field');
-                if (textField !== undefined && textField !== null) {
-                    map.setLayoutProperty(layer.id, 'text-field', expression);
-                }
-            }
+            if (layer.type !== 'symbol')
+                return;
+            const textField = map.getLayoutProperty(layer.id, 'text-field');
+            if (textField === undefined || textField === null)
+                return;
+            if (!labelsByName(textField))
+                return;
+            map.setLayoutProperty(layer.id, 'text-field', expression);
         });
     }
     catch {

package/dist/maps/mapStyle.d.ts

@@ -1,5 +1,5 @@
 import type { StyleSpecification } from 'maplibre-gl';
-import type { Buildings, ColorScheme, ContourDensity, MapStyle, Terrain, TrafficMode, TravelMode } from './mapEnums';
+import type { Buildings, ColorScheme, ContourDensity, MapStyle, Terrain, TrafficMode, TravelMode } from './mapEnums.js';
 /**
  * Options for building an AWS Location Service map style URL.
  * All parameters map directly to query parameters supported by the style descriptor endpoint.

package/dist/maps/mapStyle.js

@@ -1,4 +1,5 @@
-import { parseErrorResponse } from '../transport/errors';
+import { parseErrorResponse } from '../transport/errors.js';
+import { labelsByName, languageExpression } from './mapLanguage.js';
 /**
  * Build a map style descriptor URL for the Location Service API.
  *
@@ -83,24 +84,24 @@ export async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}) {
     return style;
 }
 /**
- * Apply a preferred language to all symbol layers within a style descriptor object.
+ * Apply a preferred language to the name labels within a style descriptor.
  * Mutates the style in place — call before passing to MapLibre.
+ *
+ * Only a `text-field` that reads a name property is rewritten. House numbers
+ * (`addr_housenumber`) and road shields (`shield_text`) used to be rewritten
+ * too, and vanished from every map that asked for a language (#28); the rule
+ * lives in `labelsByName` so this and `applyMapLanguage` cannot disagree.
  */
 function applyLanguageToDescriptor(style, language) {
-    const expression = language === 'en'
-        ? ['coalesce', ['get', 'name:en'], ['get', 'name']]
-        : [
-            'coalesce',
-            ['get', `name:${language}`],
-            ['get', 'name:en'],
-            ['get', 'name'],
-        ];
+    const expression = languageExpression(language);
     for (const layer of style.layers) {
-        if (layer.type === 'symbol') {
-            const layout = layer.layout;
-            if (layout?.['text-field'] !== undefined) {
-                layout['text-field'] = expression;
-            }
-        }
+        if (layer.type !== 'symbol')
+            continue;
+        const layout = layer.layout;
+        if (layout?.['text-field'] === undefined)
+            continue;
+        if (!labelsByName(layout['text-field']))
+            continue;
+        layout['text-field'] = expression;
     }
 }

package/dist/maps/staticMap.d.ts

@@ -1,4 +1,4 @@
-import type { ColorScheme, LabelSize, MapFeatureMode, ScaleBarUnit, StaticMapStyle } from './mapEnums';
+import type { ColorScheme, LabelSize, MapFeatureMode, ScaleBarUnit, StaticMapStyle } from './mapEnums.js';
 /**
  * Static maps: build the URL, send the right headers, get a Blob.
  *