Assets Optimization

/assets-optimization — AltTab asset audit and optimization

Goal

Every byte that ships in AltTab.app/Contents/Resources/ should justify itself. Vectors stay vector, rasters compress to HEIC, and neither carries metadata, color profiles, accessibility tags, or producer signatures that AppKit doesn't use.

This skill applies a known-good pipeline to each asset class. It is opinionated about the right format and the right encoder for each kind of content.

When to use

• A designer drops new exports into ~/Desktop/ or resources/.
• Someone asks "why is the bundle so big?".
• After adding a new icon, illustration, app icon variant, or menubar variant.
• Periodic audit when nothing else is broken.

Step 1: Inventory

Run a one-shot enumeration so you know what you're working with:

find resources -type f \( -iname '*.pdf' -o -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.heic' -o -iname '*.svg' -o -iname '*.icns' \) \
  -exec ls -la {} \; | awk '{printf "%8d  %s\n", $5, $9}' | sort -k2

Group what you see by directory. For AltTab the relevant buckets are:

• resources/icons/menubar/ — small template icons shown in the macOS menubar.
• resources/icons/tabs/ — Preferences sidebar icons (template, sized ~13pt).
• resources/icons/permission-window/ — first-launch permission window icons (~32pt).
• resources/icons/app/ — the macOS app icon (.icns + .iconset/). Don't touch — .icns is required by the bundle and Apple's tooling produces near-optimal output already.
• resources/illustrations/ — the appearance-tab preview thumbnails. Raster (screenshots inside).

For each asset, decide what category it falls into:

If an asset is in the wrong format, flag it. If it's in the right format but unoptimized, run the matching pipeline below.

Step 2: Vector PDFs — Figma exports

Figma's "Export → PDF" output is bloated. For each menubar/illustration/icon vector PDF that came from Figma, you can strip ~50–75% of the bytes without losing a single rendered pixel.

What Figma adds that AppKit doesn't need:

1. Embedded ICC color profile (/ICCBased ..., ~3.2 KB compressed). Replace every [/ICCBased N R] reference with /DeviceRGB (or /DeviceGray for monochrome). Patches needed in:
   • the page Resources/ColorSpace dict
   • every Form XObject's Resources/ColorSpace dict (these are streams, not plain dicts — pikepdf's pdf.objects will only catch them if you accept both Dictionary and Stream)
   • every Image XObject's direct /ColorSpace key
   • every Shading dict inside Pattern entries (Figma's color icons use 8+ patterns, each with its own /ColorSpace N R reference)
2. /Metadata XMP packet (~830 B) — Figma's XML manifest.
3. /StructTreeRoot, /ParentTree, /StructElem — accessibility tags ("Document" / "Part" structural roles). AppKit's PDF renderer ignores them.
4. /Info dict — Producer="Figma", Title="Menubar 22x22@1x white". In Figma's exports the Info dict sometimes lives inline inside the Catalog rather than at the trailer level, so deleting pdf.docinfo isn't enough — also del root[Name('/Info')].
5. /Lang, /MarkInfo, /Annots, /StructParents, /Tabs — empty or trivial page-level entries.
6. /ProcSet [/PDF] — deprecated since PDF 1.4.

Use the script:

python3 scripts/assets/optimize_figma_pdf.py resources/icons/menubar/*.pdf

It edits in place and prints the savings per file. After running, also pipe through mutool clean -ggg -z and qpdf --object-streams=generate --recompress-flate --compression-level=9 for the final 1–2% squeeze.

Verify each file still renders by sips'ing it back to PNG and eyeballing:

for f in resources/icons/menubar/*.pdf; do
  sips -s format png "$f" --out "/tmp/$(basename $f .pdf).png" -Z 300 >/dev/null 2>&1
done

Open the PNGs in Preview to confirm nothing visual changed.

Step 3: SF Symbols via font subset

Every SF Symbol shipped in AltTab — switcher status icons, sidebar tab icons, button icons, permission/feedback icons — is rendered as a text glyph from a subsetted SF Pro Text font. There are no SF-Symbol PDFs in the bundle.

How it works: SF Symbols are glyphs in the Private Use Area of SF Pro Text. Apple's SF-Pro-Text-Regular.otf contains every symbol they've ever shipped. We subset it down to just the codepoints AltTab needs (currently ~36 glyphs, ~17 KB) into resources/SF-Pro-Text-Regular.otf, and register it via Info.plist:ATSApplicationFontsPath = "". At runtime, NSFont(name: "SF Pro Text", size:) resolves to the bundled subset on macOS <11 (where the system font isn't installed) and to the system font on macOS 11+, with identical glyph appearance either way.

To add a new SF Symbol:

1. Open SF Symbols.app, search for the symbol, press Cmd-C to copy the symbol character to the clipboard. (Apple's name→codepoint mapping is not exposed via public API, and the SF Pro Text font's cmap uses uniXXXXXX.medium-style names rather than semantic ones, so this manual lookup is the authoritative path.)
2. Paste the character into a new case on the Symbols enum in src/switcher/main-window/TileFontIconView.swift — e.g., case foo = "􀝥" // SF Symbol name.
3. Paste the same character at the end of the --text= argument in scripts/assets/subset_font.sh.
4. Run bash scripts/assets/subset_font.sh. It reads /Library/Fonts/SF-Pro-Text-Regular.otf (installed by SF Symbols.app — a standard developer prerequisite) and writes the regenerated subset to resources/SF-Pro-Text-Regular.otf. Picks up Apple's latest glyph refinements automatically.
5. Use it in code: NSImage.fromSymbol(.foo, pointSize: 14) returns a template NSImage; or TileFontIconView(symbol: .foo, ...) for the cached-attributed-string path in the switcher hot loop.

The script runs pyftsubset via the project's pipenv environment. Warnings about MERG/meta/trak tables being dropped are normal — those tables aren't relevant to glyph rendering.

Historical note: SF Symbols via PDF (deprecated, scripts removed)

A previous pipeline shipped each SF Symbol as a per-glyph PDF in resources/icons/. The pipeline lives only in git history now (scripts/assets/export_sf_symbol_pdf.swift was deleted alongside the migrated PDFs). The technique is worth knowing in case a future need arises (e.g., a multi-color symbol that fonts can't represent):

• The naive route — NSImage(systemSymbolName:).draw(in:) against a PDF CGContext — produces a black rectangle, because Quartz emits image-mask + fill-rectangle operators where the rectangle paints over the mask. AppKit bug at the PDF emission level; paletteColors config does not fix it.
• The working route was to extract the symbol's vector path directly via private selectors that have been stable across macOS 11–15: NSImage(systemSymbolName:).representations[0] (NSSymbolImageRep) → .perform("vectorGlyph") (CUINamedVectorGlyph) → .perform("CGPath") (real CGPath).
• The CGPath lives in CUI's internal coordinate space (~2× display points, Y-down) — scale to fit the canvas and flip Y. Walk the path via CGPath.applyWithBlock and emit raw PDF operators (m, l, c, h, f). Non-zero winding fill. Fill with DeviceGray (0 g), not NSColor.black.cgColor, which drags in a ~3.4 KB ICC color profile.
• Final PDF wrapper: 4 objects (Catalog, Pages, Page, Content), no /Info, no /Metadata, no /Resources/ColorSpace. ~750–1800 bytes per icon.

Git: see commit 990c1e79 ("feat: pro improve assets") for the PDF pipeline as-it-was; subsequent commit migrated the SF-Symbol PDFs back to font glyphs.

Step 4: Raster → HEIC at q50

For anything raster (illustration thumbnails, screenshots inside an icon, anything photographic), HEIC at quality 50 is the baseline. q50 is roughly 50% smaller than JPEG at perceptually-equivalent quality, and at the small display sizes used in this app the artifacts are invisible.

Pipeline (built-in to macOS via sips):

sips -Z 1000 -s format heic -s formatOptions 50 input.png --out output.heic

• -Z 1000 resizes the longest edge to 1000px preserving aspect ratio. AltTab's illustration display is 500pt wide, so 1000px is the correct @2x ship size. Anything larger wastes bytes; anything smaller looks soft on Retina.
• formatOptions 50 is the quality. q50 was chosen after a side-by-side comparison at q20/q35/q50/q65/q80 — q50 was the lowest setting where text in screenshots stayed legible and gradient backgrounds didn't band.

Use the script for batch conversion:

bash scripts/assets/encode_heic.sh ~/Desktop 1000 50

That walks all PNG/JPEG files in the source directory, resizes to longest-edge 1000px at q50 HEIC, writes outputs to /tmp/heic-out/.

Visual review (mandatory)

Before swapping the new HEICs into resources/, always decode a representative sample back to PNG and visually compare against the source:

sips -s format png /tmp/heic-out/sample.heic --out /tmp/sample-decoded.png >/dev/null 2>&1
open /tmp/sample-decoded.png /Users/you/Desktop/sample.png

Pick the visually most demanding file from the batch — usually one with the most text or the strongest gradients. Confirm:

• No banding in flat color regions
• Text edges still crisp at native display size
• No haloing around anti-aliased edges
• Color rendition matches

If anything looks degraded, bump quality to q60 or q65 and re-batch. The user, not the script, is the final arbiter — show them the sample with sizes before committing.

Bumping quality

If q50 isn't acceptable, the next quality steps are q60 and q65 — beyond that, returns diminish quickly. q80 is the previous default in this repo and roughly 2× the bytes of q50 for no visible improvement on AltTab's content.

Step 5: pbxproj registration

Whenever you change the file extension of a resource (.jpg → .heic, .png → .pdf, etc.), update alt-tab-macos.xcodeproj/project.pbxproj. The places that need patching:

1. PBXBuildFile section — comment + the comment inside fileRef = ... /* name.ext */.
2. PBXFileReference section — comment, lastKnownFileType (e.g. image.pdf, image.heic, image.png), and path = "name.ext".
3. PBXGroup section — the file's entry inside its parent group's children.
4. PBXResourcesBuildPhase section — the entry in the main app target's files.

For pure extension swaps (no new files), sed -i '' 's|old\.ext|new.ext|g' plus a lastKnownFileType substitution covers it. For new files, generate new 24-char uppercase-hex object IDs (python3 -c "import secrets; print(secrets.token_hex(12).upper())") and insert in all four places.

If you removed an asset entirely (file deleted from disk), delete its 4 entries from pbxproj — otherwise the build fails with "missing file" or ships dangling references.

Step 6: Verify

bash ai/build.sh        # must show ** BUILD SUCCEEDED **
bash ai/run.sh          # launch the app and visually inspect every asset

Walk through every UI surface that loads an asset:

• Menubar icon (default + the two alternates from Preferences → General → Menubar icon)
• Preferences sidebar — 4 tab icons (SF Symbol on macOS 11+, bundled PDF below)
• Permissions window — open by revoking a permission
• Preferences → Appearance — illustration thumbnails change per show/hide row

Compare git diff --stat before committing. Asset replacements should net negative on bundle size.

Reporting

After the run, report:

• File-by-file before/after sizes for everything that changed.
• Total bundle delta in KB.
• Any files left untouched and why (e.g., app.icns — bundle-required format).
• The encoder settings used (especially HEIC quality if not q50, so the next person knows).
• Anything the visual review revealed (e.g., "had to bump to q60 for thumbnails_dark because gradient banding at q50").