Add Rust logo pipeline: trim, metrics, knockout and Branding settings

Logos (PNG, JPEG, WebP) are decoded, trimmed to their ink box, downscaled
to 1200 px and re-encoded as a content-addressed print PNG plus a white
knockout variant when the logo has alpha; aspect, ink density, mean colour
and kind (wordmark, mark, tall) are stored with the settings and frozen in
the issue snapshot. Legacy logos are derived at startup. The Test Vendor logo
PDF shrinks from 334 KB to 92 KB. Settings gains a Branding section with
white and dark previews and a business-name toggle (migration M5).

src-tauri/Cargo.lock

@@ -340,6 +340,12 @@ version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
 [[package]]
 name = "bytes"
 version = "1.12.1"
@@ -1703,6 +1709,32 @@ dependencies = [
  "icu_properties",
 ]
 
+[[package]]
+name = "image"
+version = "0.25.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "image-webp",
+ "moxcms",
+ "num-traits",
+ "png 0.18.1",
+ "zune-core",
+ "zune-jpeg",
+]
+
+[[package]]
+name = "image-webp"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
+dependencies = [
+ "byteorder-lite",
+ "quick-error",
+]
+
 [[package]]
 name = "indexmap"
 version = "1.9.3"
@@ -2089,6 +2121,16 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "moxcms"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
 [[package]]
 name = "muda"
 version = "0.20.0"
@@ -2700,6 +2742,18 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "pxfm"
+version = "0.1.30"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
+
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
 [[package]]
 name = "quick-xml"
 version = "0.42.0"
@@ -4236,6 +4290,7 @@ version = "0.1.0"
 dependencies = [
  "base64 0.22.1",
  "chrono",
+ "image",
  "percent-encoding",
  "rusqlite",
  "rusqlite_migration",
@@ -5138,6 +5193,21 @@ version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
 
+[[package]]
+name = "zune-core"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d56377fd46368984a170bc5aac5567e52ca5da874caa60bea39fcbca78fb658b"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
+dependencies = [
+ "zune-core",
+]
+
 [[package]]
 name = "zvariant"
 version = "5.15.0"

src-tauri/Cargo.toml

@@ -28,6 +28,7 @@ thiserror = "2"
 base64 = "0.22"
 sha2 = "0.10"
 percent-encoding = "2"
+image = { version = "0.25.10", default-features = false, features = ["png", "jpeg", "webp"] }
 
 # Desktop-only plugins (not available on mobile targets).
 [target.'cfg(not(any(target_os = "android", target_os = "ios")))'.dependencies]

src-tauri/src/commands/assets.rs

@@ -78,6 +78,24 @@ fn write_asset(data_dir: &Path, kind: &str, bytes: &[u8]) -> Result<String, Stri
     Ok(format!("assets/{file}"))
 }
 
+/// Write `assets/<file_name>` unless it already exists. For content-addressed derivatives, where the
+/// same name always means the same bytes. The name must be a plain `[a-z0-9._-]` file name.
+pub fn write_named_asset(data_dir: &Path, file_name: &str, bytes: &[u8]) -> Result<String, String> {
+    let plain = !file_name.is_empty()
+        && !file_name.starts_with('.')
+        && file_name
+            .chars()
+            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || matches!(c, '.' | '-' | '_'));
+    if !plain {
+        return Err(format!("Invalid asset name: {file_name}"));
+    }
+    let target = assets_dir(data_dir)?.join(file_name);
+    if !target.exists() {
+        std::fs::write(&target, bytes).map_err(|e| e.to_string())?;
+    }
+    Ok(format!("assets/{file_name}"))
+}
+
 fn asset_data_uri(data_dir: &Path, path: &str) -> Result<String, String> {
     let file = resolve_asset(data_dir, path)?;
     let bytes = std::fs::read(&file).map_err(|e| e.to_string())?;
@@ -162,6 +180,18 @@ mod tests {
         assert!(uri.starts_with("data:image/jpeg;base64,"));
     }
 
+    #[test]
+    fn named_assets_are_plain_names_and_not_overwritten() {
+        let dir = tempdir().unwrap();
+        let stored = write_named_asset(dir.path(), "logo-ab12cd34-print.png", b"one").unwrap();
+        assert_eq!(stored, "assets/logo-ab12cd34-print.png");
+        write_named_asset(dir.path(), "logo-ab12cd34-print.png", b"two").unwrap();
+        assert_eq!(std::fs::read(dir.path().join(&stored)).unwrap(), b"one");
+        for bad in ["", ".hidden", "../x.png", "a/b.png", "A.png", "x y.png"] {
+            assert!(write_named_asset(dir.path(), bad, b"x").is_err(), "{bad}");
+        }
+    }
+
     #[test]
     fn data_uri_mime_comes_from_the_bytes_not_the_extension() {
         let dir = tempdir().unwrap();

src-tauri/src/commands/invoice.rs

@@ -209,6 +209,9 @@ fn vendor_snapshot(settings: &Settings) -> String {
         "vendorGstin": gstin,
         "vendorStateCode": settings.vendor_state_code,
         "logoPath": settings.logo_path,
+        "logoKnockoutPath": settings.logo_knockout_path,
+        "logoMeta": settings.logo_meta,
+        "logoIncludesName": settings.logo_includes_name,
         "signaturePath": settings.signature_path,
         "gstRegistration": settings.gst_registration,
         "signatoryName": settings.signatory_name,
@@ -760,7 +763,8 @@ mod tests {
         let mut conn = registered();
         conn.execute(
             "UPDATE app_settings SET vendor_name = 'Real Name', logo_path = 'assets/logo-1.png',
-             signatory_name = 'A Signer', signatory_designation = 'Partner'",
+             logo_knockout_path = 'assets/logo-1-knockout.png', logo_meta = '{\"kind\":\"wordmark\"}',
+             logo_includes_name = 'yes', signatory_name = 'A Signer', signatory_designation = 'Partner'",
             [],
         )
         .unwrap();
@@ -779,6 +783,9 @@ mod tests {
         assert_eq!(snap["vendorGstin"], "27AAPFU0939F1ZV");
         assert_eq!(snap["vendorStateCode"], "27");
         assert_eq!(snap["logoPath"], "assets/logo-1.png");
+        assert_eq!(snap["logoKnockoutPath"], "assets/logo-1-knockout.png");
+        assert_eq!(snap["logoMeta"], "{\"kind\":\"wordmark\"}");
+        assert_eq!(snap["logoIncludesName"], "yes");
         assert!(snap["signaturePath"].is_null());
         assert_eq!(snap["gstRegistration"], "regular");
         assert_eq!(snap["signatoryName"], "A Signer");

src-tauri/src/commands/logo.rs

@@ -0,0 +1,270 @@
+use super::assets::{relative_asset_path, resolve_asset, write_named_asset};
+use super::settings::{map_settings, SETTINGS_COLS};
+use crate::logo::{process_logo, sniff_extension, LogoMetrics, MAX_INPUT_BYTES};
+use crate::models::Settings;
+use crate::AppState;
+use base64::{engine::general_purpose::STANDARD, Engine};
+use rusqlite::{params, Connection};
+use serde::Serialize;
+use sha2::{Digest, Sha256};
+use std::path::Path;
+use tauri::State;
+
+/// The stored files and measurements of an imported logo. Paths are relative to the data dir.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LogoAsset {
+    pub original_path: String,
+    pub print_path: String,
+    pub knockout_path: Option<String>,
+    pub metrics: LogoMetrics,
+}
+
+fn sha8(bytes: &[u8]) -> String {
+    Sha256::digest(bytes).iter().take(4).map(|b| format!("{b:02x}")).collect()
+}
+
+/// Derive the print and knockout images from `bytes` and store them content-addressed in the asset
+/// store. `existing_original` is the already stored file the bytes came from (legacy logos); without
+/// it the bytes are stored as the original. Nothing is ever deleted: issued invoices may still point at
+/// older logo files.
+fn store_logo(data_dir: &Path, bytes: &[u8], existing_original: Option<String>) -> Result<LogoAsset, String> {
+    let derived = process_logo(bytes).map_err(|e| e.to_string())?;
+    let id = sha8(bytes);
+    let original_path = match existing_original {
+        Some(path) => path,
+        None => {
+            let ext = sniff_extension(bytes).map_err(|e| e.to_string())?;
+            write_named_asset(data_dir, &format!("logo-{id}-original.{ext}"), bytes)?
+        }
+    };
+    let print_path = write_named_asset(data_dir, &format!("logo-{id}-print.png"), &derived.print_png)?;
+    let knockout_path = derived
+        .knockout_png
+        .as_deref()
+        .map(|png| write_named_asset(data_dir, &format!("logo-{id}-knockout.png"), png))
+        .transpose()?;
+    Ok(LogoAsset { original_path, print_path, knockout_path, metrics: derived.metrics })
+}
+
+pub fn import_logo_from_path(data_dir: &Path, source_path: &str) -> Result<LogoAsset, String> {
+    let len = std::fs::metadata(source_path).map_err(|e| e.to_string())?.len();
+    if len > MAX_INPUT_BYTES as u64 {
+        return Err(crate::logo::LogoError::TooLarge.to_string());
+    }
+    let bytes = std::fs::read(source_path).map_err(|e| e.to_string())?;
+    store_logo(data_dir, &bytes, None)
+}
+
+pub fn import_logo_from_base64(data_dir: &Path, data_base64: &str) -> Result<LogoAsset, String> {
+    // Base64 is 4/3 of the payload; refuse before decoding something huge.
+    if data_base64.len() > MAX_INPUT_BYTES / 3 * 4 + 8 {
+        return Err(crate::logo::LogoError::TooLarge.to_string());
+    }
+    let bytes = STANDARD.decode(data_base64.as_bytes()).map_err(|e| e.to_string())?;
+    store_logo(data_dir, &bytes, None)
+}
+
+fn metrics_json(metrics: &LogoMetrics) -> Result<String, String> {
+    serde_json::to_string(metrics).map_err(|e| e.to_string())
+}
+
+/// Derive trimmed print and knockout images for a logo saved before the pipeline existed
+/// (`logo_path` set, `logo_meta` empty) and point the settings at them. The old file is kept as the
+/// original. Returns whether anything changed.
+pub fn ensure_logo_derived_impl(conn: &Connection, data_dir: &Path) -> Result<bool, String> {
+    let (logo_path, meta): (Option<String>, String) = conn
+        .query_row("SELECT logo_path, logo_meta FROM app_settings WHERE id = 1", [], |r| {
+            Ok((r.get(0)?, r.get(1)?))
+        })
+        .map_err(|e| e.to_string())?;
+    let Some(logo_path) = logo_path.filter(|p| !p.trim().is_empty()) else {
+        return Ok(false);
+    };
+    if !meta.is_empty() {
+        return Ok(false);
+    }
+    let file = resolve_asset(data_dir, &logo_path)?;
+    let bytes = std::fs::read(&file).map_err(|e| e.to_string())?;
+    let asset = store_logo(data_dir, &bytes, Some(relative_asset_path(data_dir, &logo_path)?))?;
+    conn.execute(
+        "UPDATE app_settings SET logo_path = ?1, logo_original_path = ?2, logo_knockout_path = ?3,
+         logo_meta = ?4 WHERE id = 1",
+        params![asset.print_path, asset.original_path, asset.knockout_path, metrics_json(&asset.metrics)?],
+    )
+    .map_err(|e| e.to_string())?;
+    Ok(true)
+}
+
+/// Detach the logo from the settings. The files stay: issued invoices may reference them.
+pub fn remove_logo_impl(conn: &Connection) -> Result<(), String> {
+    conn.execute(
+        "UPDATE app_settings SET logo_path = NULL, logo_original_path = NULL, logo_knockout_path = NULL,
+         logo_meta = '', logo_includes_name = 'auto' WHERE id = 1",
+        [],
+    )
+    .map_err(|e| e.to_string())?;
+    Ok(())
+}
+
+fn read_settings(conn: &Connection) -> Result<Settings, String> {
+    conn.query_row(
+        &format!("SELECT {} FROM app_settings WHERE id = 1", SETTINGS_COLS),
+        [],
+        map_settings,
+    )
+    .map_err(|e| e.to_string())
+}
+
+#[tauri::command]
+pub fn import_logo(state: State<AppState>, source_path: String) -> Result<LogoAsset, String> {
+    import_logo_from_path(&state.data_dir, &source_path)
+}
+
+/// For when the frontend already holds the bytes. The file name is ignored: the type comes from the bytes.
+#[tauri::command]
+pub fn save_logo_bytes(
+    state: State<AppState>,
+    #[allow(unused_variables)] file_name: String,
+    data_base64: String,
+) -> Result<LogoAsset, String> {
+    import_logo_from_base64(&state.data_dir, &data_base64)
+}
+
+#[tauri::command]
+pub fn ensure_logo_derived(state: State<AppState>) -> Result<Settings, String> {
+    let conn = state.db.lock().map_err(|e| e.to_string())?;
+    ensure_logo_derived_impl(&conn, &state.data_dir)?;
+    read_settings(&conn)
+}
+
+#[tauri::command]
+pub fn remove_logo(state: State<AppState>) -> Result<Settings, String> {
+    let conn = state.db.lock().map_err(|e| e.to_string())?;
+    remove_logo_impl(&conn)?;
+    read_settings(&conn)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use image::{DynamicImage, ImageFormat, Rgba, RgbaImage};
+    use std::io::Cursor;
+    use tempfile::tempdir;
+
+    /// A 300x100 transparent canvas with a 100x20 opaque bar off-centre.
+    fn padded_png() -> Vec<u8> {
+        let mut img = RgbaImage::new(300, 100);
+        for y in 40..60 {
+            for x in 150..250 {
+                img.put_pixel(x, y, Rgba([10, 20, 30, 255]));
+            }
+        }
+        let mut out = Vec::new();
+        DynamicImage::ImageRgba8(img).write_to(&mut Cursor::new(&mut out), ImageFormat::Png).unwrap();
+        out
+    }
+
+    fn logo_columns(conn: &Connection) -> (Option<String>, Option<String>, Option<String>, String) {
+        conn.query_row(
+            "SELECT logo_path, logo_original_path, logo_knockout_path, logo_meta FROM app_settings WHERE id = 1",
+            [],
+            |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?, r.get(3)?)),
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn base64_import_stores_content_addressed_files() {
+        let dir = tempdir().unwrap();
+        let bytes = padded_png();
+        let asset = import_logo_from_base64(dir.path(), &STANDARD.encode(&bytes)).unwrap();
+        let id = sha8(&bytes);
+        assert_eq!(asset.original_path, format!("assets/logo-{id}-original.png"));
+        assert_eq!(asset.print_path, format!("assets/logo-{id}-print.png"));
+        assert_eq!(asset.knockout_path.as_deref(), Some(format!("assets/logo-{id}-knockout.png").as_str()));
+        assert_eq!((asset.metrics.width, asset.metrics.height), (100, 20));
+        assert_eq!(std::fs::read(dir.path().join(&asset.original_path)).unwrap(), bytes);
+        for rel in [&asset.print_path, asset.knockout_path.as_ref().unwrap()] {
+            assert!(resolve_asset(dir.path(), rel).is_ok());
+        }
+        // The same bytes land on the same names.
+        assert_eq!(import_logo_from_base64(dir.path(), &STANDARD.encode(&bytes)).unwrap().print_path, asset.print_path);
+        let json = serde_json::to_value(&asset).unwrap();
+        assert_eq!(json["metrics"]["kind"], "wordmark");
+        assert_eq!(json["metrics"]["opaqueBackground"], false);
+    }
+
+    #[test]
+    fn path_import_reads_the_file_and_rejects_bad_input() {
+        let dir = tempdir().unwrap();
+        let src = tempdir().unwrap();
+        let file = src.path().join("brand.png");
+        std::fs::write(&file, padded_png()).unwrap();
+        let asset = import_logo_from_path(dir.path(), file.to_str().unwrap()).unwrap();
+        assert_eq!(asset.metrics.width, 100);
+
+        let gif = src.path().join("x.gif");
+        std::fs::write(&gif, b"GIF89a....").unwrap();
+        assert_eq!(
+            import_logo_from_path(dir.path(), gif.to_str().unwrap()).unwrap_err(),
+            "Use a PNG, JPEG or WebP image"
+        );
+        assert!(import_logo_from_path(dir.path(), "/nonexistent/logo.png").is_err());
+        assert!(import_logo_from_base64(dir.path(), "!!not base64!!").is_err());
+        assert!(import_logo_from_base64(dir.path(), &STANDARD.encode(b"junk")).is_err());
+    }
+
+    #[test]
+    fn ensure_derives_a_legacy_untrimmed_logo_and_keeps_the_old_file() {
+        let dir = tempdir().unwrap();
+        let conn = crate::db::open_in_memory().unwrap();
+        let legacy = write_named_asset(dir.path(), "logo-legacy.png", &padded_png()).unwrap();
+        conn.execute("UPDATE app_settings SET logo_path = ?1", [&legacy]).unwrap();
+
+        assert!(ensure_logo_derived_impl(&conn, dir.path()).unwrap());
+        let (logo, original, knockout, meta) = logo_columns(&conn);
+        let logo = logo.unwrap();
+        assert!(logo.ends_with("-print.png"), "{logo}");
+        assert_eq!(original.as_deref(), Some(legacy.as_str()));
+        assert!(knockout.unwrap().ends_with("-knockout.png"));
+        let metrics: LogoMetrics = serde_json::from_str(&meta).unwrap();
+        assert_eq!((metrics.width, metrics.height), (100, 20));
+        assert!(dir.path().join(&legacy).is_file());
+        assert!(dir.path().join(&logo).is_file());
+
+        // Already derived: nothing to do the second time.
+        assert!(!ensure_logo_derived_impl(&conn, dir.path()).unwrap());
+        assert_eq!(logo_columns(&conn).0.as_deref(), Some(logo.as_str()));
+    }
+
+    #[test]
+    fn ensure_does_nothing_without_a_logo_and_errors_on_a_missing_file() {
+        let dir = tempdir().unwrap();
+        let conn = crate::db::open_in_memory().unwrap();
+        assert!(!ensure_logo_derived_impl(&conn, dir.path()).unwrap());
+        conn.execute("UPDATE app_settings SET logo_path = 'assets/gone.png'", []).unwrap();
+        assert!(ensure_logo_derived_impl(&conn, dir.path()).is_err());
+        // Left untouched so a later start can retry.
+        assert_eq!(logo_columns(&conn).0.as_deref(), Some("assets/gone.png"));
+    }
+
+    #[test]
+    fn remove_clears_the_columns_and_keeps_the_files() {
+        let dir = tempdir().unwrap();
+        let conn = crate::db::open_in_memory().unwrap();
+        let asset = import_logo_from_base64(dir.path(), &STANDARD.encode(padded_png())).unwrap();
+        conn.execute(
+            "UPDATE app_settings SET logo_path = ?1, logo_original_path = ?2, logo_knockout_path = ?3,
+             logo_meta = ?4, logo_includes_name = 'yes'",
+            params![asset.print_path, asset.original_path, asset.knockout_path, metrics_json(&asset.metrics).unwrap()],
+        )
+        .unwrap();
+        remove_logo_impl(&conn).unwrap();
+        assert_eq!(logo_columns(&conn), (None, None, None, String::new()));
+        let settings = read_settings(&conn).unwrap();
+        assert_eq!(settings.logo_includes_name, "auto");
+        assert!(dir.path().join(&asset.print_path).is_file());
+        assert!(dir.path().join(&asset.original_path).is_file());
+    }
+}

src-tauri/src/commands/mod.rs

@@ -3,6 +3,7 @@ pub mod assets;
 pub mod clients;
 pub mod files;
 pub mod invoice;
+pub mod logo;
 pub mod raw;
 pub mod series;
 pub mod settings;

src-tauri/src/commands/settings.rs

@@ -6,7 +6,8 @@ use tauri::State;
 pub(crate) const SETTINGS_COLS: &str = "vendor_name, vendor_address, vendor_email, vendor_phone, vendor_pan,
     vendor_gstin, vendor_state_code, logo_path, signature_path, default_bank_id, default_tax_rate,
     default_tax_type, payment_terms_days, currency, onboarded, theme, gst_registration, default_hsn_sac, signatory_name,
-    signatory_designation, render_prefs, last_export_dir";
+    signatory_designation, render_prefs, last_export_dir, logo_original_path, logo_knockout_path, logo_meta,
+    logo_includes_name";
 
 pub(crate) fn map_settings(row: &Row) -> rusqlite::Result<Settings> {
     Ok(Settings {
@@ -32,6 +33,10 @@ pub(crate) fn map_settings(row: &Row) -> rusqlite::Result<Settings> {
         signatory_designation: row.get(19)?,
         render_prefs: row.get(20)?,
         last_export_dir: row.get(21)?,
+        logo_original_path: row.get(22)?,
+        logo_knockout_path: row.get(23)?,
+        logo_meta: row.get(24)?,
+        logo_includes_name: row.get(25)?,
     })
 }
 
@@ -48,6 +53,9 @@ pub fn get_settings(state: State<AppState>) -> Result<Settings, String> {
 
 #[tauri::command]
 pub fn save_settings(state: State<AppState>, settings: Settings) -> Result<Settings, String> {
+    if !matches!(settings.logo_includes_name.as_str(), "auto" | "yes" | "no") {
+        return Err("Logo includes name must be auto, yes or no".into());
+    }
     let conn = state.db.lock().map_err(|e| e.to_string())?;
     conn.execute(
         r#"UPDATE app_settings SET
@@ -56,7 +64,9 @@ pub fn save_settings(state: State<AppState>, settings: Settings) -> Result<Setti
              signature_path = ?9, default_bank_id = ?10, default_tax_rate = ?11,
              default_tax_type = ?12, payment_terms_days = ?13, currency = ?14,
              onboarded = ?15, theme = ?16, gst_registration = ?17, default_hsn_sac = ?18,
-             signatory_name = ?19, signatory_designation = ?20, render_prefs = ?21
+             signatory_name = ?19, signatory_designation = ?20, render_prefs = ?21,
+             logo_original_path = ?22, logo_knockout_path = ?23, logo_meta = ?24,
+             logo_includes_name = ?25
            WHERE id = 1"#,
         params![
             settings.vendor_name,
@@ -80,6 +90,10 @@ pub fn save_settings(state: State<AppState>, settings: Settings) -> Result<Setti
             settings.signatory_name,
             settings.signatory_designation,
             settings.render_prefs,
+            settings.logo_original_path,
+            settings.logo_knockout_path,
+            settings.logo_meta,
+            settings.logo_includes_name,
         ],
     )
     .map_err(|e| e.to_string())?;
@@ -253,6 +267,35 @@ mod tests {
         assert_eq!(json["renderPrefs"], "{\"version\":1}");
     }
 
+    #[test]
+    fn settings_carry_logo_columns() {
+        let conn = crate::db::open_in_memory().unwrap();
+        let read = |conn: &Connection| {
+            conn.query_row(
+                &format!("SELECT {} FROM app_settings WHERE id = 1", SETTINGS_COLS),
+                [],
+                map_settings,
+            )
+            .unwrap()
+        };
+        let fresh = read(&conn);
+        assert_eq!(fresh.logo_original_path, None);
+        assert_eq!(fresh.logo_knockout_path, None);
+        assert_eq!(fresh.logo_meta, "");
+        assert_eq!(fresh.logo_includes_name, "auto");
+        conn.execute(
+            "UPDATE app_settings SET logo_original_path = 'assets/o.png', logo_knockout_path = 'assets/k.png',
+             logo_meta = '{}', logo_includes_name = 'no' WHERE id = 1",
+            [],
+        )
+        .unwrap();
+        let json = serde_json::to_value(read(&conn)).unwrap();
+        assert_eq!(json["logoOriginalPath"], "assets/o.png");
+        assert_eq!(json["logoKnockoutPath"], "assets/k.png");
+        assert_eq!(json["logoMeta"], "{}");
+        assert_eq!(json["logoIncludesName"], "no");
+    }
+
     #[test]
     fn deleting_the_default_bank_promotes_the_lowest_remaining() {
         let mut conn = crate::db::open_in_memory().unwrap();

src-tauri/src/db.rs

@@ -10,7 +10,7 @@ const MAX_BACKUPS: usize = 10;
 const BACKUP_PREFIX: &str = "voiced-pre-v";
 
 /// Highest schema version, i.e. the number of entries in `migrations()`.
-const LATEST_VERSION: i64 = 4;
+const LATEST_VERSION: i64 = 5;
 
 #[derive(Debug, thiserror::Error)]
 pub enum DbError {
@@ -181,8 +181,17 @@ ALTER TABLE invoices ADD COLUMN archived_at TEXT;
 ALTER TABLE app_settings ADD COLUMN last_export_dir TEXT NOT NULL DEFAULT '';
 "#;
 
+/// Version 5: logo pipeline outputs. `logo_path` now points at the trimmed print image; the original
+/// is kept so it can be re-derived. Invoice snapshots issued earlier simply lack the new keys.
+const M5: &str = r#"
+ALTER TABLE app_settings ADD COLUMN logo_original_path TEXT;
+ALTER TABLE app_settings ADD COLUMN logo_knockout_path TEXT;
+ALTER TABLE app_settings ADD COLUMN logo_meta TEXT NOT NULL DEFAULT '';
+ALTER TABLE app_settings ADD COLUMN logo_includes_name TEXT NOT NULL DEFAULT 'auto';
+"#;
+
 fn migrations() -> Migrations<'static> {
-    Migrations::new(vec![M::up(SCHEMA), M::up(M2), M::up(M3), M::up(M4)])
+    Migrations::new(vec![M::up(SCHEMA), M::up(M2), M::up(M3), M::up(M4), M::up(M5)])
 }
 
 /// Open (creating if needed) the database at `path` and bring it to the latest schema.
@@ -585,6 +594,42 @@ CREATE INDEX IF NOT EXISTS idx_invoices_created ON invoices(created_at DESC);
         assert_eq!(stored, json);
     }
 
+    #[test]
+    fn logo_columns_default_and_existing_logo_is_untouched() {
+        let conn = open_in_memory().unwrap();
+        let row: (Option<String>, Option<String>, String, String) = conn
+            .query_row(
+                "SELECT logo_original_path, logo_knockout_path, logo_meta, logo_includes_name
+                 FROM app_settings WHERE id = 1",
+                [],
+                |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?, r.get(3)?)),
+            )
+            .unwrap();
+        assert_eq!(row, (None, None, String::new(), "auto".to_string()));
+
+        // A database at v4 with a logo keeps it; only the new columns appear.
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("voiced.db");
+        {
+            let mut old = Connection::open(&path).unwrap();
+            Migrations::new(vec![M::up(SCHEMA), M::up(M2), M::up(M3), M::up(M4)])
+                .to_latest(&mut old)
+                .unwrap();
+            seed(&old).unwrap();
+            old.execute("UPDATE app_settings SET logo_path = 'assets/logo-old.png'", []).unwrap();
+            assert_eq!(user_version(&old), 4);
+        }
+        let conn = open(&path, &dir.path().join("backups")).unwrap();
+        assert_eq!(user_version(&conn), 5);
+        let (logo, meta): (String, String) = conn
+            .query_row("SELECT logo_path, logo_meta FROM app_settings WHERE id = 1", [], |r| {
+                Ok((r.get(0)?, r.get(1)?))
+            })
+            .unwrap();
+        assert_eq!((logo.as_str(), meta.as_str()), ("assets/logo-old.png", ""));
+        assert_eq!(backups_in(&dir.path().join("backups")).len(), 1);
+    }
+
     fn build_v1_database(path: &Path) {
         let conn = Connection::open(path).unwrap();
         conn.execute_batch(V1_SCHEMA).unwrap();

src-tauri/src/lib.rs

@@ -1,6 +1,7 @@
 mod commands;
 mod db;
 mod gst;
+mod logo;
 mod models;
 mod selftest;
 
@@ -66,6 +67,10 @@ fn init_state(app: &tauri::App) -> Result<AppState, Box<dyn std::error::Error>>
         show_startup_error(app, &format!("Could not update stored image paths: {e}"), Some(&data_dir));
         return Err(e.into());
     }
+    // Best effort: a logo that cannot be derived keeps working untrimmed, and the next start retries.
+    if let Err(e) = commands::logo::ensure_logo_derived_impl(&conn, &data_dir) {
+        eprintln!("Could not derive the logo images: {e}");
+    }
     Ok(AppState {
         db: Mutex::new(conn),
         data_dir,
@@ -129,6 +134,10 @@ pub fn run() {
             commands::assets::save_asset_bytes,
             commands::assets::read_asset_data_uri,
             commands::assets::remove_asset,
+            commands::logo::import_logo,
+            commands::logo::save_logo_bytes,
+            commands::logo::ensure_logo_derived,
+            commands::logo::remove_logo,
             commands::archive::archive_pdf,
             commands::archive::read_archive,
             commands::archive::archive_status,

src-tauri/src/logo.rs

@@ -0,0 +1,549 @@
+//! Logo import pipeline: decode, measure the ink box, trim, downscale and derive the print and
+//! knockout PNGs. Pure functions over bytes; storage lives in `commands::logo`.
+use image::codecs::png::{CompressionType, FilterType, PngEncoder};
+use image::imageops::{self, FilterType as ResizeFilter};
+use image::{DynamicImage, ImageFormat, ImageReader, RgbImage, RgbaImage};
+use serde::{Deserialize, Serialize};
+use std::io::Cursor;
+
+/// Largest accepted input file.
+pub const MAX_INPUT_BYTES: usize = 20 * 1024 * 1024;
+/// Largest accepted side of the decoded image, in pixels.
+const MAX_SIDE: u32 = 8192;
+/// The longer side of the derived print image never exceeds this.
+const PRINT_MAX_SIDE: u32 = 1200;
+/// Pixels with alpha at or below this are not ink (alpha logos).
+const INK_ALPHA: u8 = 32;
+/// An image counts as having transparency when any pixel is more transparent than this.
+const ALPHA_OPAQUE: u8 = 250;
+/// Alpha at or below this is treated as fully transparent when cleaning the print image.
+const ALPHA_EMPTY: u8 = 5;
+/// Colour distance from the background under which an opaque pixel is "empty".
+const BG_DISTANCE: i32 = 24;
+/// Rows and columns with fewer ink pixels than this are noise and do not widen the trim box.
+const MIN_LINE_INK: usize = 2;
+
+#[derive(Debug, thiserror::Error)]
+pub enum LogoError {
+    #[error("Use a PNG, JPEG or WebP image")]
+    Format,
+    #[error("The image is larger than 20 MB")]
+    TooLarge,
+    #[error("The image is larger than {MAX_SIDE} pixels on a side")]
+    Dimensions,
+    #[error("Could not read the image: {0}")]
+    Decode(String),
+    #[error("The image has no visible content")]
+    Empty,
+    #[error("Could not encode the logo: {0}")]
+    Encode(String),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum LogoKind {
+    Wordmark,
+    Mark,
+    Tall,
+}
+
+/// Measurements of the trimmed, downscaled print image. Stored as JSON in `app_settings.logo_meta`.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LogoMetrics {
+    pub width: u32,
+    pub height: u32,
+    pub aspect: f64,
+    pub ink_density: f64,
+    pub mean_color: [u8; 3],
+    pub kind: LogoKind,
+    pub has_alpha: bool,
+    pub opaque_background: bool,
+    pub source_width: u32,
+    pub source_height: u32,
+}
+
+#[derive(Debug)]
+pub struct LogoDerived {
+    pub print_png: Vec<u8>,
+    /// White ink with the original alpha; only for logos that have transparency.
+    pub knockout_png: Option<Vec<u8>>,
+    pub metrics: LogoMetrics,
+}
+
+/// File extension for a sniffed original: png, jpg or webp.
+pub fn sniff_extension(bytes: &[u8]) -> Result<&'static str, LogoError> {
+    sniff(bytes).map(|(_, ext)| ext)
+}
+
+fn sniff(bytes: &[u8]) -> Result<(ImageFormat, &'static str), LogoError> {
+    if bytes.starts_with(&[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A]) {
+        Ok((ImageFormat::Png, "png"))
+    } else if bytes.starts_with(&[0xFF, 0xD8, 0xFF]) {
+        Ok((ImageFormat::Jpeg, "jpg"))
+    } else if bytes.len() >= 12 && &bytes[0..4] == b"RIFF" && &bytes[8..12] == b"WEBP" {
+        Ok((ImageFormat::WebP, "webp"))
+    } else {
+        Err(LogoError::Format)
+    }
+}
+
+fn decode(bytes: &[u8]) -> Result<RgbaImage, LogoError> {
+    if bytes.len() > MAX_INPUT_BYTES {
+        return Err(LogoError::TooLarge);
+    }
+    let (format, _) = sniff(bytes)?;
+    let decode_err = |e: image::ImageError| LogoError::Decode(e.to_string());
+    let decoder = ImageReader::with_format(Cursor::new(bytes), format)
+        .into_decoder()
+        .map_err(decode_err)?;
+    // Check the declared size before allocating the pixels.
+    let (w, h) = image::ImageDecoder::dimensions(&decoder);
+    if w > MAX_SIDE || h > MAX_SIDE {
+        return Err(LogoError::Dimensions);
+    }
+    DynamicImage::from_decoder(decoder)
+        .map(|img| img.to_rgba8())
+        .map_err(decode_err)
+}
+
+/// Median of each channel over the four 4x4 corner patches.
+fn corner_background(img: &RgbaImage) -> [u8; 3] {
+    let (w, h) = img.dimensions();
+    let (pw, ph) = (4.min(w), 4.min(h));
+    let mut channels: [Vec<u8>; 3] = Default::default();
+    for (x0, y0) in [(0, 0), (w - pw, 0), (0, h - ph), (w - pw, h - ph)] {
+        for y in y0..y0 + ph {
+            for x in x0..x0 + pw {
+                let p = img.get_pixel(x, y).0;
+                for c in 0..3 {
+                    channels[c].push(p[c]);
+                }
+            }
+        }
+    }
+    let mut out = [0u8; 3];
+    for c in 0..3 {
+        channels[c].sort_unstable();
+        out[c] = channels[c][channels[c].len() / 2];
+    }
+    out
+}
+
+/// What counts as ink: opaque enough for alpha logos, far enough from the background otherwise.
+#[derive(Clone, Copy)]
+enum InkTest {
+    Alpha,
+    Background([u8; 3]),
+}
+
+impl InkTest {
+    fn is_ink(self, p: &[u8; 4]) -> bool {
+        match self {
+            InkTest::Alpha => p[3] > INK_ALPHA,
+            InkTest::Background(bg) => {
+                let d: i32 = (0..3).map(|c| (p[c] as i32 - bg[c] as i32).pow(2)).sum();
+                d > BG_DISTANCE * BG_DISTANCE
+            }
+        }
+    }
+}
+
+/// First and last index whose count reaches `MIN_LINE_INK`.
+fn span(counts: &[usize]) -> Option<(usize, usize)> {
+    let first = counts.iter().position(|&n| n >= MIN_LINE_INK)?;
+    let last = counts.iter().rposition(|&n| n >= MIN_LINE_INK)?;
+    Some((first, last))
+}
+
+fn premultiply(img: &mut RgbaImage) {
+    for p in img.pixels_mut() {
+        let a = p.0[3] as u32;
+        for c in 0..3 {
+            p.0[c] = ((p.0[c] as u32 * a + 127) / 255) as u8;
+        }
+    }
+}
+
+fn unpremultiply(img: &mut RgbaImage) {
+    for p in img.pixels_mut() {
+        let a = p.0[3] as u32;
+        if a == 0 {
+            continue;
+        }
+        for c in 0..3 {
+            p.0[c] = ((p.0[c] as u32 * 255 + a / 2) / a).min(255) as u8;
+        }
+    }
+}
+
+/// Lanczos3 downscale to at most `PRINT_MAX_SIDE`. Colours are premultiplied while resampling so
+/// transparent pixels do not bleed their (arbitrary) colour into the edges; the result is straight alpha.
+fn downscale(img: RgbaImage, has_alpha: bool) -> RgbaImage {
+    let (w, h) = img.dimensions();
+    let longer = w.max(h);
+    if longer <= PRINT_MAX_SIDE {
+        return img;
+    }
+    let scale = PRINT_MAX_SIDE as f64 / longer as f64;
+    let nw = ((w as f64 * scale).round() as u32).clamp(1, PRINT_MAX_SIDE);
+    let nh = ((h as f64 * scale).round() as u32).clamp(1, PRINT_MAX_SIDE);
+    let mut src = img;
+    if has_alpha {
+        premultiply(&mut src);
+    }
+    let mut out = imageops::resize(&src, nw, nh, ResizeFilter::Lanczos3);
+    if has_alpha {
+        unpremultiply(&mut out);
+    }
+    out
+}
+
+/// Exporters leave faint noise in "solid" and "empty" pixels (alpha 253 of 255, hidden colour under
+/// alpha 0). It is invisible but triples the PNG size, so snap near-solid alpha to solid, near-empty
+/// to empty, and drop the colour of empty pixels.
+fn clean_alpha(img: &mut RgbaImage) {
+    for p in img.pixels_mut() {
+        match p.0[3] {
+            a if a >= ALPHA_OPAQUE => p.0[3] = 255,
+            a if a <= ALPHA_EMPTY => p.0 = [0, 0, 0, 0],
+            _ => {}
+        }
+    }
+}
+
+/// Keep 64 levels per channel (steps of about 4/255, invisible in print). Anti-aliasing and encoder
+/// noise of +-1 otherwise makes flat colours incompressible: the Test Vendor logo drops from 149 KB to 75 KB.
+fn quantize_colour(img: &mut RgbaImage) {
+    for p in img.pixels_mut() {
+        for c in 0..3 {
+            p.0[c] = ((((p.0[c] as u32 * 63 + 127) / 255) * 255 + 31) / 63) as u8;
+        }
+    }
+}
+
+fn encode_png(img: &DynamicImage) -> Result<Vec<u8>, LogoError> {
+    let mut buf = Vec::new();
+    let encoder = PngEncoder::new_with_quality(&mut buf, CompressionType::Best, FilterType::Adaptive);
+    img.write_with_encoder(encoder)
+        .map_err(|e| LogoError::Encode(e.to_string()))?;
+    Ok(buf)
+}
+
+fn kind_for(aspect: f64) -> LogoKind {
+    if aspect >= 2.5 {
+        LogoKind::Wordmark
+    } else if aspect <= 0.6 {
+        LogoKind::Tall
+    } else {
+        LogoKind::Mark
+    }
+}
+
+/// Decode a logo, trim it to its ink box, and derive the print PNG, the knockout PNG and the metrics.
+pub fn process_logo(bytes: &[u8]) -> Result<LogoDerived, LogoError> {
+    let source = decode(bytes)?;
+    let (source_width, source_height) = source.dimensions();
+    let has_alpha = source.pixels().any(|p| p.0[3] < ALPHA_OPAQUE);
+    // The background estimate only drives measuring; no pixel is edited.
+    let test = if has_alpha {
+        InkTest::Alpha
+    } else {
+        InkTest::Background(corner_background(&source))
+    };
+
+    let mut rows = vec![0usize; source_height as usize];
+    let mut cols = vec![0usize; source_width as usize];
+    for (x, y, p) in source.enumerate_pixels() {
+        if test.is_ink(&p.0) {
+            rows[y as usize] += 1;
+            cols[x as usize] += 1;
+        }
+    }
+    let (Some((top, bottom)), Some((left, right))) = (span(&rows), span(&cols)) else {
+        return Err(LogoError::Empty);
+    };
+
+    let cropped = imageops::crop_imm(
+        &source,
+        left as u32,
+        top as u32,
+        (right - left + 1) as u32,
+        (bottom - top + 1) as u32,
+    )
+    .to_image();
+    let mut print = downscale(cropped, has_alpha);
+    if has_alpha {
+        clean_alpha(&mut print);
+    }
+    quantize_colour(&mut print);
+    let (width, height) = print.dimensions();
+
+    let (mut ink, mut sum) = (0u64, [0u64; 3]);
+    for p in print.pixels() {
+        if test.is_ink(&p.0) {
+            ink += 1;
+            for (total, channel) in sum.iter_mut().zip(p.0) {
+                *total += channel as u64;
+            }
+        }
+    }
+    let mean_color = if ink == 0 {
+        [0; 3]
+    } else {
+        [0, 1, 2].map(|c| ((sum[c] + ink / 2) / ink) as u8)
+    };
+    let aspect = width as f64 / height as f64;
+
+    let knockout_png = if has_alpha {
+        let mut white = print.clone();
+        for p in white.pixels_mut() {
+            p.0[0] = 255;
+            p.0[1] = 255;
+            p.0[2] = 255;
+        }
+        Some(encode_png(&DynamicImage::ImageRgba8(white))?)
+    } else {
+        None
+    };
+    let print_image = if has_alpha {
+        DynamicImage::ImageRgba8(print)
+    } else {
+        // No transparency to keep: RGB is smaller.
+        DynamicImage::ImageRgb8(RgbImage::from_fn(width, height, |x, y| {
+            let p = print.get_pixel(x, y).0;
+            image::Rgb([p[0], p[1], p[2]])
+        }))
+    };
+
+    Ok(LogoDerived {
+        print_png: encode_png(&print_image)?,
+        knockout_png,
+        metrics: LogoMetrics {
+            width,
+            height,
+            aspect,
+            ink_density: ink as f64 / (width as f64 * height as f64),
+            mean_color,
+            kind: kind_for(aspect),
+            has_alpha,
+            opaque_background: !has_alpha,
+            source_width,
+            source_height,
+        },
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use image::{codecs::jpeg::JpegEncoder, codecs::webp::WebPEncoder, ExtendedColorType, Rgba};
+
+    fn png_bytes(img: &RgbaImage) -> Vec<u8> {
+        let mut out = Vec::new();
+        DynamicImage::ImageRgba8(img.clone())
+            .write_to(&mut Cursor::new(&mut out), ImageFormat::Png)
+            .unwrap();
+        out
+    }
+
+    /// Transparent canvas with an opaque rectangle.
+    fn alpha_logo(w: u32, h: u32, rect: (u32, u32, u32, u32), color: [u8; 3]) -> RgbaImage {
+        let mut img = RgbaImage::from_pixel(w, h, Rgba([0, 0, 0, 0]));
+        let (x0, y0, rw, rh) = rect;
+        for y in y0..y0 + rh {
+            for x in x0..x0 + rw {
+                img.put_pixel(x, y, Rgba([color[0], color[1], color[2], 255]));
+            }
+        }
+        img
+    }
+
+    fn decode_png(bytes: &[u8]) -> RgbaImage {
+        image::load_from_memory_with_format(bytes, ImageFormat::Png).unwrap().to_rgba8()
+    }
+
+    #[test]
+    fn alpha_logo_is_trimmed_to_the_rect_without_padding() {
+        let img = alpha_logo(200, 100, (30, 20, 60, 25), [10, 20, 30]);
+        let out = process_logo(&png_bytes(&img)).unwrap();
+        let m = &out.metrics;
+        assert_eq!((m.width, m.height), (60, 25));
+        assert_eq!((m.source_width, m.source_height), (200, 100));
+        assert!(m.has_alpha && !m.opaque_background);
+        let printed = decode_png(&out.print_png);
+        assert_eq!(printed.dimensions(), (60, 25));
+        // Every edge pixel row/column is ink: nothing was left as padding.
+        assert!(printed.pixels().all(|p| p.0[3] == 255));
+        // Colours are quantised to 64 levels, so allow a few steps.
+        for (got, want) in m.mean_color.iter().zip([10i32, 20, 30]) {
+            assert!((*got as i32 - want).abs() <= 3, "{:?}", m.mean_color);
+        }
+    }
+
+    #[test]
+    fn noise_specks_do_not_widen_the_box() {
+        let mut img = alpha_logo(200, 100, (50, 30, 40, 20), [0, 0, 0]);
+        // Isolated single pixels far from the logo.
+        img.put_pixel(2, 2, Rgba([0, 0, 0, 255]));
+        img.put_pixel(197, 97, Rgba([0, 0, 0, 255]));
+        img.put_pixel(100, 3, Rgba([0, 0, 0, 255]));
+        let m = process_logo(&png_bytes(&img)).unwrap().metrics;
+        assert_eq!((m.width, m.height), (40, 20));
+    }
+
+    #[test]
+    fn faint_alpha_is_not_ink() {
+        let mut img = alpha_logo(100, 100, (40, 40, 20, 20), [0, 0, 0]);
+        // A soft shadow below the alpha threshold.
+        for y in 70..90 {
+            for x in 10..90 {
+                img.put_pixel(x, y, Rgba([0, 0, 0, 30]));
+            }
+        }
+        let m = process_logo(&png_bytes(&img)).unwrap().metrics;
+        assert_eq!((m.width, m.height), (20, 20));
+    }
+
+    #[test]
+    fn opaque_white_background_jpeg_is_trimmed_and_flagged() {
+        let mut img = RgbaImage::from_pixel(160, 120, Rgba([255, 255, 255, 255]));
+        for y in 40..80 {
+            for x in 30..130 {
+                img.put_pixel(x, y, Rgba([20, 40, 160, 255]));
+            }
+        }
+        let rgb = DynamicImage::ImageRgba8(img).to_rgb8();
+        let mut jpg = Vec::new();
+        JpegEncoder::new_with_quality(&mut jpg, 95)
+            .encode(rgb.as_raw(), 160, 120, ExtendedColorType::Rgb8)
+            .unwrap();
+
+        let out = process_logo(&jpg).unwrap();
+        let m = &out.metrics;
+        assert!(m.opaque_background && !m.has_alpha);
+        // JPEG ringing may move an edge by a pixel or two.
+        assert!((98..=102).contains(&m.width), "{}", m.width);
+        assert!((38..=42).contains(&m.height), "{}", m.height);
+        assert!(out.knockout_png.is_none());
+        // The input pixels are not edited: the printed corners are still the logo colour, not transparent.
+        let printed = image::load_from_memory_with_format(&out.print_png, ImageFormat::Png).unwrap();
+        assert!(!printed.color().has_alpha());
+    }
+
+    #[test]
+    fn lossless_webp_is_accepted() {
+        let img = alpha_logo(80, 60, (10, 10, 30, 30), [200, 0, 0]);
+        let mut webp = Vec::new();
+        WebPEncoder::new_lossless(&mut webp)
+            .encode(img.as_raw(), 80, 60, ExtendedColorType::Rgba8)
+            .unwrap();
+        assert_eq!(sniff_extension(&webp).unwrap(), "webp");
+        let m = process_logo(&webp).unwrap().metrics;
+        assert_eq!((m.width, m.height), (30, 30));
+        assert!(m.has_alpha);
+    }
+
+    #[test]
+    fn other_formats_and_garbage_are_rejected() {
+        let msg = "Use a PNG, JPEG or WebP image";
+        for bad in [
+            &b"GIF89a\x01\x00\x01\x00"[..],
+            b"<svg xmlns='http://www.w3.org/2000/svg'/>",
+            b"not an image at all",
+            b"",
+            b"RIFF\x00\x00\x00\x00WAVEfmt ",
+        ] {
+            assert_eq!(process_logo(bad).unwrap_err().to_string(), msg);
+        }
+        // Right magic, broken body.
+        let mut truncated = png_bytes(&alpha_logo(20, 20, (2, 2, 5, 5), [0; 3]));
+        truncated.truncate(30);
+        assert!(matches!(process_logo(&truncated), Err(LogoError::Decode(_))));
+    }
+
+    #[test]
+    fn oversized_input_and_dimensions_are_rejected() {
+        let mut big = vec![0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A];
+        big.resize(MAX_INPUT_BYTES + 1, 0);
+        assert!(matches!(process_logo(&big), Err(LogoError::TooLarge)));
+
+        // A blank image 8193 px wide compresses to a few KB, so it passes the byte cap.
+        let wide = RgbaImage::new(8193, 2);
+        assert!(matches!(process_logo(&png_bytes(&wide)), Err(LogoError::Dimensions)));
+    }
+
+    #[test]
+    fn blank_images_have_no_content() {
+        assert!(matches!(process_logo(&png_bytes(&RgbaImage::new(40, 40))), Err(LogoError::Empty)));
+        let white = RgbaImage::from_pixel(40, 40, Rgba([255, 255, 255, 255]));
+        assert!(matches!(process_logo(&png_bytes(&white)), Err(LogoError::Empty)));
+    }
+
+    #[test]
+    fn large_logos_are_downscaled_to_1200() {
+        let img = alpha_logo(3000, 1000, (10, 10, 2980, 980), [0, 0, 0]);
+        let out = process_logo(&png_bytes(&img)).unwrap();
+        let m = &out.metrics;
+        assert_eq!((m.width, m.height), (1200, 395));
+        assert_eq!((m.source_width, m.source_height), (3000, 1000));
+        assert_eq!(decode_png(&out.print_png).dimensions(), (1200, 395));
+        assert!((m.aspect - 2980.0 / 980.0).abs() < 0.01);
+    }
+
+    #[test]
+    fn density_aspect_and_kind() {
+        // Half of a 100 x 40 box is ink: left half filled.
+        let img = alpha_logo(100, 40, (0, 0, 50, 40), [0, 0, 0]);
+        // Trimming shrinks the box to the ink, so add a second block to keep the density at 0.5.
+        let mut img = img;
+        for y in 0..40 {
+            img.put_pixel(99, y, Rgba([0, 0, 0, 255]));
+            img.put_pixel(98, y, Rgba([0, 0, 0, 255]));
+        }
+        let m = process_logo(&png_bytes(&img)).unwrap().metrics;
+        assert_eq!((m.width, m.height), (100, 40));
+        assert!((m.aspect - 2.5).abs() < 1e-9);
+        assert_eq!(m.kind, LogoKind::Wordmark);
+        assert!((m.ink_density - 0.52).abs() < 1e-9, "{}", m.ink_density);
+
+        let square = alpha_logo(50, 50, (10, 10, 30, 30), [0; 3]);
+        assert_eq!(process_logo(&png_bytes(&square)).unwrap().metrics.kind, LogoKind::Mark);
+        let tall = alpha_logo(50, 100, (10, 10, 12, 40), [0; 3]);
+        assert_eq!(process_logo(&png_bytes(&tall)).unwrap().metrics.kind, LogoKind::Tall);
+        assert_eq!(kind_for(2.49), LogoKind::Mark);
+        assert_eq!(kind_for(0.6), LogoKind::Tall);
+    }
+
+    #[test]
+    fn knockout_is_white_with_the_original_alpha() {
+        let mut img = alpha_logo(60, 40, (5, 5, 40, 20), [30, 60, 90]);
+        // Anti-aliased edge column with partial alpha.
+        for y in 5..25 {
+            img.put_pixel(44, y, Rgba([30, 60, 90, 128]));
+        }
+        let out = process_logo(&png_bytes(&img)).unwrap();
+        let print = decode_png(&out.print_png);
+        let knock = decode_png(&out.knockout_png.expect("alpha logo has a knockout"));
+        assert_eq!(print.dimensions(), knock.dimensions());
+        for (a, b) in print.pixels().zip(knock.pixels()) {
+            assert_eq!(&b.0[..3], &[255, 255, 255]);
+            assert_eq!(a.0[3], b.0[3]);
+        }
+        assert!(knock.pixels().any(|p| p.0[3] == 128));
+    }
+
+    #[test]
+    fn sample_logo_is_trimmed_and_small() {
+        let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../public/brand/sample-wordmark-logo.png");
+        let bytes = std::fs::read(path).unwrap();
+        let out = process_logo(&bytes).unwrap();
+        let m = &out.metrics;
+        assert_eq!((m.source_width, m.source_height), (2172, 724));
+        assert!((4.5..=4.7).contains(&m.aspect), "aspect {}", m.aspect);
+        assert!((0.40..=0.46).contains(&m.ink_density), "density {}", m.ink_density);
+        assert_eq!(m.kind, LogoKind::Wordmark);
+        assert!(out.print_png.len() <= 120 * 1024, "print is {} bytes", out.print_png.len());
+        assert!(out.knockout_png.is_some());
+    }
+}

src-tauri/src/models.rs

@@ -29,6 +29,22 @@ pub struct Settings {
     /// Folder of the last export; owned by the backend, so saving settings never changes it.
     #[serde(default)]
     pub last_export_dir: String,
+    /// The untouched logo file the derived images came from.
+    #[serde(default)]
+    pub logo_original_path: Option<String>,
+    /// White-ink variant for dark surfaces; only for logos with transparency.
+    #[serde(default)]
+    pub logo_knockout_path: Option<String>,
+    /// LogoMetrics JSON; empty until the logo has been through the import pipeline.
+    #[serde(default)]
+    pub logo_meta: String,
+    /// Whether the logo already contains the business name: `auto`, `yes` or `no`.
+    #[serde(default = "default_logo_includes_name")]
+    pub logo_includes_name: String,
+}
+
+fn default_logo_includes_name() -> String {
+    "auto".to_string()
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]

src/components/LogoBranding.tsx

@@ -0,0 +1,165 @@
+import { useEffect, useState } from "react";
+import { Button, InlineLoading, InlineNotification, RadioButton, RadioButtonGroup } from "@carbon/react";
+import { TrashCan, Upload } from "@carbon/icons-react";
+import { open } from "@tauri-apps/plugin-dialog";
+import { api } from "../lib/api";
+import {
+  loadLogoImages,
+  logoFacts,
+  logoIncludesName,
+  parseLogoMeta,
+  type LogoAsset,
+  type LogoImages,
+  type LogoIncludesName,
+  type LogoSettings,
+} from "../lib/logo";
+import type { Settings } from "../lib/types";
+
+type LogoPatch = Pick<Settings, "logoPath" | "logoOriginalPath" | "logoKnockoutPath" | "logoMeta" | "logoIncludesName">;
+
+interface LogoBrandingProps {
+  /** Id prefix, so two instances on a page never share control ids. */
+  idPrefix: string;
+  value: LogoSettings;
+  onChange: (patch: Partial<LogoPatch>) => void;
+  disabled?: boolean;
+}
+
+/**
+ * Logo upload with the pipeline's result: the trimmed logo on a white and on a dark surface, what
+ * was measured, and whether the logo already contains the business name.
+ */
+export function LogoBranding({ idPrefix, value, onChange, disabled }: LogoBrandingProps) {
+  const [images, setImages] = useState<LogoImages | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let active = true;
+    if (!value.logoPath) {
+      setImages(null);
+      return;
+    }
+    loadLogoImages(value, api.readAssetDataUri)
+      .then((loaded) => active && setImages(loaded))
+      .catch(() => active && setImages(null));
+    return () => {
+      active = false;
+    };
+  }, [value.logoPath, value.logoKnockoutPath]);
+
+  const pick = async () => {
+    setError(null);
+    try {
+      const selected = await open({
+        multiple: false,
+        directory: false,
+        filters: [{ name: "Images", extensions: ["png", "jpg", "jpeg", "webp"] }],
+      });
+      if (typeof selected !== "string") return;
+      setBusy(true);
+      const asset: LogoAsset = await api.importLogo(selected);
+      onChange({
+        logoPath: asset.printPath,
+        logoOriginalPath: asset.originalPath,
+        logoKnockoutPath: asset.knockoutPath,
+        logoMeta: JSON.stringify(asset.metrics),
+      });
+    } catch (e) {
+      setError(String(e));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const remove = async () => {
+    setError(null);
+    try {
+      await api.removeLogo();
+      onChange({ logoPath: null, logoOriginalPath: null, logoKnockoutPath: null, logoMeta: "", logoIncludesName: "auto" });
+    } catch (e) {
+      setError(String(e));
+    }
+  };
+
+  const meta = parseLogoMeta(value.logoMeta);
+  const automaticYes = logoIncludesName("auto", meta?.kind ?? null);
+
+  return (
+    <div className="voiced-stack">
+      <div className="voiced-muted">Vendor logo (PNG, JPEG or WebP). A transparent PNG works best.</div>
+
+      {value.logoPath ? (
+        <div className="voiced-logo-preview">
+          <figure className="voiced-logo-preview__item">
+            <div className="voiced-logo-preview__surface voiced-logo-preview__surface--light">
+              {images ? <img src={images.printUri} alt="Logo on a white background" /> : <InlineLoading />}
+            </div>
+            <figcaption className="voiced-muted">On white</figcaption>
+          </figure>
+          <figure className="voiced-logo-preview__item">
+            <div className="voiced-logo-preview__surface voiced-logo-preview__surface--dark">
+              {images ? (
+                images.knockoutUri ? (
+                  <img src={images.knockoutUri} alt="White logo on a dark background" />
+                ) : (
+                  <span className="voiced-logo-preview__chip">
+                    <img src={images.printUri} alt="Logo on a white chip over a dark background" />
+                  </span>
+                )
+              ) : (
+                <InlineLoading />
+              )}
+            </div>
+            <figcaption className="voiced-muted">
+              {images && !images.knockoutUri ? "On dark (white chip)" : "On dark"}
+            </figcaption>
+          </figure>
+        </div>
+      ) : (
+        <div className="voiced-muted">{busy ? <InlineLoading description="Importing" /> : "No logo selected"}</div>
+      )}
+
+      {meta ? <div className="voiced-muted">{logoFacts(meta)}</div> : null}
+
+      {meta?.opaqueBackground ? (
+        <InlineNotification
+          kind="warning"
+          lowContrast
+          hideCloseButton
+          title="Solid background"
+          subtitle="This logo has a solid background. A transparent PNG gives better results on coloured templates."
+        />
+      ) : null}
+
+      <div className="voiced-header-action">
+        <Button kind="tertiary" size="sm" renderIcon={Upload} onClick={pick} disabled={disabled || busy}>
+          {value.logoPath ? "Replace logo" : "Choose image"}
+        </Button>
+        {value.logoPath ? (
+          <Button kind="ghost" size="sm" renderIcon={TrashCan} onClick={remove} disabled={disabled || busy}>
+            Remove
+          </Button>
+        ) : null}
+        {busy && value.logoPath ? <InlineLoading description="Importing" /> : null}
+      </div>
+
+      {error ? <InlineNotification kind="error" lowContrast hideCloseButton title="Could not use that logo" subtitle={error} /> : null}
+
+      {value.logoPath ? (
+        <RadioButtonGroup
+          legendText="Logo already includes the business name"
+          name={`${idPrefix}-logoIncludesName`}
+          orientation="horizontal"
+          valueSelected={value.logoIncludesName}
+          helperText={`Automatic treats ${automaticYes ? "this logo as including the name" : "this logo as a mark without the name"}.`}
+          onChange={(next) => onChange({ logoIncludesName: next as LogoIncludesName })}
+        >
+          <RadioButton id={`${idPrefix}-lin-auto`} labelText="Automatic" value="auto" />
+          <RadioButton id={`${idPrefix}-lin-yes`} labelText="Yes" value="yes" />
+          <RadioButton id={`${idPrefix}-lin-no`} labelText="No" value="no" />
+        </RadioButtonGroup>
+      ) : null}
+    </div>
+  );
+}

src/lib/api.ts

@@ -9,6 +9,7 @@ import type {
   InvoiceSummary,
   Settings,
 } from "./types";
+import type { LogoAsset } from "./logo";
 
 export interface ArchiveStatus {
   archived: boolean;
@@ -52,6 +53,11 @@ export const api = {
     invoke<string>("import_asset", { sourcePath, kind }),
   saveAssetBytes: (kind: string, fileName: string, dataBase64: string) =>
     invoke<string>("save_asset_bytes", { kind, fileName, dataBase64 }),
+  importLogo: (sourcePath: string) => invoke<LogoAsset>("import_logo", { sourcePath }),
+  saveLogoBytes: (fileName: string, dataBase64: string) =>
+    invoke<LogoAsset>("save_logo_bytes", { fileName, dataBase64 }),
+  ensureLogoDerived: () => invoke<Settings>("ensure_logo_derived"),
+  removeLogo: () => invoke<Settings>("remove_logo"),
   readAssetDataUri: (path: string) => invoke<string>("read_asset_data_uri", { path }),
   removeAsset: (path: string) => invoke<void>("remove_asset", { path }),
 

src/lib/logo.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it, vi } from "vitest";
+import { vendorFromSnapshot } from "../pdf/model/vendor";
+import { loadLogoImages, logoFacts, logoForModel, logoIncludesName, parseLogoMeta, type LogoMeta } from "./logo";
+import type { Settings } from "./types";
+
+const meta: LogoMeta = {
+  width: 1200,
+  height: 261,
+  aspect: 4.6,
+  inkDensity: 0.43,
+  meanColor: [13, 35, 63],
+  kind: "wordmark",
+  hasAlpha: true,
+  opaqueBackground: false,
+  sourceWidth: 2172,
+  sourceHeight: 724,
+};
+
+const vendor = (over: Partial<Settings> = {}) =>
+  ({ logoPath: "assets/p.png", logoKnockoutPath: "assets/k.png", logoMeta: JSON.stringify(meta), logoIncludesName: "auto", ...over }) as Settings;
+
+// 1 x 1 PNG header with a 40 x 10 size, enough for imageSizeFromDataUri.
+const png40x10 = () => {
+  const b = new Uint8Array(24);
+  b.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  b[19] = 40;
+  b[23] = 10;
+  return `data:image/png;base64,${btoa(String.fromCharCode(...b))}`;
+};
+
+describe("parseLogoMeta", () => {
+  it("round-trips the backend JSON", () => {
+    expect(parseLogoMeta(JSON.stringify(meta))).toEqual(meta);
+  });
+  it("returns null for empty, malformed or incomplete metrics", () => {
+    expect(parseLogoMeta("")).toBeNull();
+    expect(parseLogoMeta(null)).toBeNull();
+    expect(parseLogoMeta("{nope")).toBeNull();
+    expect(parseLogoMeta("null")).toBeNull();
+    expect(parseLogoMeta("{}")).toBeNull();
+    expect(parseLogoMeta(JSON.stringify({ ...meta, kind: "blob" }))).toBeNull();
+    expect(parseLogoMeta(JSON.stringify({ ...meta, aspect: 0 }))).toBeNull();
+  });
+});
+
+describe("logoIncludesName", () => {
+  it("resolves Automatic from the kind", () => {
+    expect(logoIncludesName("auto", "wordmark")).toBe(true);
+    expect(logoIncludesName("auto", "mark")).toBe(false);
+    expect(logoIncludesName("auto", null)).toBe(false);
+    expect(logoIncludesName("yes", "mark")).toBe(true);
+    expect(logoIncludesName("no", "wordmark")).toBe(false);
+  });
+});
+
+describe("logoForModel", () => {
+  it("uses the stored metrics and the knockout when the logo has alpha", () => {
+    const logo = logoForModel(vendor(), { printUri: "data:p", knockoutUri: "data:k" });
+    expect(logo).toEqual({
+      dataUri: "data:p",
+      width: 1200,
+      height: 261,
+      aspect: 4.6,
+      density: 0.43,
+      kind: "wordmark",
+      includesName: true,
+      hasKnockout: true,
+      knockoutDataUri: "data:k",
+    });
+  });
+  it("has no knockout for an opaque logo or when the file is missing", () => {
+    const opaque = JSON.stringify({ ...meta, hasAlpha: false, opaqueBackground: true });
+    expect(logoForModel(vendor({ logoMeta: opaque }), { printUri: "data:p", knockoutUri: "data:k" })).toMatchObject({ hasKnockout: false });
+    const missing = logoForModel(vendor(), { printUri: "data:p", knockoutUri: null });
+    expect(missing?.hasKnockout).toBe(false);
+    expect(missing).not.toHaveProperty("knockoutDataUri");
+  });
+  it("honours the includes-name override", () => {
+    expect(logoForModel(vendor({ logoIncludesName: "no" }), { printUri: "p", knockoutUri: null })?.includesName).toBe(false);
+  });
+  it("falls back to the image size for a legacy logo without metrics", () => {
+    const logo = logoForModel(vendor({ logoMeta: "" }), { printUri: png40x10(), knockoutUri: "data:k" });
+    expect(logo).toMatchObject({ width: 40, height: 10, aspect: 4, kind: "wordmark", includesName: true, hasKnockout: false });
+  });
+  it("is null without images", () => {
+    expect(logoForModel(vendor(), null)).toBeNull();
+  });
+});
+
+describe("loadLogoImages", () => {
+  it("reads print and knockout, tolerating a missing knockout", async () => {
+    const read = vi.fn(async (p: string) => {
+      if (p === "assets/k.png") throw new Error("gone");
+      return `uri:${p}`;
+    });
+    expect(await loadLogoImages(vendor(), read)).toEqual({ printUri: "uri:assets/p.png", knockoutUri: null });
+    expect(await loadLogoImages(vendor({ logoPath: null }), read)).toBeNull();
+  });
+});
+
+describe("logoFacts", () => {
+  it("summarises the logo", () => {
+    expect(logoFacts(meta)).toBe("Wordmark • 4.6:1 • transparent background");
+    expect(logoFacts({ ...meta, kind: "tall", aspect: 0.5, hasAlpha: false })).toBe("Tall logo • 1:2.0 • solid background");
+  });
+});
+
+describe("vendorFromSnapshot logo keys", () => {
+  const live = vendor({ logoMeta: JSON.stringify(meta), logoKnockoutPath: "assets/live-k.png", logoIncludesName: "yes" });
+  it("does not lend live logo metrics to a snapshot from before the pipeline", () => {
+    const old = vendorFromSnapshot(JSON.stringify({ vendorName: "A", logoPath: "assets/old.png" }), live);
+    expect(old.logoPath).toBe("assets/old.png");
+    expect(old.logoMeta).toBe("");
+    expect(old.logoKnockoutPath).toBeNull();
+    expect(old.logoIncludesName).toBe("auto");
+  });
+  it("uses the frozen values when present", () => {
+    const snap = JSON.stringify({ logoPath: "assets/p.png", logoKnockoutPath: "assets/k.png", logoMeta: "{}", logoIncludesName: "no" });
+    expect(vendorFromSnapshot(snap, live)).toMatchObject({ logoKnockoutPath: "assets/k.png", logoMeta: "{}", logoIncludesName: "no" });
+  });
+});

src/lib/logo.ts

@@ -0,0 +1,128 @@
+import type { LogoInput } from "../pdf/model/build";
+import { imageSizeFromDataUri } from "./imageSize";
+import type { Settings } from "./types";
+
+export type LogoKind = "wordmark" | "mark" | "tall";
+export type LogoIncludesName = "auto" | "yes" | "no";
+
+/** The metrics the Rust logo pipeline stores as JSON in `settings.logoMeta`. */
+export interface LogoMeta {
+  width: number;
+  height: number;
+  aspect: number;
+  inkDensity: number;
+  meanColor: [number, number, number];
+  kind: LogoKind;
+  hasAlpha: boolean;
+  opaqueBackground: boolean;
+  sourceWidth: number;
+  sourceHeight: number;
+}
+
+/** What the backend returns for an imported logo (paths are relative to the data dir). */
+export interface LogoAsset {
+  originalPath: string;
+  printPath: string;
+  knockoutPath: string | null;
+  metrics: LogoMeta;
+}
+
+export type LogoSettings = Pick<Settings, "logoPath" | "logoKnockoutPath" | "logoMeta" | "logoIncludesName">;
+
+/** The loaded print image and, when the logo has transparency, its white knockout. */
+export interface LogoImages {
+  printUri: string;
+  knockoutUri: string | null;
+}
+
+/** A logo with no readable size is fitted as if it filled Classic's 170 x 54 box. */
+const UNKNOWN_LOGO_SIZE = { width: 170, height: 54 };
+/** Ink density assumed for a logo that never went through the pipeline. */
+const UNKNOWN_INK_DENSITY = 0.5;
+
+const KINDS: readonly string[] = ["wordmark", "mark", "tall"];
+
+const isPositive = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n) && n > 0;
+
+export function parseLogoMeta(json: string | null | undefined): LogoMeta | null {
+  if (!json) return null;
+  try {
+    const m = JSON.parse(json) as Partial<LogoMeta> | null;
+    if (!m || typeof m !== "object") return null;
+    if (!isPositive(m.width) || !isPositive(m.height) || !isPositive(m.aspect)) return null;
+    if (typeof m.inkDensity !== "number" || !Number.isFinite(m.inkDensity)) return null;
+    if (typeof m.kind !== "string" || !KINDS.includes(m.kind)) return null;
+    return {
+      width: m.width,
+      height: m.height,
+      aspect: m.aspect,
+      inkDensity: m.inkDensity,
+      meanColor: Array.isArray(m.meanColor) && m.meanColor.length === 3 ? (m.meanColor as [number, number, number]) : [0, 0, 0],
+      kind: m.kind as LogoKind,
+      hasAlpha: Boolean(m.hasAlpha),
+      opaqueBackground: Boolean(m.opaqueBackground),
+      sourceWidth: Number(m.sourceWidth) || m.width,
+      sourceHeight: Number(m.sourceHeight) || m.height,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** "Automatic" means a wordmark already carries the business name. */
+export function logoIncludesName(setting: string | undefined, kind: LogoKind | null): boolean {
+  if (setting === "yes") return true;
+  if (setting === "no") return false;
+  return kind === "wordmark";
+}
+
+/** The render-model logo from the loaded images and the stored metrics, or from the image itself for a legacy logo. */
+export function logoForModel(vendor: LogoSettings, images: LogoImages | null): LogoInput | null {
+  if (!images) return null;
+  const meta = parseLogoMeta(vendor.logoMeta);
+  const knockoutDataUri = meta?.hasAlpha ? images.knockoutUri : null;
+  const hasKnockout = Boolean(knockoutDataUri);
+  if (meta) {
+    return {
+      dataUri: images.printUri,
+      width: meta.width,
+      height: meta.height,
+      aspect: meta.aspect,
+      density: meta.inkDensity,
+      kind: meta.kind,
+      includesName: logoIncludesName(vendor.logoIncludesName, meta.kind),
+      hasKnockout,
+      ...(hasKnockout ? { knockoutDataUri: knockoutDataUri as string } : {}),
+    };
+  }
+  const size = imageSizeFromDataUri(images.printUri) ?? UNKNOWN_LOGO_SIZE;
+  const aspect = size.width / size.height;
+  const kind: LogoKind = aspect >= 2.5 ? "wordmark" : aspect <= 0.6 ? "tall" : "mark";
+  return {
+    dataUri: images.printUri,
+    ...size,
+    aspect,
+    density: UNKNOWN_INK_DENSITY,
+    kind,
+    includesName: logoIncludesName(vendor.logoIncludesName, kind),
+    hasKnockout: false,
+  };
+}
+
+/** Loads the print and knockout images a vendor's logo settings point at. A missing knockout is not an error. */
+export async function loadLogoImages(
+  vendor: Pick<Settings, "logoPath" | "logoKnockoutPath">,
+  read: (path: string) => Promise<string>,
+): Promise<LogoImages | null> {
+  if (!vendor.logoPath) return null;
+  const printUri = await read(vendor.logoPath);
+  const knockoutUri = vendor.logoKnockoutPath ? await read(vendor.logoKnockoutPath).catch(() => null) : null;
+  return { printUri, knockoutUri };
+}
+
+/** "Wordmark • 4.6:1 • transparent background" */
+export function logoFacts(meta: LogoMeta): string {
+  const kind = { wordmark: "Wordmark", mark: "Mark", tall: "Tall logo" }[meta.kind];
+  const ratio = meta.aspect >= 1 ? `${meta.aspect.toFixed(1)}:1` : `1:${(1 / meta.aspect).toFixed(1)}`;
+  return [kind, ratio, meta.hasAlpha ? "transparent background" : "solid background"].join(" • ");
+}

src/lib/pdf.tsx

@@ -5,13 +5,10 @@ import { vendorFromSnapshot } from "../pdf/model/vendor";
 import { Superseded } from "../pdf/render/client";
 import type { RenderResult } from "../pdf/render/jobs";
 import { api } from "./api";
-import { imageSizeFromDataUri } from "./imageSize";
+import { loadLogoImages, logoForModel, type LogoImages } from "./logo";
 import { getRenderClient, nextRenderJobId } from "./renderClient";
 import type { BankAccount, Invoice, Settings } from "./types";
 
-/** A logo with no readable size is fitted as if it filled Classic's 170 x 54 box. */
-const UNKNOWN_LOGO_SIZE = { width: 170, height: 54 };
-
 /**
  * The render model for an invoice whose images are already loaded (the live preview caches them).
  * Supplier and bank come from the snapshots frozen at issue; live settings are only a fallback.
@@ -20,14 +17,14 @@ export function modelFromAssets(
   invoice: Invoice,
   settings: Settings,
   bank: BankAccount | null,
-  logoUri: string | null,
+  logoImages: LogoImages | null,
   signatureDataUri: string | null,
 ): RenderModel {
   return buildRenderModel({
     invoice,
     vendor: settings,
     bank,
-    logo: logoUri ? { dataUri: logoUri, ...(imageSizeFromDataUri(logoUri) ?? UNKNOWN_LOGO_SIZE) } : null,
+    logo: logoForModel(vendorFromSnapshot(invoice.vendorSnapshot, settings), logoImages),
     signatureDataUri,
     appVersion: pkg.version,
   });
@@ -36,9 +33,9 @@ export function modelFromAssets(
 /** Loads the invoice's logo and signature, then builds its render model. */
 export async function buildModelForInvoice(invoice: Invoice, settings: Settings, bank: BankAccount | null): Promise<RenderModel> {
   const vendor = vendorFromSnapshot(invoice.vendorSnapshot, settings);
-  const logoUri = vendor.logoPath ? await api.readAssetDataUri(vendor.logoPath) : null;
+  const logoImages = await loadLogoImages(vendor, api.readAssetDataUri);
   const signatureDataUri = invoice.signaturePath ? await api.readAssetDataUri(invoice.signaturePath) : null;
-  return modelFromAssets(invoice, settings, bank, logoUri, signatureDataUri);
+  return modelFromAssets(invoice, settings, bank, logoImages, signatureDataUri);
 }
 
 /** Page setup for an invoice: what was frozen at issue, else the user's current default. */

src/lib/previewInvoice.ts

@@ -40,6 +40,9 @@ export function vendorSnapshotJson(settings: Settings): string {
     vendorGstin: settings.gstRegistration === "unregistered" ? "" : settings.vendorGstin.trim(),
     vendorStateCode: settings.vendorStateCode,
     logoPath: settings.logoPath,
+    logoKnockoutPath: settings.logoKnockoutPath,
+    logoMeta: settings.logoMeta,
+    logoIncludesName: settings.logoIncludesName,
     signaturePath: settings.signaturePath,
     gstRegistration: settings.gstRegistration,
     signatoryName: settings.signatoryName,

src/lib/types.ts

@@ -27,6 +27,14 @@ export interface Settings {
   renderPrefs: string;
   /** Folder of the last export; kept by the backend (saving settings does not change it). */
   lastExportDir?: string;
+  /** The untouched logo file the derived images came from. */
+  logoOriginalPath: string | null;
+  /** White-ink variant for dark surfaces; only for logos with transparency. */
+  logoKnockoutPath: string | null;
+  /** LogoMeta JSON from the import pipeline; empty until the logo has been through it. */
+  logoMeta: string;
+  /** Whether the logo already contains the business name. Automatic means a wordmark does. */
+  logoIncludesName: "auto" | "yes" | "no";
 }
 
 export interface BankAccount {

src/pdf/model/build.test.ts

@@ -12,6 +12,10 @@ const vendor: Settings = {
   vendorGstin: "",
   vendorStateCode: "29",
   logoPath: null,
+  logoOriginalPath: null,
+  logoKnockoutPath: null,
+  logoMeta: "",
+  logoIncludesName: "auto",
   signaturePath: null,
   defaultBankId: 1,
   defaultTaxRate: 18,
@@ -229,7 +233,17 @@ describe("cancelled and logo", () => {
     expect(make({ status: "draft" }).cancelled).toBe(false);
   });
   it("passes the logo and signature through, and keeps null when absent", () => {
-    const logo = { dataUri: "data:image/png;base64,AA==", width: 200, height: 40 };
+    const logo = {
+      dataUri: "data:image/png;base64,AA==",
+      width: 200,
+      height: 40,
+      aspect: 5,
+      density: 0.43,
+      kind: "wordmark" as const,
+      includesName: true,
+      hasKnockout: true,
+      knockoutDataUri: "data:image/png;base64,CC==",
+    };
     const m = make({}, {}, { logo, signatureDataUri: "data:image/png;base64,BB==" });
     expect(m.logo).toEqual(logo);
     expect(m.signature.dataUri).toBe("data:image/png;base64,BB==");

src/pdf/model/build.ts

@@ -11,9 +11,21 @@ import { sanitize, splitLines } from "./text";
 import { bankFromSnapshot, vendorFromSnapshot } from "./vendor";
 
 export interface LogoInput {
+  /** The trimmed print image. */
   dataUri: string;
+  /** Pixel size of `dataUri`. */
   width: number;
   height: number;
+  /** Width / height of the ink box. */
+  aspect: number;
+  /** Share of the box that is ink, 0 to 1. */
+  density: number;
+  kind: "wordmark" | "mark" | "tall";
+  /** The logo already carries the business name (the user's setting, resolved from Automatic). */
+  includesName: boolean;
+  /** A white-ink variant exists, for dark surfaces. */
+  hasKnockout?: boolean;
+  knockoutDataUri?: string;
 }
 
 export interface BuildInput {

src/pdf/model/vendor.ts

@@ -7,7 +7,15 @@ import type { BankAccount, Settings } from "../../lib/types";
 export function vendorFromSnapshot(snapshot: string | undefined, live: Settings): Settings {
   if (!snapshot) return live;
   try {
-    return { ...live, ...(JSON.parse(snapshot) as Partial<Settings>) };
+    const frozen = JSON.parse(snapshot) as Partial<Settings>;
+    // Snapshots from before the logo pipeline lack these keys; the live values describe a different logo.
+    return {
+      ...live,
+      logoKnockoutPath: null,
+      logoMeta: "",
+      logoIncludesName: "auto",
+      ...frozen,
+    };
   } catch {
     return live;
   }

src/pdf/templates/harness.ts

@@ -38,6 +38,10 @@ const baseVendor: Settings = {
   vendorGstin: "",
   vendorStateCode: "29",
   logoPath: null,
+  logoOriginalPath: null,
+  logoKnockoutPath: null,
+  logoMeta: "",
+  logoIncludesName: "auto",
   signaturePath: null,
   defaultBankId: 1,
   defaultTaxRate: 18,
@@ -136,12 +140,13 @@ export function fixtureLogo(kind: LogoKind): LogoInput | null {
     if (kind === "real") {
       // 2172 x 724: the untrimmed Test Vendor logo, a 3:1 aspect.
       const png = readFileSync(path.resolve(process.cwd(), "public/brand/sample-wordmark-logo.png"));
-      hit = { dataUri: dataUri(png), width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
+      const [width, height] = [png.readUInt32BE(16), png.readUInt32BE(20)];
+      hit = { dataUri: dataUri(png), width, height, aspect: width / height, density: 0.21, kind: "wordmark", includesName: true };
     } else if (kind === "wide") {
       // The trimmed Test Vendor ink box is 4.6:1.
-      hit = { dataUri: dataUri(solidPng(460, 100)), width: 460, height: 100 };
+      hit = { dataUri: dataUri(solidPng(460, 100)), width: 460, height: 100, aspect: 4.6, density: 1, kind: "wordmark", includesName: true };
     } else {
-      hit = { dataUri: dataUri(solidPng(120, 120)), width: 120, height: 120 };
+      hit = { dataUri: dataUri(solidPng(120, 120)), width: 120, height: 120, aspect: 1, density: 1, kind: "mark", includesName: false };
     }
     cache.set(kind, hit);
   }

src/pdf/testing/selfTestFixtures.ts

@@ -28,6 +28,10 @@ const VENDOR: Settings = {
   vendorGstin: "",
   vendorStateCode: "29",
   logoPath: null,
+  logoOriginalPath: null,
+  logoKnockoutPath: null,
+  logoMeta: "",
+  logoIncludesName: "auto",
   signaturePath: null,
   defaultBankId: 1,
   defaultTaxRate: 18,

src/styles/carbon.scss

@@ -396,3 +396,59 @@ body {
   white-space: pre-wrap;
   overflow-wrap: anywhere;
 }
+
+/* ---------- Logo preview (Settings -> Branding) ---------- */
+.voiced-logo-preview {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+}
+
+.voiced-logo-preview__item {
+  margin: 0;
+  width: 14rem;
+}
+
+.voiced-logo-preview__surface {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  height: 6rem;
+  padding: 1rem;
+  border: 1px solid var(--cds-border-subtle-01);
+  overflow: hidden;
+
+  img {
+    display: block;
+    max-width: 100%;
+    max-height: 4rem;
+    object-fit: contain;
+  }
+}
+
+.voiced-logo-preview__surface--light {
+  background: #ffffff;
+}
+
+.voiced-logo-preview__surface--dark {
+  background: #161616;
+}
+
+.voiced-logo-preview__chip {
+  display: flex;
+  box-sizing: border-box;
+  max-width: 100%;
+  padding: 0.5rem 0.75rem;
+  background: #ffffff;
+  border-radius: 0.5rem;
+
+  img {
+    max-height: 3rem;
+  }
+}
+
+.voiced-logo-preview__item figcaption {
+  margin-top: 0.5rem;
+  font-size: 0.75rem;
+}

src/views/AppSettings.tsx

@@ -19,6 +19,7 @@ import {
   TableRow,
   TextArea,
   TextInput,
+  Tile,
   Toggle,
 } from "@carbon/react";
 import { Add, Save, TrashCan } from "@carbon/icons-react";
@@ -33,6 +34,7 @@ import {
 } from "../lib/types";
 import { emailError, ifscError, panError, phoneError, vendorGstinError } from "../lib/validators";
 import { ImagePicker } from "../components/ImagePicker";
+import { LogoBranding } from "../components/LogoBranding";
 import DiagnosticsPanel from "../components/DiagnosticsPanel";
 
 const blankBank = (): BankAccount => ({
@@ -264,14 +266,6 @@ export default function AppSettings({
               onChange={(e) => set("signatoryDesignation", e.target.value)}
             />
           </Column>
-          <Column sm={4} md={8} lg={8}>
-            <ImagePicker
-              kind="logo"
-              label="Vendor logo"
-              value={form.logoPath}
-              onChange={(path) => set("logoPath", path)}
-            />
-          </Column>
           <Column sm={4} md={8} lg={8}>
             <ImagePicker
               kind="signature"
@@ -283,6 +277,18 @@ export default function AppSettings({
         </Grid>
       </section>
 
+      <section className="voiced-stack" style={{ marginBottom: "2.5rem" }}>
+        <h3>Branding</h3>
+        <Tile>
+          <LogoBranding
+            idPrefix="s"
+            value={form}
+            onChange={(patch) => setForm((prev) => ({ ...prev, ...patch }))}
+            disabled={busy}
+          />
+        </Tile>
+      </section>
+
       <section className="voiced-stack" style={{ marginBottom: "2.5rem" }}>
         <h3>Defaults</h3>
         <Grid narrow>

src/views/NewInvoice.tsx

@@ -65,6 +65,7 @@ import { loadExportMode } from "../lib/exportMode";
 import type { ExportMode } from "../lib/filename";
 import { parsePrefs, type RenderPrefsV1 } from "../pdf/model/prefs";
 import { ImagePicker } from "../components/ImagePicker";
+import { loadLogoImages, type LogoImages } from "../lib/logo";
 
 // pdf.js is only needed once a preview exists, so it loads on demand.
 const PdfPreview = lazy(() => import("../components/PdfPreview"));
@@ -135,7 +136,7 @@ export default function NewInvoice({ settings, onSettingsChange, active, onActiv
   const [signaturePath, setSignaturePath] = useState<string | null>(settings.signaturePath);
   const [notes, setNotes] = useState("");
 
-  const [logoUri, setLogoUri] = useState<string | null>(null);
+  const [logoImages, setLogoImages] = useState<LogoImages | null>(null);
   const [signatureUri, setSignatureUri] = useState<string | null>(null);
 
   const [saving, setSaving] = useState(false);
@@ -196,14 +197,16 @@ export default function NewInvoice({ settings, onSettingsChange, active, onActiv
   useEffect(() => {
     let active = true;
     if (!settings.logoPath) {
-      setLogoUri(null);
+      setLogoImages(null);
       return;
     }
-    api.readAssetDataUri(settings.logoPath).then((uri) => active && setLogoUri(uri)).catch(() => {});
+    loadLogoImages(settings, api.readAssetDataUri)
+      .then((images) => active && setLogoImages(images))
+      .catch(() => {});
     return () => {
       active = false;
     };
-  }, [settings.logoPath]);
+  }, [settings.logoPath, settings.logoKnockoutPath]);
 
   useEffect(() => {
     let active = true;
@@ -365,8 +368,8 @@ export default function NewInvoice({ settings, onSettingsChange, active, onActiv
         settings,
         bank,
       );
-    return modelFromAssets(invoice, settings, bank, logoUri, signatureUri);
+    return modelFromAssets(invoice, settings, bank, logoImages, signatureUri);
-  }, [active, issued, invoiceDate, dueDate, clientId, clientName, clientAddress, clientGstin, poNumber, placeOfSupply, discount, taxRate, reverseCharge, signaturePath, notes, items, number, settings, bank, logoUri, signatureUri]);
+  }, [active, issued, invoiceDate, dueDate, clientId, clientName, clientAddress, clientGstin, poNumber, placeOfSupply, discount, taxRate, reverseCharge, signaturePath, notes, items, number, settings, bank, logoImages, signatureUri]);
   const updateItem = (index: number, patch: Partial<InvoiceItem>) =>
     setItems((prev) => prev.map((item, i) => (i === index ? { ...item, ...patch } : item)));
 

src/views/Onboarding.tsx

@@ -19,6 +19,7 @@ import type { BankAccount, GstRegistration, Settings, TaxType } from "../lib/typ
 import { INDIAN_STATES } from "../lib/types";
 import { emailError, ifscError, panError, phoneError, vendorGstinError } from "../lib/validators";
 import { ImagePicker } from "../components/ImagePicker";
+import { LogoBranding } from "../components/LogoBranding";
 
 interface OnboardingProps {
   initial: Settings;
@@ -219,11 +220,11 @@ export default function Onboarding({ initial, onDone }: OnboardingProps) {
       content: (
         <Grid narrow>
           <Column sm={4} md={8} lg={12}>
-            <ImagePicker
+            <LogoBranding
-              kind="logo"
+              idPrefix="o"
-              label="Vendor logo (shown on the invoice header)"
+              value={form}
-              value={form.logoPath}
+              onChange={(patch) => setForm((prev) => ({ ...prev, ...patch }))}
-              onChange={(path) => set("logoPath", path)}
+              disabled={saving}
             />
           </Column>
           <Column sm={4} md={8} lg={12}>