@nativedesktop/cli 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nativedesktop/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The nd CLI: dev-runs, builds, and packages NativeDesktop apps",
   "type": "module",
   "license": "MIT",
@@ -12,17 +12,19 @@
   "homepage": "https://github.com/FormalSnake/NativeDesktop#readme",
   "bugs": "https://github.com/FormalSnake/NativeDesktop/issues",
   "publishConfig": {
-  "access": "public"
-},
-"files": ["src"],
-"bin": {
-"nd": "src/index.ts"
-},
-"exports": {
-  ".": "./src/index.ts",
-  "./config": "./src/config.ts"
-},
-"dependencies": {
-  "@nativedesktop/host": "0.1.0"
-}
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "bin": {
+    "nd": "src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./config": "./src/config.ts"
+  },
+  "dependencies": {
+    "@nativedesktop/host": "0.1.2"
+  }
 }

package/src/config.ts

@@ -32,11 +32,45 @@ export interface UrlScheme {
   name?: string;
 }
 
+/**
+ * A solid color, or a two-stop gradient running top to bottom. Colors are hex
+ * (`#0a84ff`, `#0a84ffcc`) or an Icon Composer color string
+ * (`display-p3:0.04,0.52,1,1`).
+ */
+export type AppIconFill = string | { gradient: [string, string] };
+
+export interface AppIconLayer {
+  /** App-relative .svg or .png, drawn full-bleed on the 1024x1024 icon grid. */
+  image: string;
+  /** Layer name shown in Icon Composer. Default: the file's basename. */
+  name?: string;
+  /** Liquid Glass specular highlight. Default true. */
+  specular?: boolean;
+  /** Glass translucency 0..1, or false to turn it off. Default 0.5. */
+  translucency?: number | false;
+  /** Drop shadow opacity 0..1, or false to turn it off. Default 0.5. */
+  shadow?: number | false;
+}
+
+/** A macOS 26 layered icon, built into a .icon bundle at package time. */
+export interface AppIconLayered {
+  /** Fill behind the layers. Omitted leaves the icon body transparent. */
+  background?: AppIconFill;
+  /** 1 to 4 layers, back to front. A bare string is shorthand for `{ image }`. */
+  layers: Array<string | AppIconLayer>;
+}
+
 export interface AppIcon {
-  /** Shared icon source (.png/.svg/.icns path, app-relative). */
+  /** Shared icon source (.png/.svg/.icns/.iconset/.icon path, app-relative). */
   source?: string;
+  /** macOS override: .icon, .icns, .iconset, .png, or .svg. */
   macos?: string;
+  /** Linux override: .png, .svg, or .icon. */
   linux?: string;
+  /** Layered macOS 26 icon composed from separate art files. Used on macOS
+   * unless `macos` overrides it, and flattens to the Linux icon when neither
+   * `linux` nor `source` is set. */
+  layered?: AppIconLayered;
 }
 
 export interface AppIdentity {

package/src/package/doctor.ts

@@ -19,6 +19,31 @@ function which(tool: string): boolean {
   return Bun.which(tool) !== null;
 }
 
+/** Every mac icon source needs a different converter, so the check follows the
+ * same resolution order `installMacIcon` uses. */
+function macIconChecks(config: NativeDesktopConfig): Check[] {
+  const icon = typeof config.app?.icon === "string" ? { source: config.app.icon } : config.app?.icon;
+  if (!icon) return [];
+  const source = icon.layered ? ".icon" : icon.macos ?? icon.source;
+  if (!source) return [];
+  if (source.endsWith(".icon")) {
+    return [which("xcrun")
+      ? { name: "icon-tools", status: "ok", detail: "layered icon configured, actool available" }
+      : { name: "icon-tools", status: "error", detail: "layered icon configured but Xcode's actool is missing" }];
+  }
+  if (source.endsWith(".icns")) return [];
+  if (source.endsWith(".iconset")) {
+    return which("iconutil") ? [] : [{ name: "icon-tools", status: "error", detail: "iconset icon configured but iconutil is missing" }];
+  }
+  if (source.endsWith(".svg") && !["rsvg-convert", "magick", "convert", "qlmanage"].some(which)) {
+    return [{ name: "icon-tools", status: "error", detail: "SVG icon configured but no rasterizer (librsvg, ImageMagick, or qlmanage) is available" }];
+  }
+  if (!(which("sips") && which("iconutil"))) {
+    return [{ name: "icon-tools", status: "error", detail: `${source} icon configured but sips/iconutil are missing` }];
+  }
+  return [];
+}
+
 export async function collectChecks(cwd: string): Promise<Check[]> {
   const checks: Check[] = [];
   const configPath = resolve(cwd, "nativedesktop.config.ts");
@@ -63,10 +88,17 @@ export async function collectChecks(cwd: string): Promise<Check[]> {
   try {
     const backend = resolveBackend(process.platform === "darwin" ? { backend: config.package?.mac?.backend ?? "appkit" } : { backend: "gtk" });
     const { fresh } = hostBinaryCandidates(backend);
-    const found = prebuiltHostBinary(backend) ?? fresh.find(existsSync);
-    checks.push(found
-      ? { name: "host", status: "ok", detail: found }
-      : { name: "host", status: "warn", detail: `no ${backend} host binary built yet (nd dev / nd package builds it on first run in a source checkout)` });
+    // ND_HOST_BINARY is what `nd dev` will actually run, so report that rather
+    // than the prebuilt it overrides.
+    const explicit = process.env.ND_HOST_BINARY;
+    const found = explicit || prebuiltHostBinary(backend) || fresh.find(existsSync);
+    if (explicit && !existsSync(explicit)) {
+      checks.push({ name: "host", status: "error", detail: `ND_HOST_BINARY points at ${explicit}, which does not exist` });
+    } else {
+      checks.push(found
+        ? { name: "host", status: "ok", detail: explicit ? `${found} (ND_HOST_BINARY)` : found }
+        : { name: "host", status: "warn", detail: `no ${backend} host binary built yet (nd dev / nd package builds it on first run in a source checkout)` });
+    }
   } catch (err) {
     checks.push({ name: "host", status: "error", detail: String(err) });
   }
@@ -75,10 +107,7 @@ export async function collectChecks(cwd: string): Promise<Check[]> {
     checks.push(which("codesign")
       ? { name: "codesign", status: "ok", detail: "codesign available" }
       : { name: "codesign", status: "error", detail: "codesign not found (install the Xcode command line tools)" });
-    const icon = typeof config.app?.icon === "string" ? config.app.icon : config.app?.icon?.macos ?? config.app?.icon?.source;
-    if (icon && icon.endsWith(".png") && !(which("sips") && which("iconutil"))) {
-      checks.push({ name: "icon-tools", status: "error", detail: "PNG icon configured but sips/iconutil are missing" });
-    }
+    checks.push(...macIconChecks(config));
   } else if (process.platform === "linux") {
     checks.push(which("appimagetool") || which("mksquashfs")
       ? { name: "appimage", status: "ok", detail: which("appimagetool") ? "appimagetool available" : "mksquashfs fallback available" }

package/src/package/iconcomposer.ts

@@ -0,0 +1,315 @@
+// macOS 26 layered app icons. An Icon Composer ".icon" is a directory holding an
+// icon.json manifest next to an Assets/ folder of layer art; actool compiles one
+// into the Assets.car macOS 26 renders plus the .icns older releases fall back
+// to. Two constraints shape the code here: actool matches --app-icon against the
+// bundle's BASENAME and exits 0 having written nothing when they disagree, and
+// icon.json colors must be "<space>:r,g,b,a" floats (a hex string is rejected).
+//
+// The same composition also flattens to a single SVG for Linux, so one set of
+// layer art dresses both platforms.
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, extname, join, resolve } from "node:path";
+import type { AppIconFill, AppIconLayer, AppIconLayered } from "../config.ts";
+
+/** Runs an icon tool, surfacing its output only when it fails (actool prints a
+ * result plist to stdout on every successful compile). */
+export async function runTool(command: string[]): Promise<void> {
+  const proc = Bun.spawn(command, { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+  const [out, err, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (code === 0) return;
+  if (out) process.stderr.write(out);
+  if (err) process.stderr.write(err);
+  throw new Error(`nd: icon tool failed (${command.join(" ")})`);
+}
+
+type Rgba = [number, number, number, number];
+
+/** Accepts #rgb/#rgba/#rrggbb/#rrggbbaa or an Icon Composer "<space>:r,g,b,a" string. */
+function parseColor(value: string): Rgba {
+  const colon = value.indexOf(":");
+  if (colon >= 0) {
+    const parts = value.slice(colon + 1).split(",").map(Number);
+    if (parts.length < 3 || parts.some(Number.isNaN)) throw new Error(`nd: unreadable icon color "${value}"`);
+    return [parts[0]!, parts[1]!, parts[2]!, parts[3] ?? 1];
+  }
+  const hex = value.startsWith("#") ? value.slice(1) : value;
+  const wide = hex.length <= 4 ? hex.replace(/./g, (c) => c + c) : hex;
+  if (!/^[0-9a-f]{6}([0-9a-f]{2})?$/i.test(wide)) {
+    throw new Error(`nd: unsupported icon color "${value}" (want #rrggbb, #rrggbbaa, or "display-p3:r,g,b,a")`);
+  }
+  const channel = (at: number) => parseInt(wide.slice(at, at + 2), 16) / 255;
+  return [channel(0), channel(2), channel(4), wide.length === 8 ? channel(6) : 1];
+}
+
+/** A color string icon.json accepts. Color-space inputs pass through untouched;
+ * hex is normalized into extended sRGB floats. */
+function iconColor(value: string): string {
+  if (value.includes(":")) return value;
+  return `extended-srgb:${parseColor(value).map((c) => c.toFixed(5)).join(",")}`;
+}
+
+function cssColor(value: string): string {
+  const byte = (c: number) => Math.round(Math.min(1, Math.max(0, c)) * 255).toString(16).padStart(2, "0");
+  const [r, g, b] = parseColor(value);
+  return `#${byte(r)}${byte(g)}${byte(b)}`;
+}
+
+function cssOpacity(value: string): number {
+  return Math.min(1, Math.max(0, parseColor(value)[3]));
+}
+
+function fillManifest(fill: AppIconFill): Record<string, unknown> {
+  if (typeof fill === "string") return { solid: iconColor(fill) };
+  const [top, bottom] = fill.gradient;
+  return { "linear-gradient": [iconColor(top), iconColor(bottom)] };
+}
+
+const LAYER_EXTENSIONS = new Set([".svg", ".png"]);
+/** Icon Composer stacks at most four groups, one per depth level. */
+const MAX_LAYERS = 4;
+
+interface ResolvedLayer {
+  path: string;
+  /** Filename inside Assets/, deduplicated across layers from different directories. */
+  file: string;
+  name: string;
+  layer: AppIconLayer;
+}
+
+function resolveLayers(layered: AppIconLayered, appDir: string): ResolvedLayer[] {
+  const entries = layered.layers ?? [];
+  if (!entries.length) throw new Error("nd: app.icon.layered needs at least one layer");
+  if (entries.length > MAX_LAYERS) {
+    throw new Error(`nd: app.icon.layered takes at most ${MAX_LAYERS} layers (got ${entries.length})`);
+  }
+  const taken = new Set<string>();
+  return entries.map((entry) => {
+    const layer = typeof entry === "string" ? { image: entry } : entry;
+    const path = resolve(appDir, layer.image);
+    const ext = extname(path).toLowerCase();
+    if (!LAYER_EXTENSIONS.has(ext)) throw new Error(`nd: unsupported icon layer "${layer.image}" (want .svg or .png)`);
+    if (!existsSync(path)) throw new Error(`nd: icon layer not found: ${path}`);
+    const stem = basename(path, ext);
+    let file = `${stem}${ext}`;
+    for (let n = 2; taken.has(file); n++) file = `${stem}-${n}${ext}`;
+    taken.add(file);
+    return { path, file, name: layer.name ?? stem, layer };
+  });
+}
+
+/** The shape readIconBundle returns, for a layered config instead of a bundle. */
+export function layeredComposition(layered: AppIconLayered, appDir: string): { background?: AppIconFill; layers: string[] } {
+  return { background: layered.background, layers: resolveLayers(layered, appDir).map((layer) => layer.path) };
+}
+
+/** The icon.json a layered config compiles to. */
+export function iconManifest(layered: AppIconLayered, appDir: string): string {
+  return manifestJson(layered, resolveLayers(layered, appDir));
+}
+
+/** One group per layer, so the glass controls stay per-layer in the config. */
+function manifestJson(layered: AppIconLayered, layers: ResolvedLayer[]): string {
+  const manifest: Record<string, unknown> = {};
+  if (layered.background) manifest.fill = fillManifest(layered.background);
+  manifest.groups = layers.map(({ file, name, layer }) => ({
+    layers: [{ "image-name": file, name }],
+    specular: layer.specular ?? true,
+    translucency: layer.translucency === false
+      ? { enabled: false, value: 0 }
+      : { enabled: true, value: layer.translucency ?? 0.5 },
+    shadow: layer.shadow === false
+      ? { kind: "none", opacity: 0 }
+      : { kind: "neutral", opacity: layer.shadow ?? 0.5 },
+  }));
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+/** Writes a .icon bundle at `bundle` from a layered config. */
+export function writeIconBundle(layered: AppIconLayered, appDir: string, bundle: string): void {
+  const assets = join(bundle, "Assets");
+  mkdirSync(assets, { recursive: true });
+  const layers = resolveLayers(layered, appDir);
+  for (const { path, file } of layers) cpSync(path, join(assets, file));
+  writeFileSync(join(bundle, "icon.json"), manifestJson(layered, layers));
+}
+
+/**
+ * Compiles a .icon into Assets.car + the legacy .icns inside `resourcesDir`.
+ * Returns the CFBundleIconName/CFBundleIconFile value.
+ */
+export async function compileIconBundle(bundle: string, resourcesDir: string, deploymentTarget: string): Promise<string> {
+  if (!Bun.which("xcrun")) {
+    throw new Error(`nd: compiling ${basename(bundle)} needs Xcode's actool (install Xcode, or set app.icon.macos to a prebuilt .icns)`);
+  }
+  const name = basename(bundle, ".icon");
+  const out = mkdtempSync(join(tmpdir(), "nd-actool-"));
+  try {
+    await runTool([
+      "xcrun", "actool", bundle,
+      "--app-icon", name,
+      "--compile", out,
+      "--output-partial-info-plist", join(out, "partial.plist"),
+      "--minimum-deployment-target", deploymentTarget,
+      "--platform", "macosx",
+      "--target-device", "mac",
+    ]);
+    const car = join(out, "Assets.car");
+    // actool keys off the bundle basename and reports success while emitting
+    // nothing when the icon it was asked for isn't there, so a missing
+    // Assets.car is the only signal that the compile didn't take.
+    if (!existsSync(car)) throw new Error(`nd: actool compiled no icon out of ${bundle}`);
+    cpSync(car, join(resourcesDir, "Assets.car"));
+    const icns = join(out, `${name}.icns`);
+    if (existsSync(icns)) cpSync(icns, join(resourcesDir, `${name}.icns`));
+    return name;
+  } finally {
+    rmSync(out, { recursive: true, force: true });
+  }
+}
+
+/** Icon Composer writes richer fills than the Linux flatten can draw, so an
+ * unreadable one is an error naming the escape hatch rather than a wrong icon. */
+function readFill(fill: Record<string, unknown> | undefined, bundle: string): AppIconFill | undefined {
+  if (!fill) return undefined;
+  const gradient = fill["linear-gradient"];
+  if (Array.isArray(gradient) && gradient.length >= 2 && gradient.every((stop) => typeof stop === "string")) {
+    return { gradient: [gradient[0] as string, gradient[1] as string] };
+  }
+  // An automatic gradient is derived by the renderer from one seed color; Linux
+  // has no equivalent, so it flattens to that color.
+  const solid = fill.solid ?? fill["automatic-gradient"];
+  if (typeof solid === "string") return solid;
+  throw new Error(`nd: cannot flatten ${bundle}'s background for Linux - set app.icon.linux to a PNG or SVG`);
+}
+
+/** The parts of an existing .icon the Linux flatten needs: the background fill
+ * and every layer's art, back to front. */
+export function readIconBundle(bundle: string): { background?: AppIconFill; layers: string[] } {
+  const manifestPath = join(bundle, "icon.json");
+  if (!existsSync(manifestPath)) throw new Error(`nd: ${bundle} has no icon.json`);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+    fill?: Record<string, unknown>;
+    groups?: Array<{ layers?: Array<{ "image-name"?: string }> }>;
+  };
+  const background = readFill(manifest.fill, basename(bundle));
+  const layers: string[] = [];
+  for (const group of manifest.groups ?? []) {
+    for (const layer of group.layers ?? []) {
+      const file = layer["image-name"];
+      if (!file) continue;
+      const path = join(bundle, "Assets", file);
+      if (!existsSync(path)) throw new Error(`nd: ${basename(bundle)} references a missing layer: Assets/${file}`);
+      layers.push(path);
+    }
+  }
+  if (!layers.length) throw new Error(`nd: ${basename(bundle)} declares no layers`);
+  return { background, layers };
+}
+
+/** Icon Composer's design grid. */
+const GRID = 1024;
+// GNOME draws an app icon as a 104x104 body on a 128x128 canvas with a 24px
+// corner radius. Mapped onto the 1024 grid that is an 832px body inset by 96
+// with a 192px radius, which is what lets one composition serve both platforms.
+const BODY = 832;
+const INSET = 96;
+const RADIUS = 192;
+
+/** Flattens a layered composition into one SVG sized to the GNOME icon grid. */
+export function composeSvg(background: AppIconFill | undefined, layers: string[]): string {
+  const defs: string[] = [];
+  let fill = "none";
+  let fillOpacity = 1;
+  if (typeof background === "string") {
+    fill = cssColor(background);
+    fillOpacity = cssOpacity(background);
+  } else if (background) {
+    const [top, bottom] = background.gradient;
+    defs.push(
+      `<linearGradient id="nd-background" x1="0" y1="0" x2="0" y2="1">`
+      + `<stop offset="0" stop-color="${cssColor(top)}" stop-opacity="${cssOpacity(top)}"/>`
+      + `<stop offset="1" stop-color="${cssColor(bottom)}" stop-opacity="${cssOpacity(bottom)}"/>`
+      + `</linearGradient>`,
+    );
+    fill = "url(#nd-background)";
+  }
+  const art = layers.map((path, index) => inlineLayer(path, `nd${index}`)).join("");
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"`
+    + ` width="${GRID}" height="${GRID}" viewBox="0 0 ${GRID} ${GRID}">`,
+    defs.length ? `<defs>${defs.join("")}</defs>` : "",
+    background
+      ? `<rect x="${INSET}" y="${INSET}" width="${BODY}" height="${BODY}" rx="${RADIUS}" ry="${RADIUS}"`
+        + ` fill="${fill}" fill-opacity="${fillOpacity}"/>`
+      : "",
+    `<g transform="translate(${INSET} ${INSET}) scale(${BODY / GRID})">${art}</g>`,
+    `</svg>`,
+    "",
+  ].join("\n");
+}
+
+function inlineLayer(path: string, prefix: string): string {
+  if (extname(path).toLowerCase() === ".png") {
+    const data = readFileSync(path).toString("base64");
+    const href = `data:image/png;base64,${data}`;
+    return `<image x="0" y="0" width="${GRID}" height="${GRID}" preserveAspectRatio="xMidYMid meet"`
+      + ` href="${href}" xlink:href="${href}"/>`;
+  }
+  return nestSvg(readFileSync(path, "utf8"), prefix, path);
+}
+
+const ATTRIBUTE = `\\s*=\\s*("[^"]*"|'[^']*')`;
+
+/**
+ * Inlines an SVG file as a nested <svg> on the 1024 grid. Nested <svg> is plain
+ * SVG 1.1 that every renderer handles, unlike an SVG data URI inside <image>,
+ * which only librsvg-backed rasterizers read. Ids stay document-global through
+ * the nesting, so each layer's are namespaced before the layers are merged.
+ */
+function nestSvg(source: string, prefix: string, path: string): string {
+  const document = source.replace(/<\?xml[\s\S]*?\?>/g, "").replace(/<!DOCTYPE[\s\S]*?>/gi, "").trim();
+  const open = document.match(/<svg\b([^>]*)>/i);
+  const close = document.lastIndexOf("</svg>");
+  if (!open || close < 0) throw new Error(`nd: icon layer is not an SVG document: ${path}`);
+  const attributes = open[1]!;
+  const viewBox = attribute(attributes, "viewBox") ?? intrinsicViewBox(attributes);
+  const kept = attributes.replace(
+    new RegExp(`\\s(?:width|height|viewBox|x|y|preserveAspectRatio)${ATTRIBUTE}`, "gi"),
+    "",
+  );
+  const inner = document.slice(open.index! + open[0].length, close);
+  return `<svg${kept} x="0" y="0" width="${GRID}" height="${GRID}" viewBox="${viewBox}"`
+    + ` preserveAspectRatio="xMidYMid meet">${namespaceIds(inner, prefix)}</svg>`;
+}
+
+function attribute(attributes: string, name: string): string | undefined {
+  const match = attributes.match(new RegExp(`\\s${name}${ATTRIBUTE}`, "i"));
+  return match ? match[1]!.slice(1, -1) : undefined;
+}
+
+/** An SVG without a viewBox is measured by its width/height, dropping any unit suffix. */
+function intrinsicViewBox(attributes: string): string {
+  const width = Number.parseFloat(attribute(attributes, "width") ?? "");
+  const height = Number.parseFloat(attribute(attributes, "height") ?? "");
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return `0 0 ${GRID} ${GRID}`;
+  return `0 0 ${width} ${height}`;
+}
+
+function namespaceIds(svg: string, prefix: string): string {
+  const ids = new Set<string>();
+  for (const [, id] of svg.matchAll(/\sid\s*=\s*["']([^"']+)["']/g)) ids.add(id!);
+  let out = svg;
+  for (const id of ids) {
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    out = out
+      .replace(new RegExp(`(\\sid\\s*=\\s*["'])${escaped}(["'])`, "g"), `$1${prefix}-${id}$2`)
+      .replace(new RegExp(`url\\((["']?)#${escaped}\\1\\)`, "g"), `url($1#${prefix}-${id}$1)`)
+      .replace(new RegExp(`((?:xlink:)?href\\s*=\\s*["'])#${escaped}(["'])`, "g"), `$1#${prefix}-${id}$2`);
+  }
+  return out;
+}

package/src/package/icons.test.ts

@@ -3,9 +3,14 @@
 // whose PATH holds only the fixture's fake tools, because Bun.which and spawn
 // resolve against the process's startup PATH.
 import { describe, expect, test } from "bun:test";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import type { AppIconLayered, AppIcon } from "../config.ts";
+import { installLinuxIcon, installMacIcon } from "./icons.ts";
+import { composeSvg, iconManifest, layeredComposition } from "./iconcomposer.ts";
+import type { ResolvedIdentity } from "./identity.ts";
+import { PLACEHOLDER_PNG } from "./templates.ts";
 
 const ICONS_MODULE = join(import.meta.dir, "icons.ts");
 
@@ -59,3 +64,153 @@ describe("installLinuxIcon", () => {
     expect(existsSync(join(appdir, "usr/share/icons/hicolor"))).toBe(false);
   });
 });
+
+const GLASS_SVG = `<?xml version="1.0"?>\n<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512">`
+  + `<defs><linearGradient id="g"><stop offset="0" stop-color="#fff"/></linearGradient></defs>`
+  + `<circle cx="256" cy="256" r="200" fill="url(#g)"/></svg>`;
+
+function layeredFixture(layered: AppIconLayered): { appDir: string; identity: ResolvedIdentity } {
+  const appDir = mkdtempSync(join(tmpdir(), "nd-layered-"));
+  writeFileSync(join(appDir, "glyph.svg"), GLASS_SVG);
+  writeFileSync(join(appDir, "shine.png"), PLACEHOLDER_PNG);
+  return { appDir, identity: identityWith({ layered }) };
+}
+
+function identityWith(icon: AppIcon): ResolvedIdentity {
+  return { name: "Fixture", displayName: "Fixture", slug: "fixture", version: "1.0.0", categories: ["Utility"], icon };
+}
+
+describe("iconManifest", () => {
+  test("hex background becomes an extended-sRGB gradient and each layer gets its own group", () => {
+    const { appDir } = layeredFixture({ layers: [] });
+    const manifest = JSON.parse(iconManifest(
+      { background: { gradient: ["#0a84ff", "#5e5ce6"] }, layers: ["glyph.svg", { image: "shine.png", shadow: false, translucency: 0.2 }] },
+      appDir,
+    ));
+    expect(manifest.fill["linear-gradient"]).toEqual(["extended-srgb:0.03922,0.51765,1.00000,1.00000", "extended-srgb:0.36863,0.36078,0.90196,1.00000"]);
+    expect(manifest.groups).toHaveLength(2);
+    expect(manifest.groups[0].layers[0]).toEqual({ "image-name": "glyph.svg", name: "glyph" });
+    expect(manifest.groups[0].shadow).toEqual({ kind: "neutral", opacity: 0.5 });
+    expect(manifest.groups[1].shadow).toEqual({ kind: "none", opacity: 0 });
+    expect(manifest.groups[1].translucency).toEqual({ enabled: true, value: 0.2 });
+  });
+
+  test("a color-space string passes through untouched", () => {
+    const { appDir } = layeredFixture({ layers: [] });
+    const manifest = JSON.parse(iconManifest({ background: "display-p3:0,0.5,1,1", layers: ["glyph.svg"] }, appDir));
+    expect(manifest.fill).toEqual({ solid: "display-p3:0,0.5,1,1" });
+  });
+
+  test("more than four layers is rejected", () => {
+    const { appDir } = layeredFixture({ layers: [] });
+    const layers = ["glyph.svg", "glyph.svg", "glyph.svg", "glyph.svg", "glyph.svg"];
+    expect(() => iconManifest({ layers }, appDir)).toThrow(/at most 4 layers/);
+  });
+});
+
+describe("composeSvg", () => {
+  test("layers nest as SVG with namespaced ids over the GNOME icon body", () => {
+    const { appDir } = layeredFixture({ layers: [] });
+    const layered: AppIconLayered = { background: "#0a84ff", layers: ["glyph.svg", "shine.png"] };
+    const { background, layers } = layeredComposition(layered, appDir);
+    const svg = composeSvg(background, layers);
+    expect(svg).toContain(`<rect x="96" y="96" width="832" height="832" rx="192"`);
+    expect(svg).toContain(`fill="#0a84ff"`);
+    // The layer's own gradient id is rewritten on both the definition and the reference.
+    expect(svg).toContain(`id="nd0-g"`);
+    expect(svg).toContain(`url(#nd0-g)`);
+    // The nested <svg> keeps the source viewBox but is stretched onto the 1024 grid.
+    expect(svg).toContain(`viewBox="0 0 512 512" preserveAspectRatio="xMidYMid meet"`);
+    expect(svg).toContain(`data:image/png;base64,`);
+    expect(svg).not.toContain("<?xml version");
+  });
+});
+
+const rasterizer = ["rsvg-convert", "magick", "convert"].some((tool) => Bun.which(tool) !== null);
+
+function iconBundleFixture(fill: unknown): string {
+  const appDir = mkdtempSync(join(tmpdir(), "nd-bundle-"));
+  mkdirSync(join(appDir, "Brand.icon", "Assets"), { recursive: true });
+  writeFileSync(join(appDir, "Brand.icon", "Assets", "glyph.svg"), GLASS_SVG);
+  writeFileSync(join(appDir, "Brand.icon", "icon.json"), JSON.stringify({
+    fill,
+    groups: [{ layers: [{ "image-name": "glyph.svg", name: "glyph" }] }],
+  }));
+  return appDir;
+}
+
+describe.if(rasterizer)("installLinuxIcon", () => {
+  test("an Icon Composer bundle flattens into the linux icon set", async () => {
+    const appDir = iconBundleFixture({ "linear-gradient": ["extended-srgb:0,0.5,1,1", "extended-srgb:0.4,0.3,0.9,1"] });
+    const appdir = mkdtempSync(join(tmpdir(), "nd-appdir-"));
+    await installLinuxIcon(identityWith({ source: "Brand.icon" }), appDir, appdir);
+    expect(existsSync(join(appdir, "usr/share/icons/hicolor/scalable/apps/fixture.svg"))).toBe(true);
+    expect(existsSync(join(appdir, "usr/share/icons/hicolor/256x256/apps/fixture.png"))).toBe(true);
+  });
+
+  test("a fill the flatten cannot draw names the escape hatch", async () => {
+    const appDir = iconBundleFixture({ "automatic-gradient": { seed: "extended-srgb:0,0.5,1,1" } });
+    const appdir = mkdtempSync(join(tmpdir(), "nd-appdir-"));
+    await expect(installLinuxIcon(identityWith({ source: "Brand.icon" }), appDir, appdir)).rejects.toThrow(/app\.icon\.linux/);
+  });
+
+  test("the linux override beats a layered composition", async () => {
+    const { appDir, identity } = layeredFixture({ background: "#0a84ff", layers: ["glyph.svg"] });
+    const appdir = mkdtempSync(join(tmpdir(), "nd-appdir-"));
+    await installLinuxIcon(identityWith({ layered: identity.icon!.layered, linux: "shine.png" }), appDir, appdir);
+    // The override is a PNG, so the flatten never ran and there is no scalable icon.
+    expect(existsSync(join(appdir, "usr/share/icons/hicolor/scalable/apps/fixture.svg"))).toBe(false);
+    expect(existsSync(join(appdir, "fixture.png"))).toBe(true);
+  });
+
+  test("a layered config flattens to the scalable icon plus the hicolor raster set", async () => {
+    const { appDir, identity } = layeredFixture({ background: { gradient: ["#0a84ff", "#5e5ce6"] }, layers: ["glyph.svg"] });
+    const appdir = mkdtempSync(join(tmpdir(), "nd-appdir-"));
+    await installLinuxIcon(identity, appDir, appdir);
+    expect(existsSync(join(appdir, "usr/share/icons/hicolor/scalable/apps/fixture.svg"))).toBe(true);
+    expect(existsSync(join(appdir, "usr/share/icons/hicolor/512x512/apps/fixture.png"))).toBe(true);
+    expect(existsSync(join(appdir, "usr/share/icons/hicolor/16x16/apps/fixture.png"))).toBe(true);
+    expect(existsSync(join(appdir, "fixture.svg"))).toBe(true);
+  });
+});
+
+const actool = process.platform === "darwin" && Bun.which("xcrun") !== null;
+
+describe.if(actool)("installMacIcon", () => {
+  test("a layered config compiles to Assets.car plus the legacy icns", async () => {
+    const { appDir, identity } = layeredFixture({ background: "#0a84ff", layers: ["glyph.svg"] });
+    const resources = mkdtempSync(join(tmpdir(), "nd-resources-"));
+    const iconFile = await installMacIcon(identity, appDir, resources, "26.0");
+    expect(iconFile).toBe("fixture");
+    expect(existsSync(join(resources, "Assets.car"))).toBe(true);
+    expect(readFileSync(join(resources, "fixture.icns")).subarray(0, 4).toString()).toBe("icns");
+  });
+
+  test("the macos override beats a layered composition", async () => {
+    const { appDir, identity } = layeredFixture({ background: "#0a84ff", layers: ["glyph.svg"] });
+    const prebuilt = mkdtempSync(join(tmpdir(), "nd-resources-"));
+    await installMacIcon(identityWith({ layered: identity.icon!.layered }), appDir, prebuilt, "26.0");
+    cpSync(join(prebuilt, "fixture.icns"), join(appDir, "brand.icns"));
+
+    const resources = mkdtempSync(join(tmpdir(), "nd-resources-"));
+    const iconFile = await installMacIcon(
+      identityWith({ layered: identity.icon!.layered, macos: "brand.icns" }),
+      appDir,
+      resources,
+      "26.0",
+    );
+    expect(iconFile).toBe("fixture");
+    // The override is a flat icns, so nothing was compiled through actool.
+    expect(existsSync(join(resources, "Assets.car"))).toBe(false);
+  });
+
+  test("an SVG source rasterizes into a flat icns", async () => {
+    const appDir = mkdtempSync(join(tmpdir(), "nd-flat-"));
+    writeFileSync(join(appDir, "icon.svg"), GLASS_SVG);
+    const resources = mkdtempSync(join(tmpdir(), "nd-resources-"));
+    const iconFile = await installMacIcon(identityWith({ source: "icon.svg" }), appDir, resources, "26.0");
+    expect(iconFile).toBe("fixture");
+    expect(readFileSync(join(resources, "fixture.icns")).subarray(0, 4).toString()).toBe("icns");
+    expect(existsSync(join(resources, "Assets.car"))).toBe(false);
+  });
+});

package/src/package/icons.ts

@@ -1,18 +1,22 @@
-// App icon installation. mac: .icns/.iconset passthrough or a PNG source
-// rasterized through sips + iconutil. linux: hicolor theme set + the AppDir
-// root icon appimagetool requires. Resizers are probed, never hard-required:
-// sips/iconutil are macOS-only tools, and a Linux box degrades with a marker.
-import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+// App icon installation. One source per platform is resolved from app.icon and
+// converted to whatever the platform actually reads: mac gets Assets.car +
+// .icns, linux gets the hicolor theme set plus the AppDir root icon
+// appimagetool requires. Resizers are probed, never hard-required: sips and
+// iconutil are macOS-only, and a Linux box degrades with a marker.
+import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { extname, join, resolve } from "node:path";
+import { basename, extname, join, resolve } from "node:path";
+import {
+  compileIconBundle,
+  composeSvg,
+  layeredComposition,
+  readIconBundle,
+  runTool,
+  writeIconBundle,
+} from "./iconcomposer.ts";
 import type { ResolvedIdentity } from "./identity.ts";
 import { PLACEHOLDER_PNG } from "./templates.ts";
 
-async function run(command: string[]): Promise<void> {
-  const proc = Bun.spawn(command, { stdin: "ignore", stdout: "inherit", stderr: "inherit" });
-  if (await proc.exited !== 0) throw new Error(`nd: icon tool failed (${command.join(" ")})`);
-}
-
 let warnedNoIcon = false;
 function warnNoIcon(): void {
   if (warnedNoIcon) return;
@@ -34,99 +38,171 @@ const ICONSET_SIZES: Array<{ file: string; px: number }> = [
   { file: "icon_512x512@2x.png", px: 1024 },
 ];
 
-/**
- * Installs the mac icon into Contents/Resources/<slug>.icns. Returns the
- * CFBundleIconFile value, or undefined when no icon is configured.
- */
-export async function installMacIcon(identity: ResolvedIdentity, appDir: string, resourcesDir: string): Promise<string | undefined> {
-  const source = identity.icon?.macos ?? identity.icon?.source;
-  if (!source) {
-    warnNoIcon();
-    return undefined;
-  }
-  const src = resolve(appDir, source);
-  const ext = extname(src).toLowerCase();
-  const icns = join(resourcesDir, `${identity.slug}.icns`);
-  if (ext === ".icns") {
-    cpSync(src, icns);
-  } else if (ext === ".iconset") {
-    await run(["iconutil", "-c", "icns", "-o", icns, src]);
-  } else if (ext === ".png") {
-    const tmp = mkdtempSync(join(tmpdir(), "nd-iconset-"));
-    const iconset = join(tmp, `${identity.slug}.iconset`);
-    mkdirSync(iconset, { recursive: true });
-    for (const { file, px } of ICONSET_SIZES) {
-      await run(["sips", "-z", String(px), String(px), src, "--out", join(iconset, file)]);
-    }
-    await run(["iconutil", "-c", "icns", "-o", icns, iconset]);
-    rmSync(tmp, { recursive: true, force: true });
-  } else if (ext === ".svg") {
-    throw new Error(
-      "nd: macOS cannot rasterize an SVG icon. Supply a 1024px PNG (app.icon.source) or a prebuilt .icns (app.icon.macos).",
-    );
-  } else {
-    throw new Error(`nd: unsupported mac icon source "${source}" (want .png, .icns, or .iconset)`);
-  }
-  return identity.slug;
-}
-
 const HICOLOR_SIZES = [16, 32, 48, 64, 128, 256, 512];
 
 function firstOnPath(candidates: string[]): string | undefined {
   return candidates.find((tool) => Bun.which(tool) !== null);
 }
 
-async function resizePng(tool: string, src: string, px: number, out: string): Promise<void> {
+async function resize(tool: string, src: string, px: number, out: string): Promise<void> {
   switch (tool) {
     case "sips":
-      await run(["sips", "-z", String(px), String(px), src, "--out", out]);
+      await runTool(["sips", "-z", String(px), String(px), src, "--out", out]);
       return;
     case "magick":
-      await run(["magick", src, "-resize", `${px}x${px}`, out]);
+      await runTool(["magick", src, "-resize", `${px}x${px}`, out]);
       return;
     case "convert":
-      await run(["convert", src, "-resize", `${px}x${px}`, out]);
+      await runTool(["convert", src, "-resize", `${px}x${px}`, out]);
       return;
     case "rsvg-convert":
-      await run(["rsvg-convert", "-w", String(px), "-h", String(px), "-o", out, src]);
+      await runTool(["rsvg-convert", "-w", String(px), "-h", String(px), "-o", out, src]);
       return;
     default:
       throw new Error(`nd: unknown icon resizer "${tool}"`);
   }
 }
 
+/**
+ * Rasterizes an SVG to a square PNG. qlmanage is the macOS fallback: it ships
+ * with the OS and renders through QuickLook, writing <name>.svg.png into the
+ * output directory.
+ */
+async function rasterizeSvg(src: string, px: number, workDir: string): Promise<string> {
+  const tool = firstOnPath(["rsvg-convert", "magick", "convert"]);
+  if (tool) {
+    const out = join(workDir, "source.png");
+    await resize(tool, src, px, out);
+    return out;
+  }
+  if (process.platform === "darwin") {
+    await runTool(["qlmanage", "-t", "-s", String(px), "-o", workDir, src]);
+    const rendered = join(workDir, `${basename(src)}.png`);
+    if (existsSync(rendered)) return rendered;
+  }
+  throw new Error(`nd: cannot rasterize "${src}" (install librsvg or ImageMagick, or supply a 1024px PNG)`);
+}
+
+/** PNG -> .icns through a generated .iconset. */
+async function buildIcns(src: string, icns: string, workDir: string): Promise<void> {
+  const iconset = join(workDir, `${basename(icns, ".icns")}.iconset`);
+  mkdirSync(iconset, { recursive: true });
+  for (const { file, px } of ICONSET_SIZES) {
+    await runTool(["sips", "-z", String(px), String(px), src, "--out", join(iconset, file)]);
+  }
+  await runTool(["iconutil", "-c", "icns", "-o", icns, iconset]);
+}
+
+/**
+ * Installs the mac icon into Contents/Resources. A layered source compiles to
+ * Assets.car (macOS 26 Liquid Glass) plus the .icns older releases fall back
+ * to; a flat source compiles to <slug>.icns only. Returns the
+ * CFBundleIconFile/CFBundleIconName value, or undefined when no icon is
+ * configured.
+ */
+export async function installMacIcon(
+  identity: ResolvedIdentity,
+  appDir: string,
+  resourcesDir: string,
+  deploymentTarget = "26.0",
+): Promise<string | undefined> {
+  const override = identity.icon?.macos;
+  // The explicit per-platform override wins outright. Failing that macOS
+  // prefers a layered composition over the shared flat source, because layered
+  // is its native format; Linux resolves the mirror of this.
+  const layered = override ? undefined : identity.icon?.layered;
+  const source = override ?? (layered ? undefined : identity.icon?.source);
+  if (!layered && !source) {
+    warnNoIcon();
+    return undefined;
+  }
+  const work = mkdtempSync(join(tmpdir(), "nd-icon-"));
+  try {
+    if (layered) {
+      const bundle = join(work, `${identity.slug}.icon`);
+      writeIconBundle(layered, appDir, bundle);
+      return await compileIconBundle(bundle, resourcesDir, deploymentTarget);
+    }
+    const src = resolve(appDir, source!);
+    const ext = extname(src).toLowerCase();
+    if (ext === ".icon") return await compileIconBundle(src, resourcesDir, deploymentTarget);
+    const icns = join(resourcesDir, `${identity.slug}.icns`);
+    switch (ext) {
+      case ".icns":
+        cpSync(src, icns);
+        break;
+      case ".iconset":
+        await runTool(["iconutil", "-c", "icns", "-o", icns, src]);
+        break;
+      case ".png":
+        await buildIcns(src, icns, work);
+        break;
+      case ".svg":
+        await buildIcns(await rasterizeSvg(src, 1024, work), icns, work);
+        break;
+      default:
+        throw new Error(`nd: unsupported mac icon source "${source}" (want .icon, .icns, .iconset, .png, or .svg)`);
+    }
+    return identity.slug;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
 /** Installs the linux icon set into the AppDir (hicolor theme + root icon). */
 export async function installLinuxIcon(identity: ResolvedIdentity, appDir: string, appdir: string): Promise<void> {
   const source = identity.icon?.linux ?? identity.icon?.source;
+  const layered = identity.icon?.layered;
   const rootIcon = join(appdir, `${identity.slug}.png`);
-  if (!source) {
+  if (!source && !layered) {
     warnNoIcon();
     writeFileSync(rootIcon, PLACEHOLDER_PNG);
     return;
   }
-  const src = resolve(appDir, source);
-  const ext = extname(src).toLowerCase();
-  if (ext === ".svg") {
-    const scalable = join(appdir, "usr/share/icons/hicolor/scalable/apps");
-    mkdirSync(scalable, { recursive: true });
-    cpSync(src, join(scalable, `${identity.slug}.svg`));
-    cpSync(src, join(appdir, `${identity.slug}.svg`));
-    return;
-  }
-  if (ext !== ".png") throw new Error(`nd: unsupported linux icon source "${source}" (want .png or .svg)`);
-  // rsvg-convert is deliberately absent: it only rasterizes SVGs and this
-  // branch always feeds it a PNG.
-  const resizer = firstOnPath(["sips", "magick", "convert"]);
-  if (!resizer) {
-    console.error("ND_PACKAGE_ICON_SKIPPED reason=no-resizer");
+  const work = mkdtempSync(join(tmpdir(), "nd-icon-"));
+  try {
+    let src = source ? resolve(appDir, source) : "";
+    let ext = src ? extname(src).toLowerCase() : "";
+    // A layered composition (config or an Icon Composer bundle) flattens to a
+    // single SVG so the same art dresses both platforms.
+    if (!src || ext === ".icon") {
+      const composition = src ? readIconBundle(src) : layeredComposition(layered!, appDir);
+      src = join(work, `${identity.slug}.svg`);
+      writeFileSync(src, composeSvg(composition.background, composition.layers));
+      ext = ".svg";
+    }
+    if (ext === ".svg") {
+      // Raster sizes first: a failed resizer clears the whole hicolor tree, and
+      // scalable/ is a complete install on its own, so it lands afterwards.
+      await installHicolor(identity, src, appdir, ["rsvg-convert", "magick", "convert"]);
+      const scalable = join(appdir, "usr/share/icons/hicolor/scalable/apps");
+      mkdirSync(scalable, { recursive: true });
+      cpSync(src, join(scalable, `${identity.slug}.svg`));
+      cpSync(src, join(appdir, `${identity.slug}.svg`));
+      return;
+    }
+    if (ext !== ".png") throw new Error(`nd: unsupported linux icon source "${source}" (want .png, .svg, or .icon)`);
+    // rsvg-convert is deliberately absent: it only rasterizes SVGs and this
+    // branch always feeds it a PNG.
+    if (!await installHicolor(identity, src, appdir, ["sips", "magick", "convert"])) {
+      console.error("ND_PACKAGE_ICON_SKIPPED reason=no-resizer");
+    }
     cpSync(src, rootIcon);
-    return;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
   }
+}
+
+/** Renders the hicolor raster set. Returns false when no resizer is installed,
+ * which the caller reports only when raster is the sole install path. */
+async function installHicolor(identity: ResolvedIdentity, src: string, appdir: string, tools: string[]): Promise<boolean> {
+  const resizer = firstOnPath(tools);
+  if (!resizer) return false;
   try {
     for (const px of HICOLOR_SIZES) {
       const dir = join(appdir, `usr/share/icons/hicolor/${px}x${px}/apps`);
       mkdirSync(dir, { recursive: true });
-      await resizePng(resizer, src, px, join(dir, `${identity.slug}.png`));
+      await resize(resizer, src, px, join(dir, `${identity.slug}.png`));
     }
   } catch (err) {
     // A broken resizer degrades like a missing one: drop the (possibly
@@ -135,5 +211,5 @@ export async function installLinuxIcon(identity: ResolvedIdentity, appDir: strin
     console.error(String(err));
     console.error("ND_PACKAGE_ICON_SKIPPED reason=resize-failed");
   }
-  cpSync(src, rootIcon);
+  return true;
 }

package/src/package/mac.ts

@@ -55,7 +55,7 @@ export async function packageMacApp(
   cpSync(bunPath, join(c, "MacOS", "bun"), { dereference: true });
   chmodSync(join(c, "MacOS", "bun"), 0o755);
 
-  const iconFile = await installMacIcon(identity, appDir, join(c, "Resources"));
+  const iconFile = await installMacIcon(identity, appDir, join(c, "Resources"), mac?.minimumSystemVersion ?? "26.0");
   const customXml = mac?.infoPlist ? readFileSync(resolve(appDir, mac.infoPlist), "utf8") : undefined;
   writeFileSync(join(c, "Info.plist"), buildInfoPlist(identity, mac, customXml, iconFile));