Sync from IsaacHuo/maptoposter via hub-sync

AGENTS.md

@@ -54,7 +54,7 @@ uv run pytest test_logic.py -k "china_hierarchy or manual_coordinates"
 uv run python verify_data.py
 
 # Create map poster directly (CLI)
-uv run python create_map_poster.py --city "Beijing" --theme japanese_ink --output-format png
+uv run python create_map_poster.py --city "Beijing" --country "China" --theme japanese_ink --output-format png
 ```
 
 ## Code Style Guidelines

backend/main.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import os
 from dataclasses import asdict
 from pathlib import Path
+from urllib.parse import quote
 
 from fastapi import FastAPI, HTTPException, Query
 from fastapi.middleware.cors import CORSMiddleware
@@ -12,7 +13,7 @@ from fastapi.responses import Response
 from fastapi.staticfiles import StaticFiles
 
 from maptoposter import __version__
-from maptoposter.export import generate_output_filename
+from maptoposter.export import ascii_download_filename, generate_output_filename
 from maptoposter.geocoding import GeocodingError
 from maptoposter.layouts import LAYOUTS
 from maptoposter.map_data import MapDataError
@@ -82,6 +83,20 @@ def preview(request: PreviewRequest) -> Response:
         raise HTTPException(status_code=404 if isinstance(exc, MapDataError) else 400, detail=str(exc)) from exc
 
 
+def content_disposition(filename: str) -> str:
+    """Build an RFC 6266 Content-Disposition value that is Latin-1 safe.
+
+    An ASCII ``filename=`` fallback is always sent; when the readable name
+    contains non-ASCII characters, an RFC 5987 ``filename*=UTF-8''...`` with
+    percent-encoding is appended so clients keep the original name.
+    """
+    ascii_filename = ascii_download_filename(filename)
+    disposition = f'attachment; filename="{ascii_filename}"'
+    if ascii_filename != filename:
+        disposition += f"; filename*=UTF-8''{quote(filename, safe='')}"
+    return disposition
+
+
 @app.post("/api/v1/posters/export")
 def export(request: ExportRequest) -> Response:
     try:
@@ -104,7 +119,7 @@ def export(request: ExportRequest) -> Response:
         return Response(
             content,
             media_type={"png": "image/png", "svg": "image/svg+xml", "pdf": "application/pdf"}[request.format],
-            headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+            headers={"Content-Disposition": content_disposition(filename)},
         )
     except (ValueError, MapDataError) as exc:
         raise HTTPException(status_code=404 if isinstance(exc, MapDataError) else 400, detail=str(exc)) from exc

create_map_poster.py

@@ -133,8 +133,8 @@ def list_themes():
         print()
 
 
-def main():
-    """Run the command-line poster generator."""
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser for the legacy command-line entry point."""
     parser = argparse.ArgumentParser(
         description="Generate beautiful map posters for any city",
         formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -186,11 +186,19 @@ Examples:
     parser.add_argument(
         "--format",
         "-f",
+        "--output-format",
+        dest="format",
         default="png",
         choices=["png", "svg", "pdf"],
         help="Output format for the poster (default: png)",
     )
 
+    return parser
+
+
+def main():
+    """Run the command-line poster generator."""
+    parser = build_parser()
     args = parser.parse_args()
 
     if len(os.sys.argv) == 1:

frontend/src/api.test.ts

@@ -1,6 +1,19 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { PosterRequest } from './types'
-import { prepareMap } from './api'
+import { exportPoster, prepareMap, searchPlaces } from './api'
+
+function jsonResponse(payload: unknown): Response {
+  return { ok: true, json: async () => payload } as unknown as Response
+}
+
+function exportResponse(disposition: string): Response {
+  return {
+    ok: true,
+    status: 200,
+    headers: { get: (name: string) => (name.toLowerCase() === 'content-disposition' ? disposition : null) },
+    blob: async () => new Blob(['poster']),
+  } as unknown as Response
+}
 
 describe('API network errors', () => {
   afterEach(() => vi.unstubAllGlobals())
@@ -13,3 +26,61 @@ describe('API network errors', () => {
     )
   })
 })
+
+describe('place search language', () => {
+  afterEach(() => vi.unstubAllGlobals())
+
+  it.each(['zh', 'zh-CN', 'zh-Hans'])('requests lang=cn for the %s locale', async (language) => {
+    vi.stubGlobal('navigator', { language })
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse([]))
+    vi.stubGlobal('fetch', fetchMock)
+
+    await searchPlaces('Tokyo')
+
+    const url = String(fetchMock.mock.calls[0][0])
+    expect(url).toContain('lang=cn')
+    expect(url).not.toContain('lang=zh')
+  })
+
+  it('requests lang=en for non-Chinese locales', async () => {
+    vi.stubGlobal('navigator', { language: 'en-US' })
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse([]))
+    vi.stubGlobal('fetch', fetchMock)
+
+    await searchPlaces('Tokyo')
+
+    expect(String(fetchMock.mock.calls[0][0])).toContain('lang=en')
+  })
+})
+
+describe('export download filename', () => {
+  afterEach(() => vi.unstubAllGlobals())
+
+  it('prefers the RFC 5987 filename* for Chinese names', async () => {
+    const disposition =
+      'attachment; filename="japanese-ink-20261017.png"; ' +
+      "filename*=UTF-8''%E5%8C%97%E4%BA%AC%E5%B8%82-japanese-ink-20261017.png"
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(exportResponse(disposition)))
+
+    const { filename } = await exportPoster('a'.repeat(64), {} as PosterRequest, 'png', 300)
+
+    expect(filename).toBe('北京市-japanese-ink-20261017.png')
+  })
+
+  it('falls back to the ASCII filename when filename* is absent', async () => {
+    const disposition = 'attachment; filename="beijing-japanese-ink-20261017.png"'
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(exportResponse(disposition)))
+
+    const { filename } = await exportPoster('a'.repeat(64), {} as PosterRequest, 'png', 300)
+
+    expect(filename).toBe('beijing-japanese-ink-20261017.png')
+  })
+
+  it('uses the format-based default when the header is missing', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(exportResponse('')))
+
+    const { filename } = await exportPoster('a'.repeat(64), {} as PosterRequest, 'pdf', 300)
+
+    expect(filename).toBe('maptoposter.pdf')
+  })
+})

frontend/src/api.ts

@@ -25,12 +25,32 @@ async function expectJson<T>(response: Response): Promise<T> {
   return response.json() as Promise<T>
 }
 
+function decodeRfc5987(value: string): string | null {
+  const match = /^(?:UTF-8|utf-8)''(.+)$/.exec(value.trim().replace(/^"|"$/g, ''))
+  if (!match) return null
+  try {
+    return decodeURIComponent(match[1])
+  } catch {
+    return null
+  }
+}
+
+function parseDownloadFilename(disposition: string, fallback: string): string {
+  const extended = /filename\*\s*=\s*([^;]+)/i.exec(disposition)
+  if (extended) {
+    const decoded = decodeRfc5987(extended[1])
+    if (decoded) return decoded
+  }
+  const basic = /filename\s*=\s*"?([^";]+)"?/i.exec(disposition)
+  return basic?.[1] ?? fallback
+}
+
 export async function getStyles(signal?: AbortSignal): Promise<StylePreset[]> {
   return expectJson(await request(`${API_ROOT}/styles`, { signal }, 'Could not reach the MapToPoster server. Please retry.'))
 }
 
 export async function searchPlaces(query: string, signal?: AbortSignal): Promise<LocationResult[]> {
-  const params = new URLSearchParams({ q: query, lang: navigator.language.startsWith('zh') ? 'zh' : 'en' })
+  const params = new URLSearchParams({ q: query, lang: navigator.language.startsWith('zh') ? 'cn' : 'en' })
   return expectJson(await request(`${API_ROOT}/locations/search?${params}`, { signal }, 'Place search was interrupted. Please retry.'))
 }
 
@@ -63,6 +83,6 @@ export async function exportPoster(mapDataId: string, poster: PosterRequest, for
   }, `The ${format.toUpperCase()} export connection was interrupted. Please retry.`)
   if (!response.ok) throw new Error(await readError(response))
   const disposition = response.headers.get('Content-Disposition') ?? ''
-  const filename = disposition.match(/filename="?([^";]+)"?/i)?.[1] ?? `maptoposter.${format}`
+  const filename = parseDownloadFilename(disposition, `maptoposter.${format}`)
   return { blob: await response.blob(), filename }
 }

src/maptoposter/cli.py

@@ -29,7 +29,14 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--country", "-C", default="")
     parser.add_argument("--theme", "-t", default="feature_based", choices=list_themes())
     parser.add_argument("--distance", "-d", type=float, default=10_000)
-    parser.add_argument("--format", "-f", choices=[item.value for item in OutputFormat], default="png")
+    parser.add_argument(
+        "--format",
+        "-f",
+        "--output-format",
+        dest="format",
+        choices=[item.value for item in OutputFormat],
+        default="png",
+    )
     parser.add_argument("--layout", choices=[item.value for item in LayoutPreset], default="classic")
     parser.add_argument("--list-themes", action="store_true")
     parser.add_argument("--output", type=Path)

src/maptoposter/export.py

@@ -7,7 +7,17 @@ from pathlib import Path
 
 from .models import OutputFormat
 from .paths import POSTERS_DIR
-from .typography import safe_slug
+from .typography import safe_ascii_slug, safe_slug
+
+
+def ascii_download_filename(filename: str, fallback: str = "map-poster") -> str:
+    """Return an ASCII-only filename that preserves the original extension.
+
+    HTTP header values must be Latin-1 encodable; non-ASCII poster names are
+    reduced to their ASCII parts for the ``filename=`` fallback.
+    """
+    path = Path(filename)
+    return f"{safe_ascii_slug(path.stem, fallback=fallback)}{path.suffix}"
 
 
 def generate_output_filename(

src/maptoposter/geocoding.py

@@ -18,6 +18,17 @@ from .models import Coordinate, Location
 
 COORDINATE_QUERY = re.compile(r"^\s*([+-]?(?:\d+(?:\.\d*)?|\.\d+))\s*[,/ ]\s*([+-]?(?:\d+(?:\.\d*)?|\.\d+))\s*$")
 
+CHINESE_LANGUAGE_CODES = frozenset({"cn", "zh", "zh-cn"})
+
+
+def nominatim_language(language: str) -> str:
+    """Map a UI language code to the language sent to Nominatim.
+
+    The product documents ``en`` and ``cn``; ``zh``/``zh-CN`` are accepted as
+    aliases for Chinese so clients that already send them still localize.
+    """
+    return "zh-CN" if language.strip().lower() in CHINESE_LANGUAGE_CODES else "en"
+
 
 class GeocodingError(RuntimeError):
     """Raised when a place search cannot be completed."""
@@ -65,7 +76,7 @@ class NominatimProvider:
                 exactly_one=False,
                 limit=limit,
                 addressdetails=True,
-                language="zh-CN" if language == "cn" else "en",
+                language=nominatim_language(language),
             )
         except Exception as exc:
             raise GeocodingError(f"Location service is unavailable: {exc}") from exc

src/maptoposter/typography.py

@@ -116,6 +116,19 @@ def safe_slug(value: str, fallback: str = "map-poster") -> str:
     return value[:80] or fallback
 
 
+def safe_ascii_slug(value: str, fallback: str = "map-poster") -> str:
+    """Create an ASCII-only filename slug by dropping non-ASCII characters.
+
+    Used to build the Latin-1-safe ``filename=`` fallback of an HTTP
+    ``Content-Disposition`` header, while ``safe_slug`` keeps the readable
+    Unicode form transported through RFC 5987 ``filename*``.
+    """
+    value = value.replace("_", "-")
+    value = re.sub(r"[^A-Za-z0-9]+", "-", value.strip().lower())
+    value = re.sub(r"-+", "-", value).strip("-_")
+    return value[:80] or fallback
+
+
 def fitted_font_size(text: str, requested: float, max_units: float, minimum: float = 18) -> float:
     """Return a deterministic first-pass title size for a bounded layout region."""
     if not text:

tests/test_api.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from pathlib import Path
+from urllib.parse import unquote
 
 from fastapi.testclient import TestClient
 
@@ -54,6 +55,55 @@ def test_prepare_preview_and_export_contract(monkeypatch, tmp_path) -> None:
     assert "beijing-japanese-ink" in exported.headers["content-disposition"]
 
 
+def test_export_chinese_title_returns_valid_content_disposition(monkeypatch, tmp_path) -> None:
+    key = "c" * 64
+    monkeypatch.setattr(service, "export_poster", lambda reference, config, export: b"%PDF-test")
+
+    payload = poster_payload()
+    payload["typography"] = {**payload["typography"], "title": "北京市"}
+    exported = client.post(
+        "/api/v1/posters/export",
+        json={"map_data_id": key, "poster": payload, "format": "pdf", "dpi": 300},
+    )
+
+    assert exported.status_code == 200
+    assert exported.headers["content-type"] == "application/pdf"
+    assert exported.content
+
+    disposition = exported.headers["content-disposition"]
+    basic = disposition.split("filename=")[1].split(";")[0].strip().strip('"')
+    assert basic, "ASCII fallback filename must be present"
+    assert basic.isascii(), f"fallback filename must be ASCII: {basic!r}"
+    assert "japanese-ink" in basic
+
+    assert "filename*=UTF-8''" in disposition
+    encoded = disposition.split("filename*=UTF-8''", 1)[1]
+    decoded = unquote(encoded)
+    assert decoded.startswith("北京市-japanese-ink-")
+    assert decoded.endswith(".pdf")
+
+
+def test_export_uses_chinese_display_name_when_title_blank(monkeypatch, tmp_path) -> None:
+    key = "d" * 64
+    monkeypatch.setattr(service, "export_poster", lambda reference, config, export: b"\x89PNG\r\n")
+
+    payload = poster_payload()
+    payload["typography"] = {**payload["typography"], "title": ""}
+    payload["location"] = {"display_name": "北京市", "latitude": 39.9042, "longitude": 116.4074, "country": "China"}
+    exported = client.post(
+        "/api/v1/posters/export",
+        json={"map_data_id": key, "poster": payload, "format": "png", "dpi": 300},
+    )
+
+    assert exported.status_code == 200
+    assert exported.headers["content-type"] == "image/png"
+    assert exported.content
+
+    disposition = exported.headers["content-disposition"]
+    encoded = disposition.split("filename*=UTF-8''", 1)[1]
+    assert unquote(encoded).startswith("北京市-japanese-ink-")
+
+
 def test_prepare_keeps_selected_bbox_for_portrait_ratio(monkeypatch, tmp_path) -> None:
     key = "b" * 64
     captured = {}

tests/test_cache_and_geocoding.py

@@ -2,18 +2,28 @@ from __future__ import annotations
 
 from dataclasses import replace
 
+import pytest
+
+import maptoposter.geocoding as geocoding
 from maptoposter.cache import DiskCache, map_cache_key
 from maptoposter.china import search_china
-from maptoposter.geocoding import GeocodingService, parse_coordinate_query
+from maptoposter.geocoding import (
+    GeocodingService,
+    NominatimProvider,
+    nominatim_language,
+    parse_coordinate_query,
+)
 from maptoposter.models import Coordinate, Location
 
 
 class FakeProvider:
     def __init__(self) -> None:
         self.calls = 0
+        self.languages: list[str] = []
 
     def search(self, query: str, language: str, limit: int) -> list[Location]:
         self.calls += 1
+        self.languages.append(language)
         return [Location(query, Coordinate(1.25, 2.5), "Testland", provider="fake")]
 
 
@@ -50,3 +60,46 @@ def test_external_geocoder_result_is_cached(tmp_path) -> None:
     assert service.search("Atlantis")[0].provider == "fake"
     assert service.search("Atlantis")[0].provider == "fake"
     assert provider.calls == 1
+
+
+@pytest.mark.parametrize(
+    ("language", "expected"),
+    [
+        ("en", "en"),
+        ("fr", "en"),
+        ("cn", "zh-CN"),
+        ("zh", "zh-CN"),
+        ("zh-CN", "zh-CN"),
+        ("ZH", "zh-CN"),
+    ],
+)
+def test_nominatim_language_maps_chinese_aliases(language: str, expected: str) -> None:
+    assert nominatim_language(language) == expected
+
+
+@pytest.mark.parametrize(
+    ("requested", "expected"),
+    [("cn", "zh-CN"), ("zh", "zh-CN"), ("zh-CN", "zh-CN"), ("en", "en"), ("fr", "en")],
+)
+def test_nominatim_provider_forwards_localized_language(monkeypatch, requested: str, expected: str) -> None:
+    captured: list[str] = []
+
+    class FakeGeocoder:
+        def geocode(self, query: str, **kwargs: object) -> list[object]:
+            captured.append(str(kwargs.get("language")))
+            return []
+
+    monkeypatch.setattr(geocoding, "Nominatim", lambda **_: FakeGeocoder())
+
+    NominatimProvider().search("Tokyo", requested)
+
+    assert captured == [expected]
+
+
+def test_geocoding_service_forwards_requested_language(tmp_path) -> None:
+    provider = FakeProvider()
+    service = GeocodingService(DiskCache(tmp_path), provider)
+
+    service.search("Atlantis", "zh")
+
+    assert provider.languages == ["zh"]

tests/test_cli.py

@@ -0,0 +1,71 @@
+"""Regression tests for the documented command-line usage.
+
+The README and AGENTS docs publish runnable commands. Previously the docs used
+``--output-format``, which no parser defined, so argparse rejected the command with
+``unrecognized arguments`` before any poster could be generated. These tests pin the
+documented argv, the ``--output-format`` alias and the original ``--format``/``-f`` flags.
+"""
+
+from __future__ import annotations
+
+import shlex
+from pathlib import Path
+
+from create_map_poster import build_parser as build_legacy_parser
+from maptoposter.cli import build_parser
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _documented_argv(command: str, prefix_length: int) -> list[str]:
+    """Split a documented command and drop the ``uv run ...`` prefix."""
+    argv = shlex.split(command)
+    return argv[prefix_length:]
+
+
+def test_readme_documented_command_parses() -> None:
+    """README.md's CLI example must parse verbatim and select the png format."""
+    readme = (ROOT / "README.md").read_text(encoding="utf-8-sig")
+    command = 'uv run maptoposter --city "Beijing" --theme japanese_ink --output-format png'
+    assert command in readme
+
+    args = build_parser().parse_args(_documented_argv(command, 3))
+    assert args.city == "Beijing"
+    assert args.theme == "japanese_ink"
+    assert args.format == "png"
+
+
+def test_agents_documented_legacy_command_parses() -> None:
+    """AGENTS.md's legacy example must parse verbatim, including --city/--country."""
+    agents = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
+    command = (
+        "uv run python create_map_poster.py --city \"Beijing\" --country \"China\" "
+        "--theme japanese_ink --output-format png"
+    )
+    assert command in agents
+
+    args = build_legacy_parser().parse_args(_documented_argv(command, 4))
+    assert args.city == "Beijing"
+    assert args.country == "China"
+    assert args.theme == "japanese_ink"
+    assert args.format == "png"
+
+
+def test_output_format_alias_maps_to_format_dest() -> None:
+    """The alias resolves to the same ``format`` destination for both parsers."""
+    assert build_parser().parse_args(["--city", "Paris", "--output-format", "svg"]).format == "svg"
+    legacy = build_legacy_parser().parse_args(["--city", "Paris", "-C", "France", "--output-format", "pdf"])
+    assert legacy.format == "pdf"
+
+
+def test_format_flags_remain_available() -> None:
+    """Existing --format and -f usage must keep working."""
+    assert build_parser().parse_args(["--city", "Paris", "--format", "svg"]).format == "svg"
+    assert build_parser().parse_args(["--city", "Paris", "-f", "pdf"]).format == "pdf"
+    assert build_legacy_parser().parse_args(["--city", "Paris", "-C", "France", "--format", "svg"]).format == "svg"
+
+
+def test_help_advertises_output_format_alias() -> None:
+    """``--help`` must advertise the documented alias so users can discover it."""
+    assert "--output-format" in build_parser().format_help()
+    assert "--output-format" in build_legacy_parser().format_help()

tests/test_repository_contract.py

@@ -48,7 +48,7 @@ def test_main_release_contract() -> None:
     workflow = (ROOT / ".github/workflows/publish-hugging-face.yml").read_text(encoding="utf-8")
     assert "branches: [main]" in workflow
     assert "needs: validate" in workflow
-    assert "huggingface/hub-sync@v0.1.0" in workflow
+    assert "huggingface/hub-sync@v0.3.0" in workflow
     assert "huggingface_repo_id: isaachwf/MapToPoster" in workflow
     assert "hf_token: ${{ secrets.HF_TOKEN }}" in workflow
     assert "space_sdk: docker" in workflow