Document double-click app bundles and the Windows GUI base

README and the packing guide gain a double-click app section covering the macOS .app, the Linux .AppDir/.AppImage, favicon icons, and the windows-gui base. The changelog and docs release notes record the new format under Unreleased.
2026-06-15 00:42:54 +07:00
parent 05a87960d1
commit 8b8331c435
5 changed files with 93 additions and 3 deletions
@@ -16,10 +16,26 @@ All notable changes to kage are recorded here. The format follows

 - Container-aware Chrome flags. kage detects a container from the `IN_DOCKER` environment variable or a `/.dockerenv` marker and, only there, drops the sandbox and adds `--disable-dev-shm-usage` (the default 64 MB `/dev/shm` is too small for Chrome on large pages). Outside a container the faster shared memory is left in place.
 - Asset downloads retry on a transient failure (a 403/429, a 5xx, or a network blip) with a short backoff, recovering files that bot-protection rejects on the first request of a burst. Permanent failures (404, 401, ...) are not retried.
+- `kage pack --format app` wraps the packed viewer in a double-click desktop app
+  with the site's favicon as the icon. On macOS it writes a `.app` bundle
+  (`Info.plist`, the viewer under `Contents/MacOS`, and an `.icns` generated from
+  the favicon); on Linux, with a Linux `--base`, it writes an AppImage-style
+  `.AppDir` and folds it into a single `.AppImage` when `appimagetool` is
+  installed. The icon is found in the mirror automatically (preferring a large
+  `apple-touch-icon.png`, then `favicon.png` or a PNG-based `favicon.ico`) and
+  can be overridden with `--icon`.
+- The release now ships a GUI-subsystem Windows base,
+  `kage_<version>_windows-gui_<arch>.zip`. Packing a viewer onto it with
+  `--format binary --base` produces a `.exe` that opens with no console window
+  behind it, the Windows equivalent of the `.app` double-click experience.

 ### Changed

 - Clearer crawl error reporting. Each failure is logged with a classified reason (`HTTP 403 Forbidden`, `timed out`, ...), the URL, and the page that referenced it, and the end-of-run summary lists what went wrong instead of printing only a count.
+- Cross-platform packing detects the base binary's target OS from its executable
+  header (ELF, PE, or Mach-O) rather than its file name, so a Windows viewer
+  always gets a `.exe` suffix and the run hint names the right platform even when
+  the base is named without one.

 ### Fixed

@@ -8,7 +8,7 @@

 **kage** (影, "shadow") clones a website into a folder you can browse offline, with every script stripped out. It opens each page in real headless Chrome, waits for the page to settle, snapshots the DOM a human would have seen, then deletes all the JavaScript and pulls the CSS, images, and fonts down to local paths. What lands on disk looks like the live site and runs no code.

-[Install](#install) • [Quick start](#quick-start) • [Commands](#commands) • [Clone](#clone) • [Pack](#pack-it-into-one-file) • [Native window](#a-real-window-not-a-browser-tab) • [How it works](#how-it-works)
+[Install](#install) • [Quick start](#quick-start) • [Commands](#commands) • [Clone](#clone) • [Pack](#pack-it-into-one-file) • [Double-click app](#a-double-click-app) • [Native window](#a-real-window-not-a-browser-tab) • [How it works](#how-it-works)

 ![kage cloning paulgraham.com, packing it into one file, and serving it back offline](docs/static/demo.gif)

@@ -65,7 +65,7 @@ kage pack paulgraham.com --format binary -o paulgraham
 | --- | --- |
 | `kage clone <url>` | render a site in headless Chrome and write a browsable, script-free mirror |
 | `kage serve [dir]` | preview a cloned folder over a local HTTP server |
-| `kage pack <mirror-dir>` | collapse a mirror into one ZIM archive, or a self-contained viewer binary |
+| `kage pack <mirror-dir>` | collapse a mirror into one ZIM archive, a self-contained viewer binary, or a double-click app |
 | `kage open <file.zim>` | serve a packed ZIM back for offline reading |

 ## Clone
@@ -158,6 +158,32 @@ kage pack paulgraham.com --format binary --base kage-windows-amd64.exe   # -> pa

 The trade is size. The binary carries a whole kage, so it weighs around 13 MiB plus the site no matter how small the mirror is. When you only need the content, the ZIM is far leaner.

+### A double-click app
+
+A bare binary is great from a terminal, but double-click it in a file manager and the experience is rough: macOS opens a Terminal window behind the site, and on Windows a console flashes up next to it. `--format app` wraps the same viewer in a proper desktop app so a double-click just opens the site, no terminal, with the mirror's own favicon as the icon.
+
+On macOS you get a real `.app` bundle:
+
+```bash
+kage pack paulgraham.com --format app          # -> paulgraham.app
+open paulgraham.app                            # or double-click it in Finder
+```
+
+On Linux, point `--base` at a Linux kage and you get an [AppImage](https://appimage.org)-style `.AppDir` with a `.desktop` launcher (`Terminal=false`, so no console). If [`appimagetool`](https://github.com/AppImage/appimagetool) is installed, kage folds it into a single double-clickable `.AppImage` for you:
+
+```bash
+kage pack paulgraham.com --format app --base kage-linux-amd64   # -> paulgraham.AppDir (+ .AppImage)
+```
+
+kage finds the icon by digging the favicon out of the mirror (it prefers a large `apple-touch-icon.png` and falls back to `favicon.ico`); pass `--icon some.png` to override it. Pair `--format app` with a `webview` base (below) and the double-click opens a native window instead of the browser, which is the full "it's an app" effect.
+
+Windows needs no bundle, because there a single `.exe` already is the app. The catch is the console window. The release ships a `kage_<version>_windows-gui_<arch>.zip` whose binary is linked for the GUI subsystem, so a viewer packed onto it opens with no console behind it:
+
+```bash
+# Build a console-free Windows viewer (from any OS)
+kage pack paulgraham.com --format binary --base kage-windows-gui-amd64.exe   # -> paulgraham.exe
+```
+
 ## A real window, not a browser tab

 By default a packed binary opens your system browser, which means the site shows up as yet another tab, address bar and all, next to the 47 you already have open. Build kage with the `webview` tag and it opens the site in its own window instead, backed by the operating system's WebView (WKWebView on macOS, WebView2 on Windows, WebKitGTK on Linux). Paul Graham's essays, offline, in something that looks and feels like a real app:
@@ -40,7 +40,7 @@ kage crawls breadth-first from a seed URL, staying within the seed's host (and o

 ## Then what?

-A folder is the starting point, not the end. Once you have a mirror you can [pack it](/guides/packing-a-mirror/) into a single ZIM file, the open offline-archive format Kiwix uses, so the whole site travels as one file that any ZIM reader can open. Or build kage with the `webview` tag and a packed binary opens the site in its own native window instead of a browser tab:
+A folder is the starting point, not the end. Once you have a mirror you can [pack it](/guides/packing-a-mirror/) into a single ZIM file, the open offline-archive format Kiwix uses, so the whole site travels as one file that any ZIM reader can open. You can also pack it into a self-contained binary, or a double-click desktop app with the site's favicon as its icon. Or build kage with the `webview` tag and a packed binary opens the site in its own native window instead of a browser tab:

 ![paulgraham.com served offline in a native kage window](/webview.png)

@@ -99,6 +99,46 @@ A binary you built or downloaded may be quarantined by Gatekeeper on first run.
 xattr -d com.apple.quarantine ./paulgraham
 ```

+## A double-click app
+
+The self-contained binary is perfect from a terminal, but double-clicking it in a file manager is less tidy: on macOS Finder opens a Terminal window behind the site, and on Windows a console flashes alongside it. `--format app` wraps the same viewer in a real desktop app, so a double-click just opens the mirror with no terminal in sight, using the site's own favicon as the icon.
+
+On macOS it writes a standard `.app` bundle:
+
+```bash
+kage pack paulgraham.com --format app
+```
+
+```
+packed paulgraham.app
+  size 13.5 MiB
+  icon paulgraham.com/apple-touch-icon.png
+  double-click paulgraham.app to open the site offline
+```
+
+The bundle holds the packed viewer under `Contents/MacOS`, an `Info.plist` describing the app, and the icon converted to `Contents/Resources/icon.icns`. Double-click it in Finder, or run `open paulgraham.app`, and the site comes up with no console attached.
+
+On Linux, point `--base` at a Linux kage and you get an [AppImage](https://appimage.org)-style `.AppDir`: the viewer as `AppRun`, a `.desktop` launcher with `Terminal=false`, and the icon as a PNG. When [`appimagetool`](https://github.com/AppImage/appimagetool) is on your `PATH`, kage runs it for you and turns the directory into one double-clickable `.AppImage`; otherwise it leaves the `.AppDir` ready for any AppImage tool.
+
+```bash
+kage pack paulgraham.com --format app --base kage-linux-amd64   # -> paulgraham.AppDir (+ .AppImage)
+```
+
+kage picks the icon by digging through the mirror for the site's favicon. It prefers a large `apple-touch-icon.png` and falls back to `favicon.png` or a PNG-based `favicon.ico`; if a site only ships a legacy BMP `.ico` the bundle is built without a custom icon rather than with a mangled one. Override the choice with `--icon path/to/image.png`.
+
+For the full "it's an app" effect, pair `--format app` with a `webview` base so the double-click opens a native window instead of the system browser:
+
+```bash
+make build-webview
+kage pack paulgraham.com --format app --base bin/kage
+```
+
+Windows needs no bundle, because there a single `.exe` already is the app. What it needs is to lose the console window. A normal build is console-attached (handy for the CLI, since that is where clone progress prints), so the release ships a second Windows binary linked for the GUI subsystem in `kage_<version>_windows-gui_<arch>.zip`. Pack a viewer onto that base and double-clicking the result opens the site with no console behind it:
+
+```bash
+kage pack paulgraham.com --format binary --base kage-windows-gui-amd64.exe   # -> paulgraham.exe
+```
+
 ## Metadata and options

 ```bash
@@ -6,6 +6,14 @@ weight: 40

 The authoritative, commit-level history lives in [`CHANGELOG.md`](https://github.com/tamnd/kage/blob/main/CHANGELOG.md) and on the [releases page](https://github.com/tamnd/kage/releases). This page summarises each version.

+## Unreleased
+
+Double-click apps, so a packed mirror opens like a real desktop app instead of a terminal program.
+
+- **`kage pack --format app`** wraps the viewer in a double-click app with the site's favicon as its icon. On macOS that is a `.app` bundle; on Linux, with a Linux `--base`, an [AppImage](https://appimage.org)-style `.AppDir` that becomes a single `.AppImage` when `appimagetool` is installed. The icon is pulled from the mirror automatically, or set with `--icon`.
+- **A GUI-subsystem Windows base** ships in the release as `kage_<version>_windows-gui_<arch>.zip`. Pack a viewer onto it with `--format binary --base` and the resulting `.exe` opens with no console window behind it.
+- **Smarter cross-platform packing.** kage reads the base binary's executable header to detect its target OS, so a Windows viewer always gets a `.exe` name and the right run hint, regardless of how the base file is named.
+
 ## v0.1.2

 A security fix for how kage launches Chrome, clearer crawl errors, and a container image that actually runs.