Module assets

Theme asset resolution: wallpapers, lockscreens, branding logos, app icons, launcher icon, and the SVG rasterisation pipeline (with process-wide cache) that the canvas consumes.

Functions

• app_default_icon
  Path to app-default.svg inside the active theme’s icon directory. Returns None when the document has no on-disk root or the file is absent.
• app_icon
  Path to the named app icon SVG inside the active theme’s icons/apps/ directory. name is the bare stem (e.g. "firefox", "calculator") without the .svg extension. Returns None when the active document has no on-disk root or the file does not exist.
• branding_asset
  Resolve a branding asset (launcher logo, wallpaper, lockscreen, …) against the active theme’s branding/ tree. Tries three candidate paths in order and returns the first one that exists on disk:
• branding_image
  Resolve a branded image asset, preferring a raster variant (WebP / PNG / JPEG) over the canonical SVG. Tries [branding_raster(name, sw, sh)] first; on None (no raster files at all under branding/{mode}/{name}/) falls back to [branding_asset(name, "svg")].
• branding_raster
  Resolve a raster variant of a branded asset for the given surface dimensions. Looks under branding/{mode}/{name}/ (with the standard mode → opposite-mode → no-mode fallback chain on the directory), parses each filename as WIDTHxHEIGHT.<ext> where <ext> is webp, png, jpg, or jpeg. Returns the best match in the first existing directory:
• decode_svg_bytes
  Decode a UTF-8 SVG document into a premultiplied RGBA8 pixmap of the requested longest-edge size in physical pixels. The shorter edge is scaled proportionally so the icon’s aspect ratio is preserved; the returned (width, height) reflect the final pixmap.
• icon_path
  Resolve a theme-relative icon name to an absolute path inside the active theme’s icons/catalogue/ tree.
• icon_rgba
  Rasterise a theme icon to a premultiplied RGBA8 pixmap.
• launcher_icon
  Path to the launcher-logo SVG for the currently active mode. Resolves through branding_asset using the convention branding/{mode}/launcher.svg, with the standard mode → opposite-mode → no-mode fallback chain.
• lockscreen
  The active mode’s lockscreen / greeter wallpaper. Same resolution strategy as wallpaper: explicit theme.json declaration first, otherwise branding/{mode}/lockscreen.svg via branding_asset. Use branding_image( "lockscreen", sw, sh ) for the size-aware raster lookup.
• logo
  Path to the brand logo SVG for the currently active mode. Convention: branding/{mode}/logo/logo.svg. The “main” logo — usually the wordmark variant a shell would put in an “About” dialog or a splash. Pair with logo_square / logo_horizontal when the surface dictates a different aspect ratio.
• logo_horizontal
  Path to the horizontal (wordmark) brand logo SVG for the currently active mode. Convention: branding/{mode}/logo/horizontal.svg. Use when there is meaningful horizontal space — header bars, menu bars, “About” dialogs, sign-in screens. Same fallback chain as logo.
• logo_square
  Path to the square (1:1) brand logo SVG for the currently active mode. Convention: branding/{mode}/logo/square.svg. Use when the surface is roughly square — app icons, login avatars, splash screens, lockscreen brand badges. Same fallback chain as logo.
• tint_symbolic
  Re-tint a symbolic RGBA icon: replace every pixel’s RGB with tint while keeping the source alpha (weighted by tint.a).
• wallpaper
  The active mode’s homescreen / shell wallpaper. Prefers an explicit declaration in theme.json; when absent, falls back to the convention path branding/{mode}/wallpaper.svg via branding_asset (with mode → opposite-mode → no-mode fallback). Returns None when neither source resolves to an existing file.