@bongos/core 1.18.0 → 1.18.18

package/modules/dev-box/app/scripts/apply-dmg-backdrop.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Re-package electron-builder's mac DMGs so the install-window backdrop renders
+# (task 1235). See scripts/dmgbuild-settings.py for the root cause: Finder on
+# macOS >= Sonoma can't resolve the `pBBk` bookmark electron-builder writes, so
+# its DMG shows a white window; dmgbuild's alias-only .DS_Store resolves and the
+# backdrop (task 912) draws.
+#
+# For each dist/<ProductSlug>-<ver>-<arch>.dmg this:
+#   1. mounts it read-only and copies the .app out with `ditto` (preserves the
+#      Developer ID signature + the stapled notarization ticket verbatim),
+#   2. rebuilds the DMG with dmgbuild + the on-brand backdrop,
+#   3. overwrites the original in place.
+# The .app is byte-identical, so it stays notarized; the DMG is an unsigned
+# carrier either way (verified: the published DMGs were never DMG-signed, only
+# the app inside is). dmgbuild needs no GUI/Finder, so this is CI-safe (headless).
+#
+# Run from the devbox-app/ directory:  bash scripts/apply-dmg-backdrop.sh [distDir]
+set -euo pipefail
+
+DIST="${1:-dist}"
+RES="build-resources"
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+if [ ! -f "$RES/dmg-background.png" ] || [ ! -f "$RES/dmg-background@2x.png" ]; then
+  echo "ERROR: backdrop art missing in $RES (run scripts/gen-dmg-backdrop.py)" >&2
+  exit 1
+fi
+
+# Crisp on Retina: fold the 1x + 2x PNGs into a single multi-rep hidpi TIFF.
+tiffutil -cathidpicheck "$RES/dmg-background.png" "$RES/dmg-background@2x.png" \
+  -out "$WORK/backdrop.tiff" >/dev/null
+
+# Isolated, headless dmgbuild (writes .DS_Store directly; no Finder dependency).
+python3 -m venv "$WORK/venv"
+"$WORK/venv/bin/pip" install --quiet --disable-pip-version-check dmgbuild
+
+# Brand comes from the generated brand (ADR 0145) so this re-packages whatever
+# the branding-driven build produced — Cloud-Bongos-Dev-Box-*.dmg here, any
+# instance's slug elsewhere — never a hardcoded product name.
+SLUG="$(python3 -c 'import json;print(json.load(open("src/brand.generated.json"))["PRODUCT_SLUG"])')"
+PNAME="$(python3 -c 'import json;print(json.load(open("src/brand.generated.json"))["PRODUCT_NAME"])')"
+
+shopt -s nullglob
+count=0
+for DMG in "$DIST"/"$SLUG"-*.dmg; do
+  base="$(basename "$DMG" .dmg)"             # e.g. Cloud-Bongos-Dev-Box-1.0.10-arm64
+  suffix="${base#"$SLUG"-}"                  # e.g. 1.0.10-arm64
+  volname="$PNAME $suffix"                   # e.g. Cloud Bongos Dev Box 1.0.10-arm64
+
+  mnt="$WORK/mnt-$suffix"
+  mkdir -p "$mnt"
+  hdiutil attach "$DMG" -nobrowse -readonly -mountpoint "$mnt" -owners off >/dev/null
+
+  app="$(/bin/ls -d "$mnt"/*.app 2>/dev/null | head -1)"
+  if [ -z "$app" ]; then
+    echo "ERROR: no .app inside $DMG" >&2
+    hdiutil detach "$mnt" >/dev/null 2>&1 || true
+    exit 1
+  fi
+  appname="$(basename "$app")"
+  ditto "$app" "$WORK/$appname"
+  hdiutil detach "$mnt" >/dev/null
+
+  out="$WORK/out-$suffix.dmg"
+  "$WORK/venv/bin/dmgbuild" \
+    -s scripts/dmgbuild-settings.py \
+    -D app="$WORK/$appname" \
+    -D bg="$WORK/backdrop.tiff" \
+    "$volname" "$out" >/dev/null
+
+  mv -f "$out" "$DMG"
+  rm -rf "$WORK/$appname"
+  echo "  backdrop applied: $(basename "$DMG")  (volume \"$volname\")"
+  count=$((count + 1))
+done
+
+if [ "$count" -eq 0 ]; then
+  echo "ERROR: no ${SLUG}-*.dmg found in $DIST" >&2
+  exit 1
+fi
+echo "Re-packaged $count DMG(s) with the install-window backdrop."

package/modules/dev-box/app/scripts/dmgbuild-settings.py

@@ -0,0 +1,39 @@
+# dmgbuild settings for the OTB Dev Box install window (task 1235).
+#
+# WHY dmgbuild and not electron-builder's own DMG styling:
+# electron-builder writes a .DS_Store whose background reference includes a
+# modern security-scoped bookmark (`pBBk`). Finder on macOS >= Sonoma/Sequoia
+# (verified white on 15.7.4) cannot resolve that bookmark, so it falls back to a
+# solid white window — the embedded Greek-coast backdrop (task 912) is present
+# but never drawn. dmgbuild writes an alias-only `.DS_Store` (no `pBBk`) that
+# Finder DOES resolve, so the backdrop renders. The OS is not the problem; the
+# bookmark electron-builder emits is. scripts/apply-dmg-backdrop.sh re-packages
+# electron-builder's signed+notarized .app into a dmgbuild DMG using this file.
+#
+# Coordinates MUST match the icon-well centers drawn by gen-dmg-backdrop.py
+# (LEFT 180,198 / RIGHT 480,198) and the 660x400 art — change one, change all.
+# `app` and `bg` are passed in via dmgbuild -D defines.
+
+import os.path
+
+# -D app=<path to OTB Dev Box.app>  -D bg=<path to the hidpi backdrop tiff>
+application = defines["app"]
+backdrop = defines["bg"]
+appname = os.path.basename(application)  # "OTB Dev Box.app"
+
+# Contents of the disk image.
+files = [application]
+symlinks = {"Applications": "/Applications"}
+
+# Window + icon layout — matched to the backdrop art's two marble wells.
+background = backdrop
+window_rect = ((150, 150), (660, 400))  # ((x, y), (w, h)); w/h match the 660x400 art
+icon_size = 100
+text_size = 12
+icon_locations = {
+    appname: (180, 198),       # the container (app) — left well
+    "Applications": (480, 198),  # Applications — right well
+}
+
+# Compressed, read-only final image (same distribution format as before).
+format = "UDZO"

package/modules/dev-box/app/scripts/gen-brand.js

@@ -0,0 +1,138 @@
+// modules/dev-box/app/scripts/gen-brand.js — make the Dev Box app branding-driven.
+//
+// The app is a self-contained Electron subproject (ADR 0045) built separately
+// from the server, so it can't read the instance branding at runtime. Instead
+// this reads the instance's config/branding.json (the SAME contract the server
+// resolves — docs/branding-contract.md) at BUILD time and emits three generated
+// artifacts the app + electron-builder consume:
+//
+//   src/brand.generated.json     — every user-visible string + appId/slug/colors
+//   renderer/theme.generated.css — the :root design tokens (palette + fonts)
+//   electron-builder.yml         — rendered from electron-builder.tmpl.yml
+//
+// So ONE source tree builds a "Cloud Bongos Dev Box" here and an "Amazonprimea
+// Dev Box" on the OTB instance — the brand is a build input, not baked into code
+// (the ADR 0004 posture, generalised: no instance's name is hardcoded anywhere).
+//
+// Run: npm run gen-brand  (also invoked before start / test / dist:*).
+// Resolution: BONGOS_BRANDING_FILE env → <repoRoot>/config/branding.json →
+//             <repoRoot>/config/branding.neutral.json (the Cloud Bongos pack).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const APP_DIR = path.resolve(__dirname, '..');          // modules/dev-box/app
+const REPO_ROOT = path.resolve(APP_DIR, '..', '..', '..'); // repo root (…/app → …/dev-box → …/modules → root)
+
+function readBranding() {
+  const candidates = [
+    process.env.BONGOS_BRANDING_FILE,
+    path.join(REPO_ROOT, 'config', 'branding.json'),
+    path.join(REPO_ROOT, 'config', 'branding.neutral.json'),
+  ].filter(Boolean);
+  for (const f of candidates) {
+    try {
+      const b = JSON.parse(fs.readFileSync(f, 'utf8'));
+      return { file: f, branding: b };
+    } catch { /* try next */ }
+  }
+  throw new Error('gen-brand: no branding file found (looked for config/branding.json, config/branding.neutral.json)');
+}
+
+// "Cloud Bongos" → "cloudbongos" (appId segment); "Cloud Bongos Dev Box" →
+// "Cloud-Bongos-Dev-Box" (artifact filename — no spaces, ADR 0004).
+const idSlug = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '') || 'instance';
+const fileSlug = (s) => String(s || '').trim().replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'Dev-Box';
+
+function buildBrand(branding) {
+  const id = branding.identity || {};
+  const dom = branding.domains || {};
+  const ui = (branding.theme && branding.theme.ui) || {};
+  const colors = ui.colors || {};
+  const world = id.worldName || id.productName || 'Cloud Bongos';
+  const company = (id.company && id.company.name) || world;
+  const productName = `${world} Dev Box`;
+  return {
+    // Rendered-at-runtime display strings (brand.js re-exports these).
+    CIV_NAME: world,
+    PRODUCT_NAME: productName,
+    DESKTOP_ENV_NAME: productName,
+    // Origins the built app pairs against. A release BUILD overrides these via
+    // env (DEVBOX_PUBLIC_ORIGIN/_BUILDERS_ORIGIN — set from CI repo variables)
+    // so the neutral core stays neutral (localhost) yet a cloudbongos.com build
+    // bakes cloudbongos.com — without committing a host origin to the core.
+    PUBLIC_ORIGIN: process.env.DEVBOX_PUBLIC_ORIGIN || dom.publicOrigin || 'http://localhost:3000',
+    BUILDERS_ORIGIN: process.env.DEVBOX_BUILDERS_ORIGIN || dom.buildersOrigin || dom.publicOrigin || 'http://localhost:3000',
+    // Build + packaging inputs.
+    PRODUCT_SLUG: fileSlug(productName),
+    APP_ID: `com.${idSlug(world)}.devbox`,
+    COPYRIGHT: `© ${company}`,
+    // Local integration: match the instance's CLI config dir so pairing the app
+    // also signs in the /builder-* CLI on this machine (session-store.js).
+    CONFIG_DIR: branding.configDir || 'cloudbongos',
+    // Panel header epigraph (branding copy.tagline).
+    TAGLINE: (branding.copy && branding.copy.tagline) || '',
+    // Pre-CSS window background (main.js) — the theme bg so first paint is on-brand.
+    BG_COLOR: colors.bg || '#ffffff',
+  };
+}
+
+// The renderer :root tokens — mirror renderer/styles.css var names.
+function buildThemeCss(branding) {
+  const ui = (branding.theme && branding.theme.ui) || {};
+  const c = ui.colors || {};
+  const fonts = ui.fonts || {};
+  const v = (x, fb) => x || fb;
+  return `/* GENERATED by scripts/gen-brand.js from config/branding.json — do not edit by hand. */
+:root {
+  --bg: ${v(c.bg, '#fff7ed')};
+  --bg-card: ${v(c.bgCard, '#ffffff')};
+  --bg-deep: ${v(c.bgDeep, '#ffedd5')};
+  --ink: ${v(c.ink, '#2a1f17')};
+  --ink-soft: ${v(c.inkSoft, '#6b5d52')};
+  --ink-faint: ${v(c.inkFaint, '#857567')};
+  --rule: ${v(c.rule, '#fdba74')};
+  --rule-soft: ${v(c.ruleSoft, '#fed7aa')};
+  --accent: ${v(c.accent, '#f97316')};
+  --accent-deep: ${v(c.accentDeep, '#ea580c')};
+  --terracotta: ${v(c.terracotta, '#fb7185')};
+  --font-display: ${v(fonts.display, '"Baloo 2", "Quicksand", system-ui, sans-serif')};
+  --font-body: ${v(fonts.body, '"Quicksand", system-ui, -apple-system, "Segoe UI", sans-serif')};
+}
+`;
+}
+
+function renderElectronBuilder(brand) {
+  const tmplPath = path.join(APP_DIR, 'electron-builder.tmpl.yml');
+  const tmpl = fs.readFileSync(tmplPath, 'utf8');
+  return tmpl
+    .replace(/@@APP_ID@@/g, brand.APP_ID)
+    .replace(/@@PRODUCT_NAME@@/g, brand.PRODUCT_NAME)
+    .replace(/@@COPYRIGHT@@/g, brand.COPYRIGHT)
+    .replace(/@@PRODUCT_SLUG@@/g, brand.PRODUCT_SLUG);
+}
+
+function main() {
+  const { file, branding } = readBranding();
+  const brand = buildBrand(branding);
+
+  const brandOut = path.join(APP_DIR, 'src', 'brand.generated.json');
+  fs.writeFileSync(brandOut, `${JSON.stringify(brand, null, 2)}\n`);
+
+  const themeOut = path.join(APP_DIR, 'renderer', 'theme.generated.css');
+  fs.writeFileSync(themeOut, buildThemeCss(branding));
+
+  const ebOut = path.join(APP_DIR, 'electron-builder.yml');
+  fs.writeFileSync(ebOut, renderElectronBuilder(brand));
+
+  const rel = (p) => path.relative(REPO_ROOT, p);
+  console.log(`gen-brand: ${brand.PRODUCT_NAME} (${brand.APP_ID}) ← ${rel(file)}`);
+  console.log(`  wrote ${rel(brandOut)}, ${rel(themeOut)}, ${rel(ebOut)}`);
+}
+
+if (require.main === module) main();
+
+// Exported so a test can call the PURE builders (tests/devbox_installer_brand.mjs
+// gates the committed artifacts against them). Importing must never write —
+// hence the require.main guard above.
+module.exports = { readBranding, buildBrand, buildThemeCss, renderElectronBuilder, main };

package/modules/dev-box/app/scripts/gen-dmg-backdrop.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""Draw the DMG install-window backdrop from the INSTANCE BRANDING (task 912, 1002372).
+
+The Mac .dmg install window shows two icons — the app on the left and an
+Applications-folder alias on the right — and the user drags one onto the other.
+This draws the Finder-window BACKDROP behind that gesture.
+
+Branding is a BUILD INPUT, not baked in — the same posture gen-brand.js already
+holds for the app's strings (ADR 0145). The palette comes from the pack's
+`theme.ui.colors`, the headline names the product the build actually ships, the
+subhead is the pack's tagline, and the type is the pack's own font stack. So ONE
+source tree renders the vanilla Cloud Bongos sunrise here and a host instance's
+palette + voice there: no hex, motif, or sentence belongs to a single brand.
+
+ONE source, resolved exactly as gen-brand.js resolves it (docs/branding-contract.md):
+    BONGOS_BRANDING_FILE → config/branding.json → config/branding.neutral.json
+Palette, type, product name and tagline all come from that file, so a render can
+never mix one pack's colours with another's words.
+
+A pack that wants different words states them outright as `copy.dmgHeadline` /
+`copy.dmgSubhead`; otherwise both lines are derived, so a new instance needs no
+extra config to get a correct install screen.
+
+Draws DIRECTLY with Pillow (no SVG renderer needed in CI/headless) and
+supersamples 2x then LANCZOS-downscales so text + edges read crisply at Retina.
+Outputs:
+    build-resources/dmg-background.png      660x400  (@1x)
+    build-resources/dmg-background@2x.png  1320x800  (@2x; electron-builder auto-picks)
+
+The icon SLOTS are left clear — electron-builder / dmgbuild place the real app +
+Applications icons over them at the coords mirrored in scripts/dmgbuild-settings.py;
+this art only draws the guidance AROUND them (wells, the beat line, copy).
+
+Pillow is an ad-hoc dependency: the repo declares no Python manifest (the sibling
+scripts/apply-dmg-backdrop.sh installs its own `dmgbuild` the same way), so run
+this from a throwaway venv with `pip install Pillow`.
+
+Run:  python3 modules/dev-box/app/scripts/gen-dmg-backdrop.py
+Re-run after any branding/layout/copy change; commit the two PNGs. Text renders in
+the first face of the pack's stack that is INSTALLED on the rendering machine, so
+a re-render on a different OS may substitute a different fallback face.
+"""
+from __future__ import annotations  # `X | None` hints must not run on macOS's system python 3.9
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Union
+
+from PIL import Image, ImageDraw, ImageFont
+
+RGB = tuple[int, int, int]
+Face = Union[ImageFont.FreeTypeFont, ImageFont.ImageFont]  # a truetype face, or Pillow's built-in
+
+APP_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # modules/dev-box/app
+REPO_ROOT = os.path.abspath(os.path.join(APP_DIR, "..", "..", ".."))
+
+W, H = 660, 400            # the DMG window size (must match electron-builder.yml dmg.window)
+SS = 2                     # supersample factor for crisp anti-aliased output
+LEFT = (180, 198)          # app-icon slot center (matches dmg.contents[0])
+RIGHT = (480, 198)         # Applications slot center (matches dmg.contents[1])
+ICON = 100                 # dmg.iconSize
+
+# theme.ui.colors keys → the roles this art draws, with the neutral pack's values
+# as fallbacks so a partial instance pack still renders something coherent.
+# Every role here MUST be one the app's own brand surface emits (gen-brand.js's
+# buildThemeCss) — a role outside it has nothing prompting a host pack to define
+# it, so its "fallback" would paint a Cloud Bongos colour into a fully-specified
+# host build. That is exactly what `sea` did to the Applications-well rim.
+COLOR_ROLES = {
+    "bg": "#fff7ed", "bgDeep": "#ffedd5", "bgCard": "#ffffff",
+    "ink": "#2a1f17", "inkSoft": "#6b5d52", "ruleSoft": "#fed7aa",
+    "accent": "#f97316", "accentDeep": "#ea580c", "terracotta": "#fb7185",
+}
+
+FONT_DIRS = (
+    "/System/Library/Fonts/Supplemental", "/Library/Fonts", "/System/Library/Fonts",
+    os.path.join(os.environ.get("WINDIR", "C:/Windows"), "Fonts"),
+    "/usr/share/fonts/truetype/dejavu",
+)
+# Tried only when none of the pack's own families is installed — a web-font stack
+# ("Baloo 2", "Quicksand") usually isn't present on the machine doing the render.
+GENERIC_BOLD = ("Arial Bold.ttf", "Helvetica.ttc", "segoeuib.ttf", "arialbd.ttf", "DejaVuSans-Bold.ttf")
+GENERIC_REGULAR = ("Arial.ttf", "Helvetica.ttc", "segoeui.ttf", "arial.ttf", "DejaVuSans.ttf")
+# CSS keywords name no file, so they fall through to the generic faces above.
+CSS_GENERIC_FAMILIES = {"system-ui", "-apple-system", "sans-serif", "serif", "monospace", "ui-sans-serif"}
+
+
+@dataclass(frozen=True)
+class Art:
+    """Everything the render pulls from the instance pack — resolved once, then drawn."""
+    palette: dict[str, RGB]
+    headline: str
+    subhead: str
+    display_stack: str
+    body_stack: str
+
+
+def read_json(path: str) -> dict | None:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return json.load(fh)
+    except (OSError, ValueError):
+        return None
+
+
+def read_branding() -> dict:
+    """The pack, resolved exactly as gen-brand.js resolves it (env → instance → neutral)."""
+    for path in (os.environ.get("BONGOS_BRANDING_FILE"),
+                 os.path.join(REPO_ROOT, "config", "branding.json"),
+                 os.path.join(REPO_ROOT, "config", "branding.neutral.json")):
+        pack = read_json(path) if path else None
+        if pack is not None:
+            return pack
+    raise SystemExit("gen-dmg-backdrop: no branding pack found (is config/branding.neutral.json missing?)")
+
+
+def brand_strings(branding: dict) -> dict:
+    """Product name + tagline, derived from the resolved pack exactly as gen-brand.js's
+    buildBrand derives them (`<worldName> Dev Box`, `copy.tagline`).
+
+    Deliberately NOT read out of gen-brand.js's src/brand.generated.json, which carries
+    the same two fields: that artifact is COMMITTED holding the neutral values and
+    nothing on this path regenerates it, so preferring it would let a stale checked-in
+    file outrank the host's own pack — the render would draw the host palette and type
+    under the neutral product's name. The pack decides, every time."""
+    identity = branding.get("identity") or {}
+    world = identity.get("worldName") or identity.get("productName") or "Cloud Bongos"
+    return {
+        "product": f"{world} Dev Box",
+        "tagline": (branding.get("copy") or {}).get("tagline") or "",
+    }
+
+
+def copy_lines(branding: dict, brand: dict) -> tuple[str, str]:
+    """Headline + subhead. Derived from the instance's own name and tagline; a pack
+    whose voice needs different words states them as copy.dmgHeadline/dmgSubhead."""
+    copy = branding.get("copy") or {}
+    headline = copy.get("dmgHeadline") or f"Drag {brand['product']} to Applications"
+    subhead = copy.get("dmgSubhead")
+    return headline, brand["tagline"] if subhead is None else subhead
+
+
+def hexrgb(value: str | None, fallback: str) -> RGB:
+    """A pack colour, or the neutral fallback when the pack omits it or writes junk —
+    one malformed hex must not abort a build over a decorative backdrop."""
+    for candidate in (value, fallback):
+        raw = str(candidate or "").lstrip("#")
+        if len(raw) == 3:
+            raw = "".join(c * 2 for c in raw)
+        if len(raw) == 6:
+            try:
+                return (int(raw[0:2], 16), int(raw[2:4], 16), int(raw[4:6], 16))
+            except ValueError:
+                continue
+    return (0, 0, 0)
+
+
+def palette(branding: dict) -> dict[str, RGB]:
+    ui = (branding.get("theme") or {}).get("ui") or {}
+    colors = ui.get("colors") or {}
+    return {role: hexrgb(colors.get(role), fallback) for role, fallback in COLOR_ROLES.items()}
+
+
+def font_files(stack: str, bold: bool) -> list[str]:
+    """A CSS family stack → font FILENAMES to try, in the pack's own preference order.
+    Covers both the macOS ("Georgia Bold.ttf") and Windows ("georgiab.ttf") naming."""
+    names: list[str] = []
+    for raw in str(stack or "").split(","):
+        family = raw.strip().strip("\"'")
+        if not family or family in CSS_GENERIC_FAMILIES:
+            continue
+        flat = family.replace(" ", "").lower()
+        if bold:
+            names += [f"{family} Bold.ttf", f"{flat}b.ttf", f"{flat}bd.ttf"]
+        names += [f"{family}.ttf", f"{flat}.ttf"]
+    return names + list(GENERIC_BOLD if bold else GENERIC_REGULAR)
+
+
+def font(stack: str, size: int, bold: bool = False) -> Face:
+    for name in font_files(stack, bold):
+        for directory in FONT_DIRS:
+            path = os.path.join(directory, name)
+            if os.path.exists(path):
+                return ImageFont.truetype(path, size)
+    return ImageFont.load_default(size)
+
+
+def lerp(a: RGB, b: RGB, t: float) -> RGB:
+    return tuple(round(a[i] + (b[i] - a[i]) * t) for i in range(3))
+
+
+def vgradient(draw: ImageDraw.ImageDraw, x0: int, y0: int, x1: int, y1: int, c_top: RGB, c_bot: RGB) -> None:
+    h = max(1, y1 - y0)
+    for y in range(y0, y1):
+        draw.line([(x0, y), (x1, y)], fill=lerp(c_top, c_bot, (y - y0) / h))
+
+
+def text_width(draw: ImageDraw.ImageDraw, text: str, fnt: Face) -> float:
+    left, _, right, _ = draw.textbbox((0, 0), text, font=fnt)
+    return right - left
+
+
+def centered(draw: ImageDraw.ImageDraw, cx: float, y: float, text: str,
+             fnt: Face, fill: RGB) -> None:
+    draw.text((cx - text_width(draw, text, fnt) / 2, y), text, font=fnt, fill=fill)
+
+
+def fitted_font(draw: ImageDraw.ImageDraw, text: str, stack: str, size: int, max_w: float) -> Face:
+    """Shrink the headline until it fits — an instance's product name is arbitrary
+    length, and a name that runs off the 660px art would ship a broken installer."""
+    fnt = font(stack, size, bold=True)
+    while size > 12 and text_width(draw, text, fnt) > max_w:
+        size -= 1
+        fnt = font(stack, size, bold=True)
+    return fnt
+
+
+def cloud_band(draw: ImageDraw.ImageDraw, base_y: float, scale: int, fill: RGB) -> None:
+    # A soft cloud shelf across the foot: a flat fill topped by overlapping discs,
+    # so the band reads as one puffy silhouette and grounds the two icon wells.
+    y = base_y * scale
+    draw.rectangle([0, y, W * scale, H * scale], fill=fill)
+    x = -12.0 * scale
+    i = 0
+    while x < (W + 40) * scale:
+        r = (11 + 5 * ((i * 3) % 4)) * scale
+        draw.ellipse([x - r, y - r, x + r, y + r], fill=fill)
+        x += r * 1.15
+        i += 1
+
+
+def bongo_mark(draw: ImageDraw.ImageDraw, center: tuple[float, float], scale: int,
+               big: RGB, small: RGB, head: RGB) -> None:
+    # The mark: a drum pair seen from above, mirroring the neutral pack's favicon
+    # geometry but coloured FROM the resolved pack — so it recolours per instance
+    # rather than stamping one brand's emblem into every build.
+    cx, cy = center[0] * scale, center[1] * scale
+    for dx, radius, body in ((-8.0, 13.0, big), (9.0, 10.0, small)):
+        x = cx + dx * scale
+        r = radius * scale
+        draw.ellipse([x - r, cy - r, x + r, cy + r], fill=body)
+        inner = r * 0.44
+        draw.ellipse([x - inner, cy - inner, x + inner, cy + inner], fill=head)
+
+
+def well(draw: ImageDraw.ImageDraw, center: tuple[int, int], scale: int, face: RGB, rim: RGB) -> None:
+    # A soft raised disc the icon sits on — a filled card with concentric rings
+    # fading into it, so the placed icon reads as resting ON the surface.
+    cx, cy = center[0] * scale, center[1] * scale
+    rad = (ICON / 2 + 18) * scale
+    draw.ellipse([cx - rad, cy - rad, cx + rad, cy + rad], fill=face)
+    for i in range(6):
+        r = rad - i * 1.6 * scale
+        draw.ellipse([cx - r, cy - r, cx + r, cy + r], outline=lerp(rim, face, i / 5),
+                     width=max(1, int(1.5 * scale)))
+
+
+def beat_line(draw: ImageDraw.ImageDraw, p0: tuple[float, float], p1: tuple[float, float],
+              scale: int, dot: RGB, tip: RGB) -> None:
+    # The drag guidance: beats swelling toward a chevron. Direction without a
+    # world-specific motif — it reads the same whatever the instance is building.
+    x0, y0 = p0[0] * scale, p0[1] * scale
+    x1, y1 = p1[0] * scale, p1[1] * scale
+    beats = 6
+    for i in range(beats):
+        t = i / (beats - 1)
+        x, y = x0 + (x1 - x0) * t, y0 + (y1 - y0) * t
+        r = (2.0 + 2.4 * t) * scale
+        draw.ellipse([x - r, y - r, x + r, y + r], fill=dot)
+    a = 12 * scale
+    draw.polygon([(x1 + a * 1.5, y1), (x1 + a * 0.2, y1 - a * 0.8), (x1 + a * 0.2, y1 + a * 0.8)], fill=tip)
+
+
+def render(scale: int, art: Art) -> Image.Image:
+    p = art.palette
+    img = Image.new("RGB", (W * scale, H * scale), p["bg"])
+    d = ImageDraw.Draw(img)
+    # the pack's field: its deep tint at the top easing into its base tone
+    vgradient(d, 0, 0, W * scale, H * scale, p["bgDeep"], p["bg"])
+    cloud_band(d, 344, scale, p["bgCard"])
+    bongo_mark(d, (W / 2, 34), scale, p["accent"], p["terracotta"], p["bg"])
+    centered(d, W * scale / 2, int(56 * scale), art.headline,
+             fitted_font(d, art.headline, art.display_stack, int(25 * scale), (W - 72) * scale), p["ink"])
+    if art.subhead:
+        centered(d, W * scale / 2, int(94 * scale), art.subhead,
+                 font(art.body_stack, int(13 * scale)), p["inkSoft"])
+    # Wells + guidance. The destination rim takes the pack's accent — the same tone
+    # the beats arrive in — so the drop target is distinguishable from the source's
+    # soft rule at a glance.
+    well(d, LEFT, scale, p["bgCard"], p["ruleSoft"])
+    well(d, RIGHT, scale, p["bgCard"], p["accent"])
+    beat_line(d, (LEFT[0] + ICON / 2 + 24, LEFT[1]), (RIGHT[0] - ICON / 2 - 36, RIGHT[1]),
+              scale, p["accent"], p["accentDeep"])
+    # NB: no under-slot labels — Finder renders each icon's own name beneath it,
+    # so drawing our own would double them.
+    return img
+
+
+def main() -> None:
+    branding = read_branding()
+    brand = brand_strings(branding)
+    headline, subhead = copy_lines(branding, brand)
+    fonts = ((branding.get("theme") or {}).get("ui") or {}).get("fonts") or {}
+    art = Art(
+        palette=palette(branding),
+        headline=headline,
+        subhead=subhead,
+        display_stack=fonts.get("display") or "",
+        body_stack=fonts.get("body") or "",
+    )
+
+    out_dir = os.path.join(APP_DIR, "build-resources")
+    # @1x: render at SS then downscale for anti-aliasing.
+    render(SS, art).resize((W, H), Image.LANCZOS).save(os.path.join(out_dir, "dmg-background.png"))
+    # @2x: native double-size canvas (so it is genuinely 2x detail), supersampled.
+    render(SS * 2, art).resize((W * 2, H * 2), Image.LANCZOS).save(os.path.join(out_dir, "dmg-background@2x.png"))
+    print(f'gen-dmg-backdrop: "{headline}" / "{subhead}"')
+    print(f"  wrote {out_dir}/dmg-background.png ({W}x{H}) + dmg-background@2x.png ({W * 2}x{H * 2})")
+
+
+if __name__ == "__main__":
+    main()