Hong Kong Tour

01Summary

Hong Kong Tour is a guide to 143 places in Hong Kong — Hong Kong Island, Kowloon and the New Territories — split into 27 neighbourhoods. Every entry carries a real photograph of the place, a rating, a description, practical tips, a location and (where available) a map link. Search and fifteen category filters sit on top.

The interesting part is not the content, it is the delivery. One Python core — data, launcher, HTML interface — is packaged as five installable archives (macOS .dmg, Windows .exe, Linux .deb, portable .zip, Android .apk) plus an iOS/iPadOS Xcode project and a server-less browser build. The same code renders all of them; only the shell around it differs.

Five separate bugs came out of that packaging, and every one of them produced a file that looked plausible and was actually broken. They are documented below with root causes, because they are the reusable part of this project.

02By the numbers

Measured from the shipped build (data.json and dist/), not from memory.

Every desktop archive is roughly 300 MB while the whole dataset is 117 KB. That ratio is the honest headline of the project: the app is tiny, the runtime it needs is not. Bundling CPython plus pywebview plus a WebKit/WebView shell accounts for essentially all of it.

03The data model

One nested dictionary: region → area → spots. Regions carry their own name, Chinese name, blurb, hero image and accent colour; areas group spots into walkable neighbourhoods.

ATTRACTIONS = {
  "hong_kong_island": {
    "name": "香港島 Hong Kong Island", "name_cn": "香港島",
    "description": "...", "image": "...", "color": "#1f4bd8",
    "central": {"name": "中環 Central", "spots": [ {...}, ... ]},
  }, ...
}

# each spot
{"name": "中環 Central", "name_cn": "中環", "category": "neighbourhood",
 "rating": 4.6, "description": "...", "tips": "...",
 "location": "22.2819,114.1582", "google_maps": "...",
 "image": "images/929d3b56ae67c1a2.jpg"}

Why the Chinese is inside name

The spot names embed their Chinese form ("中環 Central") while name_cn holds the Chinese alone. The interface renders both, which originally printed 中環 Central 中環 on every card — a visible bug. The fix is a shared guard rather than a second field:

function cnSuffix(name, cn) {
  return (cn && !name.includes(cn)) ? cn : '';   // '' when name already carries it
}

Used for both the area header and the spot card. This is the kind of bug that only shows up in a build where CJK actually renders, which is why the automated test now asserts the subtitle never repeats the title.

Category spread

Slugs are singular (beach, not beaches), and the human labels come from a single CAT_LABELS map that feeds both the filter chips and the tags on each card — so a chip can never say "Arts & Culture" while its card says arts_culture.

04One core, seven targets

The launcher starts a threaded HTTP server on port 8570 and points a native webview at it. Everything platform-specific lives in the shell around that, never in the app.

The Android and iOS builds never touch Python: they ship the HTML, CSS, JS and images, and the data arrives through the same JSON the server would have served. That keeps the APK at 2.3 MB while the desktop builds carry a whole interpreter.

05The five packaging traps

Each of these produced an artifact that passed a naive check. Each is a macOS-toolchain or hosting-limit problem, not an app problem.

06The browser build

The desktop app talks to a local server (/api/region, /api/search, /static/images/…). On a static host there is no server, so build/build_web.py removes it rather than emulating it:

• freezes the /api/region response to data.json (111,088 B);
• downscales and re-encodes photos with sips -Z 1200 -s formatOptions 75 — 300 MB of source images become 28 MB of shipped ones;
• injects a search shim that indexes the frozen data client-side;
• emits a real favicon so the page does not request a missing one.

07What is actually proven

Claims here are backed by the check that produced them, not by "it deployed".

Two of those checks exist specifically because a green-looking result lied earlier: a page-level request listener cannot see a window.open download (it reports "no request" for a working button), and a full download is the only thing that detects a streaming proxy that truncates while returning correct headers.

08Known gaps

09Where it lives

All five installers are on the portfolio card's download buttons, served same-origin and resumable. Source lives at /Applications/HongKongTour/.

10Reproducing it

# run the desktop app
cd /Applications/HongKongTour && python3 hongkong_tour.py      # port 8570

# rebuild the four desktop packs + Android
cd /tmp && env -u PYTHONPATH /bin/bash \
  /Applications/HongKongTour/build/build_linux_windows.sh

Use native /bin/bash: a Homebrew bash is x86_64 and drags the build into Rosetta, where xcrun and the SDK disagree. Unset PYTHONPATH when calling the scripts — a stale PIL in a venv breaks the image step otherwise.

# verify every pack
env -u PYTHONPATH python3 /Applications/HongKongTour/build/verify_all_packs.py

# rebuild the static browser build
env -u PYTHONPATH python3 /Applications/HongKongTour/build/build_web.py