diff --git a/docs/giza-app-icon.md b/docs/giza-app-icon.md
index 7e959896..05d898fb 100644
--- a/docs/giza-app-icon.md
+++ b/docs/giza-app-icon.md
@@ -246,7 +246,7 @@ dock and ⌘-Tab. `packageDeb` can be checked on this machine; the `.dmg` and `.
| phase | state |
|---|---|
| 0 | done. `giza` merged in (`a4f54ad4`, Android's icon). The master is `docs/brand/giza-sphinx.svg`, the designer's *Transparent Cutouts* file unchanged; its path equals the `pathData` of both `ic_launcher_foreground.xml` and `ic_launcher_monochrome.xml`, 1,567 characters each. Baseline at `e00d0f80`: `jvmTest` 1,407 run, 0 failed, 0 skipped; `m3Audit` all budgets met, adaptive APIs 12 (floor 12), navigation components 2 (floor 2). Measuring the path also showed its thirteen sub-paths are disjoint, so the fill rule is not load-bearing; the facts above say so |
-| 1 | not started |
+| 1 | done. `docs/scripts/app-icons.py`, with `--only ios|desktop|xml`, `--root` (to write somewhere other than the tree) and `--sheet`. Run twice into two scratch roots it wrote byte-identical files. The light icon is RGB with no alpha, the dark RGBA, the tinted grayscale; the `.ico` holds eight entries, 256 as PNG; the `.icns` parses as eight PNG chunks, `ic07`–`ic14`, with the sizes the table names. The contact sheet left 0.68 and 0.80 as they were: the stripes stay apart down to 32 px and merge, as expected, at 16 |
| 2 | not started |
| 3 | not started |
| 4 | not started |
diff --git a/docs/scripts/app-icons.py b/docs/scripts/app-icons.py
new file mode 100755
index 00000000..3ad62190
--- /dev/null
+++ b/docs/scripts/app-icons.py
@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""Render every app icon outside Android from the one master SVG.
+
+The master is docs/brand/giza-sphinx.svg: the sphinx as one evenodd path in sand, with
+nothing behind it. Android's launcher layers carry the same path (docs/giza-app-icon.md,
+Phase 0), and everything written here is that path, the sand, and one background colour,
+composed per platform:
+
+ ios iosApp/iosApp/Assets.xcassets/AppIcon.appiconset/AppIcon-{light,dark,tinted}.png
+ desktop composeApp/desktop-icons/giza.{icns,ico,png}
+ xml composeApp/src/commonMain/composeResources/drawable/compose-multiplatform.xml
+
+Needs Python 3 and ImageMagick's `convert` (6 or 7) and `montage` (for --sheet). Nothing
+else: ImageMagick's own SVG renderer draws the master correctly, and the .icns is written
+here because `iconutil` exists only on macOS.
+
+The output is deterministic -- PNGs are written without their date and time chunks -- so a
+second run over an unchanged master leaves the tree clean.
+
+Usage: app-icons.py [--only ios|desktop|xml ...] [--root DIR] [--sheet FILE]
+
+ --root where to write, as a repository root (default: this repository). Point it at a
+ scratch directory to look at the output without touching the tree.
+ --sheet also write a contact sheet of every output at the sizes it is shown at.
+"""
+import argparse, os, re, shutil, struct, subprocess, sys, tempfile
+
+REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
+MASTER = os.path.join(REPO, 'docs', 'brand', 'giza-sphinx.svg')
+
+# The brand's two colours (docs/giza-app-icon.md, I1). BACKGROUND is Android's launcher
+# background, #000000; the designer's files use #080A09, eight steps away.
+SAND = '#D2AB5E'
+BACKGROUND = '#000000'
+
+# The art's bounding box in the 1024 viewport is x 122-901, y 89-939, so its centre is here.
+# Scaling about it keeps the mark where the eye expects it on a plate.
+ART_CENTRE = (511.5, 514.0)
+
+# macOS: Apple's Big Sur grid, an 824 px rounded square centred in 1024 (I3).
+MAC_PLATE, MAC_RADIUS, MAC_ART = 824, 185, 0.68
+# Windows and Linux: a plate filling the canvas, gently rounded.
+DESK_RADIUS, DESK_ART = 123, 0.80
+
+IOS_DIR = os.path.join('iosApp', 'iosApp', 'Assets.xcassets', 'AppIcon.appiconset')
+DESK_DIR = os.path.join('composeApp', 'desktop-icons')
+XML_PATH = os.path.join('composeApp', 'src', 'commonMain', 'composeResources', 'drawable',
+ 'compose-multiplatform.xml')
+
+ICO_SIZES = [256, 64, 48, 40, 32, 24, 20, 16]
+# ICNS chunk types with PNG payloads, and the pixel size of each.
+ICNS_CHUNKS = [(b'ic07', 128), (b'ic08', 256), (b'ic09', 512), (b'ic10', 1024),
+ (b'ic11', 32), (b'ic12', 64), (b'ic13', 256), (b'ic14', 512)]
+
+# Written without timestamps, so reruns are byte-identical.
+PNG_STABLE = ['-strip', '-define', 'png:exclude-chunks=date,time']
+
+
+def master_path():
+ svg = open(MASTER, encoding='utf-8').read()
+ m = re.search(r'\sd="([^"]+)"', svg)
+ if not m or 'evenodd' not in svg:
+ sys.exit(f'{MASTER}: expected one path with fill-rule="evenodd"')
+ return m.group(1)
+
+
+def art(d, fill, scale=1.0):
+ if scale == 1.0:
+ transform = ''
+ else:
+ cx, cy = ART_CENTRE
+ transform = (f' transform="translate({512 - scale * cx:.4f} {512 - scale * cy:.4f})'
+ f' scale({scale})"')
+ return f''
+
+
+def svg(*body):
+ return ('')
+
+
+def plate(size, radius):
+ o = (1024 - size) / 2
+ return (f'')
+
+
+def convert(*args):
+ subprocess.run(['convert', *args], check=True)
+
+
+def render(tmp, name, document):
+ """Rasterise an SVG document to a 1024 RGBA PNG and return its path."""
+ src = os.path.join(tmp, name + '.svg')
+ out = os.path.join(tmp, name + '.png')
+ with open(src, 'w', encoding='utf-8') as f:
+ f.write(document)
+ # msvg: ImageMagick's built-in renderer, so the result does not depend on whether an
+ # rsvg delegate happens to be installed.
+ convert('-background', 'none', 'msvg:' + src, *PNG_STABLE, 'PNG32:' + out)
+ return out
+
+
+def resized(src, size, out):
+ convert(src, '-filter', 'Lanczos', '-resize', f'{size}x{size}', *PNG_STABLE,
+ 'PNG32:' + out)
+ return out
+
+
+def write_ios(d, root, tmp):
+ out = os.path.join(root, IOS_DIR)
+ os.makedirs(out, exist_ok=True)
+ full = plate(1024, 0)
+
+ # Light: no alpha channel at all, which App Store Connect requires of the 1024 icon.
+ light = render(tmp, 'ios-light', svg(full, art(d, SAND)))
+ convert(light, '-background', BACKGROUND, '-alpha', 'remove', '-alpha', 'off',
+ *PNG_STABLE, 'PNG24:' + os.path.join(out, 'AppIcon-light.png'))
+
+ # Dark: the art alone; iOS draws its own dark backdrop behind a dark icon.
+ dark = render(tmp, 'ios-dark', svg(art(d, SAND)))
+ shutil.copyfile(dark, os.path.join(out, 'AppIcon-dark.png'))
+
+ # Tinted: grayscale, since iOS tints by luminance -- white art takes the full tint.
+ tinted = render(tmp, 'ios-tinted', svg(full, art(d, '#FFFFFF')))
+ convert(tinted, '-background', BACKGROUND, '-alpha', 'remove', '-alpha', 'off',
+ '-colorspace', 'Gray', '-define', 'png:color-type=0', *PNG_STABLE,
+ os.path.join(out, 'AppIcon-tinted.png'))
+ return [os.path.join(out, n) for n in ('AppIcon-light.png', 'AppIcon-dark.png',
+ 'AppIcon-tinted.png')]
+
+
+def write_icns(master, path, tmp):
+ chunks = b''
+ for kind, size in ICNS_CHUNKS:
+ png = resized(master, size, os.path.join(tmp, f'icns-{size}.png'))
+ data = open(png, 'rb').read()
+ chunks += kind + struct.pack('>I', 8 + len(data)) + data
+ with open(path, 'wb') as f:
+ f.write(b'icns' + struct.pack('>I', 8 + len(chunks)) + chunks)
+
+
+def write_desktop(d, root, tmp):
+ out = os.path.join(root, DESK_DIR)
+ os.makedirs(out, exist_ok=True)
+
+ mac = render(tmp, 'mac', svg(plate(MAC_PLATE, MAC_RADIUS), art(d, SAND, MAC_ART)))
+ write_icns(mac, os.path.join(out, 'giza.icns'), tmp)
+
+ desk = render(tmp, 'desk', svg(plate(1024, DESK_RADIUS), art(d, SAND, DESK_ART)))
+ resized(desk, 512, os.path.join(out, 'giza.png'))
+
+ # One resize per entry from the 1024 render, rather than letting the ico writer scale.
+ entries = [resized(desk, s, os.path.join(tmp, f'ico-{s}.png')) for s in ICO_SIZES]
+ convert(*entries, *PNG_STABLE, os.path.join(out, 'giza.ico'))
+ return [mac, desk]
+
+
+def write_xml(d, root):
+ path = os.path.join(root, XML_PATH)
+ os.makedirs(os.path.dirname(path), exist_ok=True)
+ xml = f'''
+
+
+
+
+
+'''
+ with open(path, 'w', encoding='utf-8') as f:
+ f.write(xml)
+
+
+def write_sheet(path, ios, desktop, tmp):
+ """Every output at the sizes it is seen at, on a mid grey so plates and cutouts show."""
+ tiles = []
+ for src in ios + desktop:
+ for size in (180, 64, 32, 16):
+ tiles.append(resized(src, size, os.path.join(tmp, f'sheet-{len(tiles)}.png')))
+ subprocess.run(['montage', *tiles, '-background', '#808080', '-geometry', '+8+8',
+ '-tile', '4x', '-gravity', 'center', path], check=True)
+
+
+def main():
+ ap = argparse.ArgumentParser(description=__doc__.split('\n')[0])
+ ap.add_argument('--only', nargs='+', choices=['ios', 'desktop', 'xml'])
+ ap.add_argument('--root', default=REPO)
+ ap.add_argument('--sheet')
+ a = ap.parse_args()
+ if shutil.which('convert') is None:
+ sys.exit('ImageMagick `convert` is not on the PATH')
+ only = set(a.only or ['ios', 'desktop', 'xml'])
+ d = master_path()
+
+ with tempfile.TemporaryDirectory() as tmp:
+ ios = write_ios(d, a.root, tmp) if 'ios' in only else []
+ desktop = write_desktop(d, a.root, tmp) if 'desktop' in only else []
+ if 'xml' in only:
+ write_xml(d, a.root)
+ if a.sheet:
+ write_sheet(a.sheet, ios, desktop, tmp)
+
+
+if __name__ == '__main__':
+ main()