@livx.cc/appwrap 0.42.3 → 0.43.0

package/src/config.ts

@@ -51,6 +51,45 @@ export interface AppwrapConfig {
    * Set 0 for no extra lift (input flush at the reported height; the strip may show). */
   iosKeyboardExtraLift?: number;
   pwaDist: string;
+  /** Desktop (Tauri chassis) shell — phase-0, macOS-only. When present, `appwrap dev|build desktop`
+   * stamps a generated Tauri wrapper (`native-desktop/`). Identity (`id`/`name`/`version`), `urlScheme`
+   * (internal deep-link loopback) and `pwaDist` (→ Tauri `frontendDist`) come from the top-level config;
+   * this only carries the desktop-window specifics. Absent → the desktop lane is inert (mobile-only app). */
+  desktop?: {
+    /** Window title (default: `name`). */
+    title?: string;
+    /** Initial window inner width in px (default 430 — a phone-ish portrait frame). */
+    width?: number;
+    /** Initial window inner height in px (default 800). */
+    height?: number;
+    /** Bundle identifier for the desktop build (default: `${id}.desktop`). Reverse-DNS. */
+    identifier?: string;
+    /** Remember the window's size + position across launches (tauri-plugin-window-state). Default
+     * `true`. When `false`, the plugin isn't registered so every launch opens at the configured
+     * `width`/`height` (no saved state applied). */
+    restoreWindowState?: boolean;
+    /** Force Google's account chooser in `signInWithPopup` OAuth. The shared WKWebView cookie store
+     * keeps the Google session, so Firebase auto-signs the remembered account; for apps that run
+     * multiple instances against different accounts (e.g. Unclaw) set `true` to append
+     * `prompt=select_account` to the popup's `accounts.google.com` OAuth URL so the user always picks.
+     * Default `false` (remember-me behavior stays). macOS-only. */
+    googleAccountPicker?: boolean;
+    /** Launch the app automatically when the user logs in (tauri-plugin-autostart, macOS LaunchAgent).
+     * Default `false`. The shell registers a login item on first launch when `true`, and explicitly
+     * REMOVES it when `false`, so flipping this off actually clears the login item on the next launch.
+     * NOTE: an adhoc-signed `.app` (the phase-0 desktop build) still autostarts via the LaunchAgent
+     * plist — no Developer ID required. macOS-only. */
+    autostart?: boolean;
+    /** Path (relative to the app root) to a TypeScript file that exports custom native handlers via
+     * `defineHandlers({...})` from `@livx.cc/appwrap/handlers`. When present the desktop shell spawns a
+     * Bun sidecar (`bun <path>`) at launch and routes any method the sidecar advertises to it — so an
+     * app ships app-custom native capabilities (called from the PWA via `kit.invoke('myapp.foo', …)`)
+     * without touching the Rust shell. Absent → the feature is fully inert (no sidecar spawned).
+     * The CLI stamps the ABSOLUTE resolved path into the shell config; handlers run with their CWD at
+     * the app dir, so `build desktop` apps must keep their repo (+ node_modules) around at runtime —
+     * embedding the handler file into the `.app` is out of scope for phase-0. macOS-only. */
+    handlers?: string;
+  };
   /** Custom URL scheme for deep links (e.g. "hellowrap" → hellowrap://...). */
   urlScheme?: string;
   /** Custom URL schemes `kit.app.canOpenUrl()` may probe (e.g. `['whatsapp', 'tg']`) — covers BOTH
@@ -241,7 +280,7 @@ export function defineConfig(config: AppwrapConfig): AppwrapConfig {
  */
 export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
   'appBoundDomains', 'backendOrigin', 'backgroundAudio', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'debug',
-  'debugLog', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'name',
+  'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'name',
   'iosEntitlements', 'neutralizeServiceWorker', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
   'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'signing', 'signingProfiles', 'statusBarStyle',
   'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',

package/src/desktop.ts

@@ -0,0 +1,246 @@
+/**
+ * Pure desktop (Tauri-chassis) config derivation + stamp transforms — side-effect-free (no fs, no
+ * config I/O) so they unit-test against fixtures, same standard as derive.ts. The CLI wires these into
+ * the `dev|build desktop` lane: `deriveDesktopConfig` → the JSON the Rust shell reads (`shell_config.json`,
+ * embedded at compile time), `stampTauriConf` → the generated `tauri.conf.json`.
+ */
+import type { AppwrapConfig } from './config';
+
+/** The resolved shell config the Rust desktop chassis reads (mirrors the `ShellConfig` struct in
+ * runtime-desktop/src-tauri/src/main.rs — keys are camelCase; Rust deserializes with rename_all). */
+export interface DesktopShellConfig {
+  appId: string;
+  name: string;
+  version: string;
+  title: string;
+  width: number;
+  height: number;
+  /** App's own deep-link scheme (e.g. "hellowrap"); '' when none — the Rust shell skips the
+   * `<scheme>://` loopback so an empty scheme can't spuriously match every url. */
+  urlScheme: string;
+  identifier: string;
+  /** Persist + restore window size/position across launches (default true). When false the Rust
+   * shell skips registering tauri-plugin-window-state, so the configured width/height always apply. */
+  restoreWindowState: boolean;
+  /** Append `prompt=select_account` to Google `signInWithPopup` OAuth URLs (default false) so a
+   * remembered Google session doesn't auto-sign — the user picks an account per instance. */
+  googleAccountPicker: boolean;
+  /** Launch on login via tauri-plugin-autostart (macOS LaunchAgent). Default false. The Rust shell
+   * enables the login item when true and explicitly disables it when false (so turning this off
+   * removes the item on the next launch). Works for the adhoc-signed .app (no Developer ID needed). */
+  autostart: boolean;
+  /** Path to the app's custom-handlers TS file for the Bun sidecar; '' when none (the Rust shell
+   * skips spawning the sidecar entirely). `deriveDesktopConfig` carries it through AS AUTHORED
+   * (relative to the app root); the CLI resolves it to an ABSOLUTE path before stamping
+   * `shell_config.json` (see `regenerateDesktop`), since the shell binary runs from elsewhere. */
+  handlers: string;
+  /** True when the CLI resolved a real signing identity + a macOS provisioning profile for this
+   * build (the .app will carry the aps-environment entitlement). Stamped by `build desktop` —
+   * never authored; gates the Rust shell's push capability + push.register. */
+  pushSigned: boolean;
+  /** Absolute path to the Bun binary the sidecar should be spawned with; '' until the CLI stamps it
+   * (from `process.execPath` — the exact runtime the app was built with). Needed because a
+   * GUI-launched .app inherits the launchd PATH (/usr/bin:/bin:...) which does NOT contain
+   * ~/.bun/bin, so a bare `bun` spawn fails. The Rust shell falls back to `bun` when this is
+   * missing/nonexistent. */
+  handlersRuntime: string;
+}
+
+/** Resolve the desktop shell config from an appwrap config: identity + `urlScheme` come from the
+ * top-level fields, the window specifics from the `desktop` sub-shape (with lean defaults). */
+export function deriveDesktopConfig(cfg: AppwrapConfig): DesktopShellConfig {
+  const d = cfg.desktop ?? {};
+  return {
+    appId: cfg.id,
+    name: cfg.name,
+    version: cfg.version,
+    title: d.title ?? cfg.name,
+    width: d.width ?? 430,
+    height: d.height ?? 800,
+    urlScheme: cfg.urlScheme ?? '',
+    identifier: d.identifier ?? `${cfg.id}.desktop`,
+    restoreWindowState: d.restoreWindowState ?? true,
+    googleAccountPicker: d.googleAccountPicker ?? false,
+    autostart: d.autostart ?? false,
+    handlers: d.handlers ?? '',
+    pushSigned: false, // stamped by the CLI when a signing identity + macOS profile resolve — see buildDesktop
+    handlersRuntime: '', // stamped by the CLI (process.execPath) when handlers is set — see regenerateDesktop
+  };
+}
+
+/** Stamp a `tauri.conf.json` template object from the resolved shell config + the (src-tauri-relative)
+ * frontendDist. Pure: takes the parsed template, returns the stamped object (the CLI reads/writes). */
+export function stampTauriConf(
+  template: Record<string, unknown>,
+  shell: DesktopShellConfig,
+  frontendDist: string,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    ...template,
+    productName: shell.name,
+    version: shell.version,
+    identifier: shell.identifier,
+    build: { ...(template.build as Record<string, unknown> | undefined), frontendDist },
+  };
+  // tauri-plugin-deep-link needs its schemes declared for the desktop lane (used by the plugin's
+  // registration + the tauri bundler). We assemble the .app ourselves, but keep this in sync so the
+  // plugin config is honest. Omit entirely when the app declares no scheme.
+  if (shell.urlScheme) {
+    const plugins = { ...(template.plugins as Record<string, unknown> | undefined) };
+    plugins['deep-link'] = { desktop: { schemes: [shell.urlScheme] } };
+    out.plugins = plugins;
+  }
+  return out;
+}
+
+const xmlEscape = (s: string): string =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/**
+ * Generate the macOS `Contents/Info.plist` for the assembled `.app`. This is what registers the app's
+ * `urlScheme` with LaunchServices (CFBundleURLTypes) so a `<scheme>://…` open reaches the running shell
+ * via tauri-plugin-deep-link. `executable` = the copied Mach-O name (CFBundleExecutable must match the
+ * file in `Contents/MacOS/`); `iconFile` = the `.icns` basename when an icon was generated (else omit);
+ * `iconName` = the asset-catalog icon name (e.g. `AppIcon`) when an `Assets.car` was compiled — macOS 26
+ * (Tahoe) resolves the Finder/Dock icon via `CFBundleIconName`+`Assets.car`, not the legacy `.icns`.
+ */
+export function buildInfoPlist(
+  shell: DesktopShellConfig,
+  executable: string,
+  iconFile?: string,
+  iconName?: string,
+): string {
+  const urlTypes = shell.urlScheme
+    ? `
+	<key>CFBundleURLTypes</key>
+	<array>
+		<dict>
+			<key>CFBundleURLName</key>
+			<string>${xmlEscape(shell.identifier)}</string>
+			<key>CFBundleURLSchemes</key>
+			<array>
+				<string>${xmlEscape(shell.urlScheme)}</string>
+			</array>
+		</dict>
+	</array>`
+    : '';
+  const icon = iconFile
+    ? `
+	<key>CFBundleIconFile</key>
+	<string>${xmlEscape(iconFile)}</string>`
+    : '';
+  const iconAsset = iconName
+    ? `
+	<key>CFBundleIconName</key>
+	<string>${xmlEscape(iconName)}</string>`
+    : '';
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleName</key>
+	<string>${xmlEscape(shell.name)}</string>
+	<key>CFBundleDisplayName</key>
+	<string>${xmlEscape(shell.name)}</string>
+	<key>CFBundleIdentifier</key>
+	<string>${xmlEscape(shell.identifier)}</string>
+	<key>CFBundleVersion</key>
+	<string>${xmlEscape(shell.version)}</string>
+	<key>CFBundleShortVersionString</key>
+	<string>${xmlEscape(shell.version)}</string>
+	<key>CFBundleExecutable</key>
+	<string>${xmlEscape(executable)}</string>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<key>NSHighResolutionCapable</key>
+	<true/>${icon}${iconAsset}${urlTypes}
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Generate the macOS code-signing entitlements plist for the signed desktop lane. macOS uses the
+ * PREFIXED keys (`com.apple.application-identifier`, `com.apple.developer.aps-environment`) — the
+ * bare iOS spellings (`application-identifier`, `aps-environment`) are NOT valid on macOS. The
+ * restricted entitlements here (app identifier + aps) only launch when backed by an embedded
+ * provisioning profile, so the caller must only include `apsEnvironment` when it embeds one.
+ * `apsEnvironment`: 'development' for Apple Development signing, 'production' for Developer ID.
+ */
+/** A macOS provisioning profile's decoded payload (the CMS-decoded `security cms -D` plist). */
+export interface MacProfileInfo {
+  teamId?: string;
+  appId?: string;
+  expiration?: string;
+  /** The profile's OWN `com.apple.developer.aps-environment` entitlement (source of truth for the
+   * app entitlement — a cert-derived guess can claim `production` the profile doesn't back → launch kill). */
+  apsEnvironment?: string;
+  /** Base64 DER of each embedded DeveloperCertificate (whitespace-stripped). */
+  certificates: string[];
+}
+
+/** Parse a CMS-decoded `.provisionprofile` plist (XML). Pure — unit-tested. */
+export function parseMacProfile(plist: string): MacProfileInfo {
+  const teamId = plist.match(/<key>TeamIdentifier<\/key>\s*<array>\s*<string>([^<]+)<\/string>/)?.[1];
+  const appId = plist.match(/<key>com\.apple\.application-identifier<\/key>\s*<string>([^<]+)<\/string>/)?.[1];
+  const expiration = plist.match(/<key>ExpirationDate<\/key>\s*<date>([^<]+)<\/date>/)?.[1];
+  const apsEnvironment = plist.match(/<key>com\.apple\.developer\.aps-environment<\/key>\s*<string>([^<]+)<\/string>/)?.[1];
+  const certBlock = plist.match(/<key>DeveloperCertificates<\/key>\s*<array>([\s\S]*?)<\/array>/)?.[1] ?? '';
+  const certificates = [...certBlock.matchAll(/<data>([\s\S]*?)<\/data>/g)].map((m) => m[1].replace(/\s+/g, ''));
+  return { teamId, appId, expiration, apsEnvironment, certificates };
+}
+
+export function buildMacEntitlements(opts: {
+  teamId: string;
+  bundleId: string;
+  apsEnvironment?: 'development' | 'production';
+}): string {
+  const aps = opts.apsEnvironment
+    ? `
+	<key>com.apple.developer.aps-environment</key>
+	<string>${xmlEscape(opts.apsEnvironment)}</string>`
+    : '';
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.application-identifier</key>
+	<string>${xmlEscape(`${opts.teamId}.${opts.bundleId}`)}</string>
+	<key>com.apple.developer.team-identifier</key>
+	<string>${xmlEscape(opts.teamId)}</string>${aps}
+</dict>
+</plist>
+`;
+}
+
+/** Result of locating a spawnable `cargo` for the desktop lane. `bin` is what to invoke (a bare
+ * `cargo` when it's already on PATH, else the absolute `<home>/.cargo/bin/cargo`); `path` is the
+ * (possibly augmented) PATH to hand the child so rustc/rustup neighbours resolve too. */
+export interface CargoResolution {
+  found: boolean;
+  augmented: boolean;
+  bin: string;
+  path: string;
+}
+
+/** Pure PATH resolution for `cargo` (side-effect-free — fs access is injected via `hasCargo`), so it
+ * unit-tests against fixtures. If `cargo` isn't on any current PATH entry but `<home>/.cargo/bin/cargo`
+ * exists (rustup's default location, commonly missing from a GUI/login shell's PATH), append that dir
+ * and invoke the binary by absolute path. Returns `found:false` when it's genuinely nowhere — the
+ * caller turns that into an actionable "install rust via rustup / source $HOME/.cargo/env" message
+ * instead of a raw spawn ENOENT. */
+export function resolveCargoPath(opts: {
+  path: string;
+  home: string;
+  delimiter: string;
+  hasCargo: (dir: string) => boolean;
+}): CargoResolution {
+  const { path, home, delimiter, hasCargo } = opts;
+  const dirs = path.split(delimiter).filter(Boolean);
+  if (dirs.some(hasCargo)) return { found: true, augmented: false, bin: 'cargo', path };
+  const cargoBin = home ? `${home}/.cargo/bin` : '';
+  if (cargoBin && hasCargo(cargoBin)) {
+    return { found: true, augmented: true, bin: `${cargoBin}/cargo`, path: [...dirs, cargoBin].join(delimiter) };
+  }
+  return { found: false, augmented: false, bin: 'cargo', path };
+}

package/src/handlers.ts

@@ -0,0 +1,71 @@
+/**
+ * `defineHandlers` — author custom native handlers for the appwrap DESKTOP shell, run as a Bun sidecar.
+ *
+ * The desktop shell (runtime-desktop) spawns `bun <yourFile>` when `desktop.handlers` is set, and routes
+ * any method your map advertises to this process over NDJSON on stdin/stdout (appwrap sidecar protocol v1).
+ * The PWA calls them through the kit with a raw invoke: `kit.invoke('myapp.foo', { … })`.
+ *
+ *   // handlers.ts (referenced by desktop.handlers in appwrap.config.ts)
+ *   import { defineHandlers } from '@livx.cc/appwrap/handlers';
+ *   defineHandlers({
+ *     'myapp.echo':   (p) => ({ echoed: p }),
+ *     'myapp.addOne': (p) => ({ n: (p.n ?? 0) + 1 }),
+ *   });
+ *
+ * Wire protocol (one JSON object per line):
+ *   sidecar → shell (on spawn):  { "kind":"ready", "methods":["myapp.echo", …] }
+ *   shell   → sidecar:           { "kind":"request",  "id":"…", "method":"…", "params":{…} }
+ *   sidecar → shell (per req):   { "kind":"response", "id":"…", "ok":true,  "data":{…} }
+ *                          or:   { "kind":"response", "id":"…", "ok":false, "error":{ "code":"…", "message":"…" } }
+ * A handler that throws is caught and returned as ok:false / NATIVE_ERROR — the shell maps that to the
+ * kit error envelope, so a bug in one handler never takes the sidecar down.
+ */
+import type { Readable, Writable } from 'node:stream';
+
+export type HandlerFn = (params: any) => any | Promise<any>;
+export type HandlerMap = Record<string, HandlerFn>;
+
+/** Start the sidecar loop against process stdin/stdout. Call once, top-level, in the handlers file. */
+export function defineHandlers(map: HandlerMap): void {
+  runHandlers(map, process.stdin, process.stdout);
+  // If the shell goes away (stdin closes) without killing us, don't linger as an orphan.
+  process.stdin.on('end', () => process.exit(0));
+}
+
+/** The dispatch loop, decoupled from process streams so it's unit-testable with in-memory streams. */
+export function runHandlers(map: HandlerMap, input: Readable, output: Writable): void {
+  const write = (obj: unknown): void => { output.write(JSON.stringify(obj) + '\n'); };
+  // Announce the surface first — the shell blocks on this line (with a timeout) before going live.
+  write({ kind: 'ready', methods: Object.keys(map) });
+
+  let buf = '';
+  input.setEncoding('utf8');
+  input.on('data', (chunk: string) => {
+    buf += chunk;
+    let nl: number;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (line) void handleLine(line);
+    }
+  });
+
+  async function handleLine(line: string): Promise<void> {
+    let req: any;
+    try { req = JSON.parse(line); } catch { return; } // ignore malformed lines
+    if (!req || req.kind !== 'request') return;
+    const id = req.id;
+    const fn = map[req.method];
+    if (!fn) {
+      // The shell only forwards advertised methods, so this is defensive.
+      write({ kind: 'response', id, ok: false, error: { code: 'UNSUPPORTED', message: `${req.method} not implemented` } });
+      return;
+    }
+    try {
+      const data = await fn(req.params);
+      write({ kind: 'response', id, ok: true, data: data ?? null });
+    } catch (e) {
+      write({ kind: 'response', id, ok: false, error: { code: 'NATIVE_ERROR', message: e instanceof Error ? e.message : String(e) } });
+    }
+  }
+}

package/src/icon.ts

@@ -0,0 +1,207 @@
+/**
+ * Dependency-free PNG codec + macOS app-icon corner rounding, in pure TS on `node:zlib`.
+ *
+ * WHY: Tauri embeds `src-tauri/icons/icon.png` via `generate_context!` and sets it as the RUNTIME
+ * app icon on macOS — which OVERRIDES the bundle icns/Assets.car in cmd+tab/Dock. The template ships
+ * a placeholder square, so every built app shows that square while running. We stamp the app's real
+ * icon in instead: downscale (sips, in the CLI) → decode here → round the corners with the macOS
+ * app-icon squircle mask → ensure RGBA (Tauri hard-requires alpha) → re-encode.
+ *
+ * Supports 8-bit RGB / RGBA, non-interlaced PNG (what `sips` emits). Errors clearly on anything else.
+ */
+import { deflateSync, inflateSync } from 'zlib';
+
+/** Apple's app-icon corner radius as a fraction of the icon side (the "squircle" bounding ratio).
+ * A plain rounded-rect at this radius is a close-enough approximation of the true superellipse. */
+export const APPLE_CORNER_RATIO = 0.2237;
+
+const PNG_SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export interface RgbaImage {
+  width: number;
+  height: number;
+  /** Row-major RGBA, 4 bytes/pixel, length = width*height*4. */
+  data: Buffer;
+}
+
+const paeth = (a: number, b: number, c: number): number => {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  if (pb <= pc) return b;
+  return c;
+};
+
+/** Decode an 8-bit, non-interlaced RGB/RGBA PNG into a normalized RGBA image. RGB input gets an
+ * opaque (255) alpha channel added. Throws on unsupported PNGs (paletted, 16-bit, interlaced, …). */
+export function decodePng(buf: Buffer): RgbaImage {
+  if (buf.length < 8 || !buf.subarray(0, 8).equals(PNG_SIG)) throw new Error('not a PNG (bad signature)');
+
+  let width = 0;
+  let height = 0;
+  let bitDepth = 0;
+  let colorType = -1;
+  const idat: Buffer[] = [];
+
+  let off = 8;
+  while (off + 8 <= buf.length) {
+    const len = buf.readUInt32BE(off);
+    const type = buf.toString('ascii', off + 4, off + 8);
+    const dataStart = off + 8;
+    const data = buf.subarray(dataStart, dataStart + len);
+    if (type === 'IHDR') {
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      bitDepth = data[8];
+      colorType = data[9];
+      const interlace = data[12];
+      if (bitDepth !== 8) throw new Error(`unsupported PNG bit depth ${bitDepth} (only 8-bit)`);
+      if (colorType !== 2 && colorType !== 6)
+        throw new Error(`unsupported PNG color type ${colorType} (only RGB=2 / RGBA=6)`);
+      if (interlace !== 0) throw new Error('unsupported interlaced PNG');
+    } else if (type === 'IDAT') {
+      idat.push(Buffer.from(data));
+    } else if (type === 'IEND') {
+      break;
+    }
+    off = dataStart + len + 4; // +4 CRC
+  }
+  if (!width || !height) throw new Error('PNG missing IHDR');
+
+  const channels = colorType === 6 ? 4 : 3;
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  if (raw.length < (stride + 1) * height) throw new Error('PNG IDAT truncated');
+
+  // Unfilter scanlines (filter types 0-4) in place into a channels-packed buffer.
+  const unf = Buffer.alloc(stride * height);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const inRow = y * (stride + 1) + 1;
+    const outRow = y * stride;
+    for (let x = 0; x < stride; x++) {
+      const rawByte = raw[inRow + x];
+      const a = x >= channels ? unf[outRow + x - channels] : 0; // left
+      const b = y > 0 ? unf[outRow - stride + x] : 0; // up
+      const c = x >= channels && y > 0 ? unf[outRow - stride + x - channels] : 0; // up-left
+      let val: number;
+      switch (filter) {
+        case 0: val = rawByte; break;
+        case 1: val = rawByte + a; break;
+        case 2: val = rawByte + b; break;
+        case 3: val = rawByte + ((a + b) >> 1); break;
+        case 4: val = rawByte + paeth(a, b, c); break;
+        default: throw new Error(`unsupported PNG filter type ${filter}`);
+      }
+      unf[outRow + x] = val & 0xff;
+    }
+  }
+
+  // Normalize to RGBA.
+  const data = Buffer.alloc(width * height * 4);
+  for (let i = 0, j = 0; i < width * height; i++) {
+    data[j++] = unf[i * channels];
+    data[j++] = unf[i * channels + 1];
+    data[j++] = unf[i * channels + 2];
+    data[j++] = channels === 4 ? unf[i * channels + 3] : 255;
+  }
+  return { width, height, data };
+}
+
+/** Encode a normalized RGBA image to a PNG (color type 6, 8-bit, filter type 0, zlib deflate). */
+export function encodePng(img: RgbaImage): Buffer {
+  const { width, height, data } = img;
+  const stride = width * 4;
+  const rawFiltered = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    rawFiltered[y * (stride + 1)] = 0; // filter type 0 (None)
+    data.copy(rawFiltered, y * (stride + 1) + 1, y * stride, y * stride + stride);
+  }
+  const idat = deflateSync(rawFiltered);
+
+  const chunk = (type: string, body: Buffer): Buffer => {
+    const out = Buffer.alloc(12 + body.length);
+    out.writeUInt32BE(body.length, 0);
+    out.write(type, 4, 'ascii');
+    body.copy(out, 8);
+    out.writeUInt32BE(crc32(out.subarray(4, 8 + body.length)), 8 + body.length);
+    return out;
+  };
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 6; // color type RGBA
+  ihdr[10] = 0; // compression
+  ihdr[11] = 0; // filter
+  ihdr[12] = 0; // interlace
+  return Buffer.concat([PNG_SIG, chunk('IHDR', ihdr), chunk('IDAT', idat), chunk('IEND', Buffer.alloc(0))]);
+}
+
+/** Multiply the alpha channel by a rounded-rect mask (radius = ratio*side) so corners become
+ * transparent — the macOS app-icon shape. Mutates + returns the image. */
+export function roundCorners(img: RgbaImage, ratio: number = APPLE_CORNER_RATIO): RgbaImage {
+  const { width, height, data } = img;
+  const r = Math.min(width, height) * ratio;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      // Distance into the nearest corner's radius square; only corners are clipped.
+      const dx = x < r ? r - (x + 0.5) : x + 0.5 > width - r ? x + 0.5 - (width - r) : 0;
+      const dy = y < r ? r - (y + 0.5) : y + 0.5 > height - r ? y + 0.5 - (height - r) : 0;
+      if (dx > 0 && dy > 0) {
+        const dist = Math.sqrt(dx * dx + dy * dy);
+        // 1px anti-aliased edge: coverage 1 inside the radius, 0 outside, linear across the boundary.
+        const coverage = Math.max(0, Math.min(1, r - dist + 0.5));
+        const idx = (y * width + x) * 4 + 3;
+        data[idx] = Math.round(data[idx] * coverage);
+      }
+    }
+  }
+  return img;
+}
+
+/** Center the image on a larger transparent canvas (no resampling — callers pre-size via sips).
+ * macOS app icons bake in a transparent margin: the squircle artwork is 824px on a 1024 canvas
+ * (~80.5%). A full-bleed runtime icon renders visibly LARGER than its bundle-masked Dock neighbors. */
+export function padToCanvas(img: RgbaImage, canvas: number): RgbaImage {
+  const { width, height, data } = img;
+  const ox = Math.floor((canvas - width) / 2);
+  const oy = Math.floor((canvas - height) / 2);
+  const out = Buffer.alloc(canvas * canvas * 4);
+  for (let y = 0; y < height; y++) {
+    out.set(data.subarray(y * width * 4, (y + 1) * width * 4), ((y + oy) * canvas + ox) * 4);
+  }
+  return { width: canvas, height: canvas, data: out };
+}
+
+/** Artwork fraction of the icon canvas per Apple's Big Sur+ app-icon grid (824/1024). */
+export const APPLE_ICON_GRID_SCALE = 824 / 1024;
+
+/** Convenience: decode a (sips-produced) PNG, round its corners, guarantee RGBA, re-encode. */
+export function makeRoundedRgbaIcon(pngBuf: Buffer, ratio: number = APPLE_CORNER_RATIO): Buffer {
+  return encodePng(roundCorners(decodePng(pngBuf), ratio));
+}
+
+/** Dock-parity runtime icon: rounded artwork centered on a transparent `canvas`² px canvas at the
+ * Apple icon-grid scale. Input PNG should already be sized to `canvas * APPLE_ICON_GRID_SCALE`. */
+export function makeDockRuntimeIcon(pngBuf: Buffer, canvas: number): Buffer {
+  return encodePng(padToCanvas(roundCorners(decodePng(pngBuf)), canvas));
+}
+
+// ─── CRC32 (PNG/zlib polynomial) ───
+let CRC_TABLE: Uint32Array | null = null;
+function crc32(buf: Buffer): number {
+  if (!CRC_TABLE) {
+    CRC_TABLE = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+      let c = n;
+      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+      CRC_TABLE[n] = c >>> 0;
+    }
+  }
+  let crc = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) crc = CRC_TABLE[(crc ^ buf[i]) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}