feat: read zoom from optional ?z= on clear-coordinate links

onGe0Decode now sources zoom as: ?z= query param -> legacy /lat,lon,zoom path segment -> default 14. ?z= is optional, so existing links (path-zoom or none) keep working. Widens normalizeZoom's cap 19->20 to match the app's kMaxZoom (organicmaps libs/ge0/geo_url_parser.cpp) so a valid share never silently falls back to 14.

Name parsing, XSS escaping, and the ge0 fallback are unchanged; path+query (incl. ?z=) still flows into the om:/ deep link, so the app receives the zoom too. Adds a cross-reference to the app's synced clear-coordinate parser. Extends the jest suite: ?z= precedence/optional/name-coexistence/out-of-range, and normalizeZoom 1..20.

Author: biodranik

src/ge0.ts

@@ -43,11 +43,13 @@ export function normalizeNameAndTitle(name: string | undefined): [string, string
   return [name, title];
 }
 
-export function normalizeZoom(zoom: string): number {
+export function normalizeZoom(zoom: string | undefined): number {
   const DEFAULT_ZOOM = 14;
-  const z = parseInt(zoom);
-  if (isNaN(z)) return DEFAULT_ZOOM;
-  if (z < 1 || z > 19) return DEFAULT_ZOOM;
+  // Upper bound mirrors the app's kMaxZoom (organicmaps libs/ge0/geo_url_parser.cpp, GeoURLInfo::SetZoom).
+  const MAX_ZOOM = 20;
+  if (!zoom || !/^\d+$/.test(zoom)) return DEFAULT_ZOOM;
+  const z = Number(zoom);
+  if (z < 1 || z > MAX_ZOOM) return DEFAULT_ZOOM;
   return z;
 }
 
@@ -104,6 +106,9 @@ function renderTemplate(template: string, llz: LatLonZoom, name: string, title:
   return new Response(template, { headers: { 'content-type': 'text/html' } });
 }
 
+// Clear decimal coordinates: /lat,lon[,zoom][/name]. An optional ?z=<zoom> query param takes
+// precedence over the path zoom (see onGe0Decode). Kept in sync with the app's clear-coordinate
+// parser (organicmaps libs/ge0/geo_url_parser.cpp) — same grammar, same ?z= precedence and zoom cap.
 // Coordinates and zoom are validated separately.
 export const CLEAR_COORDINATES_REGEX =
   /(?<lat>-?\d+\.\d+)[^.](?<lon>-?\d+\.\d+)(?:[^.](?<zoom>\d{1,2}))?(?:[^\d.](?<name>.+))?/;
@@ -115,7 +120,9 @@ export async function onGe0Decode(template: string, url: string): Promise<Respon
 
   const m = pathname.match(CLEAR_COORDINATES_REGEX);
   if (m && m.groups) {
-    const llz = { lat: Number(m.groups.lat), lon: Number(m.groups.lon), zoom: normalizeZoom(m.groups.zoom) };
+    // Zoom precedence: ?z= query param, then a legacy /lat,lon,zoom path segment, then the default.
+    const zoom = normalizeZoom(new URLSearchParams(search).get('z') ?? m.groups.zoom);
+    const llz = { lat: Number(m.groups.lat), lon: Number(m.groups.lon), zoom };
     if (llz.lat <= -90.0 || llz.lat >= 90.0 || llz.lon <= -180.0 || llz.lon >= 180.0)
       throw new Error(`Invalid coordinates ${m.groups.lat} and ${m.groups.lon}`);
 

test/api.test.ts

@@ -22,17 +22,21 @@ describe('decodeLatLonZoom — ge0 binary short links', () => {
 });
 
 describe('normalizeZoom', () => {
-  test('keeps zoom levels within 1..19', () => {
+  test('keeps zoom levels within 1..20 (matches the app kMaxZoom)', () => {
     expect(normalizeZoom('1')).toBe(1);
     expect(normalizeZoom('15')).toBe(15);
     expect(normalizeZoom('19')).toBe(19);
+    expect(normalizeZoom('20')).toBe(20);
   });
 
   test('falls back to the default zoom (14) for missing or out-of-range values', () => {
     expect(normalizeZoom('')).toBe(14);
     expect(normalizeZoom('0')).toBe(14);
+    expect(normalizeZoom('21')).toBe(14);
     expect(normalizeZoom('99')).toBe(14);
     expect(normalizeZoom('abc')).toBe(14);
+    expect(normalizeZoom('16abc')).toBe(14);
+    expect(normalizeZoom('1.5')).toBe(14);
   });
 });
 
@@ -129,4 +133,34 @@ describe('onGe0Decode — end to end', () => {
   test('rejects out-of-range clear-text coordinates', async () => {
     await expect(onGe0Decode(TEMPLATE, 'https://omaps.app/91.0,0.0')).rejects.toThrow(/Invalid coordinates/);
   });
+
+  test('reads zoom from the ?z= query param', async () => {
+    const html = await (await onGe0Decode(TEMPLATE, 'https://omaps.app/53.9,27.56?z=16')).text();
+    expect(html).toContain('<coords>53.9,27.56@16</coords>');
+  });
+
+  test('?z= takes precedence over a legacy path zoom', async () => {
+    const html = await (await onGe0Decode(TEMPLATE, 'https://omaps.app/53.9,27.56,15?z=16')).text();
+    expect(html).toContain('<coords>53.9,27.56@16</coords>');
+  });
+
+  test('?z= is optional — falls back to the path zoom, then the default', async () => {
+    const path = await (await onGe0Decode(TEMPLATE, 'https://omaps.app/53.9,27.56,15')).text();
+    expect(path).toContain('<coords>53.9,27.56@15</coords>');
+    const bare = await (await onGe0Decode(TEMPLATE, 'https://omaps.app/53.9,27.56')).text();
+    expect(bare).toContain('<coords>53.9,27.56@14</coords>');
+  });
+
+  test('?z= coexists with a pin name: /lat,lon/Name?z=', async () => {
+    const html = await (await onGe0Decode(TEMPLATE, 'https://omaps.app/53.9,27.56/Minsk?z=12')).text();
+    expect(html).toContain('<coords>53.9,27.56@12</coords>');
+    expect(html).toContain('<name>Minsk</name>');
+  });
+
+  test('out-of-range ?z= falls back to the default zoom', async () => {
+    for (const z of ['0', '99', 'abc', '16abc', '1.5']) {
+      const html = await (await onGe0Decode(TEMPLATE, `https://omaps.app/53.9,27.56?z=${z}`)).text();
+      expect(html).toContain('<coords>53.9,27.56@14</coords>');
+    }
+  });
 });