From 74cf2d8fb8dd5ed2ee046dbb17ee50c53060dcb2 Mon Sep 17 00:00:00 2001 From: gulian Date: Sun, 8 Nov 2026 19:07:18 +0100 Subject: [PATCH 1/5] bom: write the key length in tree headers --- Sources/AssetKit/BOM/BOMTree.swift | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/Sources/AssetKit/BOM/BOMTree.swift b/Sources/AssetKit/BOM/BOMTree.swift index 89e38c9..42a5ec7 100644 --- a/Sources/AssetKit/BOM/BOMTree.swift +++ b/Sources/AssetKit/BOM/BOMTree.swift @@ -69,10 +69,12 @@ struct BOMTree { } let leafID = bom.addBlock(leaf.data) - // Tree header block. actool's tree headers are 29 bytes -- 21 bytes - // of fixed fields plus 8 trailing zeros (probably reserved/align). - // Match the layout so all trees in our output are the same size as - // the reference. + // Tree header block, 29 bytes like actool's. After the fixed fields + // actool writes the key length as a big-endian u32 (18 for + // RENDITIONS, 7 for a FACETKEYS tree holding "AppIcon", 15 for + // "UIAppearanceAny"), then 4 zero bytes. App Store Connect never + // finishes processing a build whose catalog leaves it at 0: the + // upload stays in PROCESSING with no error. var header = ByteWriter() header.writeBE(treeMagic) header.writeBE(UInt32(1)) // version @@ -80,7 +82,8 @@ struct BOMTree { header.writeBE(blockSize) header.writeBE(UInt32(sorted.count)) // pathCount header.write(byte: 0) // isPathInternal - header.writeZeros(8) // trailing reserved + header.writeBE(UInt32(sorted.map(\.key.count).max() ?? 0)) // key length + header.writeZeros(4) // reserved return bom.addBlock(header.data) } From a24d8d277279f49054712d532e9575a05849f393 Mon Sep 17 00:00:00 2001 From: gulian Date: Sun, 8 Nov 2026 20:26:05 +0100 Subject: [PATCH 2/5] bom: copy the keys into tree leaves after the entries actool follows a leaf's entries with 4 zero bytes and a copy of every key, and sizes the leaf blockSize plus the total key length. App Store Connect looks the app icon up through this copy: without it a build fails with ITMS-90022, 90023 and 91111 (icons missing). --- Sources/AssetKit/BOM/BOMTree.swift | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/Sources/AssetKit/BOM/BOMTree.swift b/Sources/AssetKit/BOM/BOMTree.swift index 42a5ec7..3fbbf08 100644 --- a/Sources/AssetKit/BOM/BOMTree.swift +++ b/Sources/AssetKit/BOM/BOMTree.swift @@ -64,8 +64,18 @@ struct BOMTree { leaf.writeBE(valueBlockIDs[i]) leaf.writeBE(keyBlockIDs[i]) } - if leaf.offset < Int(blockSize) { - leaf.writeZeros(Int(blockSize) - leaf.offset) + // actool follows the entries with 4 zero bytes and a copy of every + // key, in entry order, and sizes the leaf blockSize + the total key + // length. App Store Connect looks the app icon up through this copy: + // without it the catalog parses but it reports the icons as missing + // (ITMS-90022, 90023, 91111). + leaf.writeZeros(4) + for entry in sorted { + leaf.write(entry.key) + } + let leafSize = Int(blockSize) + sorted.reduce(0) { $0 + $1.key.count } + if leaf.offset < leafSize { + leaf.writeZeros(leafSize - leaf.offset) } let leafID = bom.addBlock(leaf.data) From 5d6f761e154aa421b4650271c7b60ce2a0167c8a Mon Sep 17 00:00:00 2001 From: gulian Date: Sun, 8 Nov 2026 21:02:22 +0100 Subject: [PATCH 3/5] car: pad bitmap rows to 32 bytes actool pads every bitmap row to a multiple of 32 bytes, in the pixels and in the bytesPerRow TLV (a 180 px icon: 736 bytes, not 720). AssetKit declared rows rounded to 16 bytes but stored them tightly packed, so for widths where width * 4 is not a multiple of 16 (29, 87, 167 px...) the declared and stored row lengths disagreed, and App Store Connect never finished processing the build. A per-size app icon now goes through. --- Sources/AssetKit/CAR/MLECBody.swift | 23 +++++++++++++++-- Sources/AssetKit/CAR/TVLEntry.swift | 4 +-- Sources/AssetKit/Compression/LZFSE.swift | 12 +++++++++ Tests/AssetKitTests/RowPaddingTests.swift | 31 +++++++++++++++++++++++ 4 files changed, 65 insertions(+), 5 deletions(-) create mode 100644 Tests/AssetKitTests/RowPaddingTests.swift diff --git a/Sources/AssetKit/CAR/MLECBody.swift b/Sources/AssetKit/CAR/MLECBody.swift index 8164c57..b5d9dc9 100644 --- a/Sources/AssetKit/CAR/MLECBody.swift +++ b/Sources/AssetKit/CAR/MLECBody.swift @@ -23,8 +23,27 @@ import Foundation /// single chunk covering the whole image. The 3-chunk split is mimicry /// rather than a correctness requirement: CoreUI accepts both layouts. enum MLECBody { + /// Rows are padded to a multiple of 32 bytes, like actool, and the + /// `bytesPerRow` TLV says so. App Store Connect never finishes processing + /// a build whose catalog stores tightly packed rows that are not already + /// a multiple of 32 bytes (a 180 px icon: 720 bytes instead of 736). + static func bytesPerRow(width: UInt32) -> Int { + (Int(width) * 4 + 31) & ~31 + } + static func encode(width: UInt32, height: UInt32, pixelsBGRA: [UInt8]) -> Data { - let bytesPerRow = Int(width) * 4 + let packedRow = Int(width) * 4 + let bytesPerRow = Self.bytesPerRow(width: width) + var padded = pixelsBGRA + if bytesPerRow != packedRow { + padded = [UInt8](repeating: 0, count: bytesPerRow * Int(height)) + for row in 0.. 0, "LZFSE encoding failed for \(input.count)-byte buffer") return Array(output.prefix(encoded)) } + + /// Decodes an LZFSE stream whose decoded size is at most `capacity`. + /// Only used to check the encoder's output. + static func decode(_ input: [UInt8], capacity: Int = 1 << 24) -> [UInt8] { + var output = [UInt8](repeating: 0, count: capacity) + let decoded = input.withUnsafeBufferPointer { inBuf -> Int in + output.withUnsafeMutableBufferPointer { outBuf in + lzfse_decode_buffer(outBuf.baseAddress!, capacity, inBuf.baseAddress!, input.count, nil) + } + } + return Array(output.prefix(decoded)) + } } diff --git a/Tests/AssetKitTests/RowPaddingTests.swift b/Tests/AssetKitTests/RowPaddingTests.swift new file mode 100644 index 0000000..a7fb7e6 --- /dev/null +++ b/Tests/AssetKitTests/RowPaddingTests.swift @@ -0,0 +1,31 @@ +import Foundation +import Testing +@testable import AssetKit + +@Suite("Bitmap row padding") +struct RowPaddingTests { + @Test("Rows are padded to 32 bytes, in the TLV and in the pixels") + func rowPadding() throws { + for (width, expected) in [(20, 96), (29, 128), (87, 352), (167, 672), (180, 736), (256, 1024)] { + #expect(MLECBody.bytesPerRow(width: UInt32(width)) == expected, "\(width)") + } + // 29 px wide, 3 rows: each stored row is 128 bytes, the last 12 zero + let width = 29, height = 3 + let pixels = [UInt8](repeating: 0xAB, count: width * 4 * height) + let body = MLECBody.encode(width: UInt32(width), height: UInt32(height), pixelsBGRA: pixels) + func le32(_ o: Int) -> Int { + Int(body[body.startIndex + o]) | Int(body[body.startIndex + o + 1]) << 8 + | Int(body[body.startIndex + o + 2]) << 16 | Int(body[body.startIndex + o + 3]) << 24 + } + // 3 rows divide by 3: one KCBC chunk per row. MLEC header 16 bytes, chunk header 20 bytes + var offset = 16 + for _ in 0..<3 { + let size = le32(offset + 16) + let raw = LZFSE.decode(Array(body[body.startIndex + offset + 20.. Date: Sun, 8 Nov 2026 21:51:35 +0100 Subject: [PATCH 4/5] bom: variable key length and no key copy when keys differ in length The key length in a tree header and the key copy in its leaf are BOM's fixed-size keys. actool only writes them when every key of the tree has the same length (rendition keys, a FACETKEYS tree holding only AppIcon). When lengths differ, as with several image names or both appearances, the header says 0xFFFFFFFF and the leaf has no copy. Writing the longest length and a copy there made App Store Connect miss the app icon. --- Sources/AssetKit/BOM/BOMTree.swift | 39 ++++++++++++++++++------------ 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/Sources/AssetKit/BOM/BOMTree.swift b/Sources/AssetKit/BOM/BOMTree.swift index 3fbbf08..4b7d9b9 100644 --- a/Sources/AssetKit/BOM/BOMTree.swift +++ b/Sources/AssetKit/BOM/BOMTree.swift @@ -64,27 +64,36 @@ struct BOMTree { leaf.writeBE(valueBlockIDs[i]) leaf.writeBE(keyBlockIDs[i]) } - // actool follows the entries with 4 zero bytes and a copy of every - // key, in entry order, and sizes the leaf blockSize + the total key - // length. App Store Connect looks the app icon up through this copy: - // without it the catalog parses but it reports the icons as missing - // (ITMS-90022, 90023, 91111). - leaf.writeZeros(4) - for entry in sorted { - leaf.write(entry.key) + // BOM trees whose keys all have the same length store them inline: + // the header gives that length and actool follows the leaf entries + // with 4 zero bytes and a copy of every key, sizing the leaf + // blockSize + the total key length. With keys of different lengths + // (image names in FACETKEYS, appearance names), the header says + // 0xFFFFFFFF and the leaf has no copy. App Store Connect reads keys + // through this copy when the length is fixed: without it, or with a + // fixed length on keys that differ, it reports the app icon as + // missing (ITMS-90022, 90023, 91111). + let keyLengths = Set(sorted.map(\.key.count)) + let fixedKeyLength: Int? = keyLengths.count == 1 ? keyLengths.first : nil + if fixedKeyLength != nil { + leaf.writeZeros(4) + for entry in sorted { + leaf.write(entry.key) + } } - let leafSize = Int(blockSize) + sorted.reduce(0) { $0 + $1.key.count } + let leafSize = Int(blockSize) + (fixedKeyLength != nil ? sorted.reduce(0) { $0 + $1.key.count } : 0) if leaf.offset < leafSize { leaf.writeZeros(leafSize - leaf.offset) } let leafID = bom.addBlock(leaf.data) // Tree header block, 29 bytes like actool's. After the fixed fields - // actool writes the key length as a big-endian u32 (18 for - // RENDITIONS, 7 for a FACETKEYS tree holding "AppIcon", 15 for - // "UIAppearanceAny"), then 4 zero bytes. App Store Connect never - // finishes processing a build whose catalog leaves it at 0: the - // upload stays in PROCESSING with no error. + // actool writes the key length as a big-endian u32 when all keys + // have the same length (18 or 20 for RENDITIONS, 7 for a FACETKEYS + // tree holding only "AppIcon"), 0xFFFFFFFF when they differ, then 4 + // zero bytes. App Store Connect never finishes processing a build + // whose catalog leaves it at 0: the upload stays in PROCESSING with + // no error. var header = ByteWriter() header.writeBE(treeMagic) header.writeBE(UInt32(1)) // version @@ -92,7 +101,7 @@ struct BOMTree { header.writeBE(blockSize) header.writeBE(UInt32(sorted.count)) // pathCount header.write(byte: 0) // isPathInternal - header.writeBE(UInt32(sorted.map(\.key.count).max() ?? 0)) // key length + header.writeBE(fixedKeyLength.map { UInt32($0) } ?? 0xFFFF_FFFF) // key length header.writeZeros(4) // reserved return bom.addBlock(header.data) } From 96ead745077189586f58105aa11286a766b7a842 Mon Sep 17 00:00:00 2001 From: gulian Date: Sun, 8 Nov 2026 22:58:00 +0100 Subject: [PATCH 5/5] car: mark image bitmaps as having alpha The u32 after the MLEC magic is not the compression type: actool writes 1 for every image with transparency (534 of 534 renditions in Xcode's own catalogs) and 3 only in app icon catalogs. AssetKit wrote 3 everywhere, and iOS drew the transparent pixels of images black. Images now get 1, app icons keep 3. Checked on an iPhone: transparent images show the background through. --- Sources/AssetKit/CAR/CSIWriter.swift | 10 +++++++++- Sources/AssetKit/CAR/MLECBody.swift | 19 ++++++++++++++----- Tests/AssetKitTests/RowPaddingTests.swift | 12 ++++++++++++ 3 files changed, 35 insertions(+), 6 deletions(-) diff --git a/Sources/AssetKit/CAR/CSIWriter.swift b/Sources/AssetKit/CAR/CSIWriter.swift index 2bdeace..eeb5962 100644 --- a/Sources/AssetKit/CAR/CSIWriter.swift +++ b/Sources/AssetKit/CAR/CSIWriter.swift @@ -16,7 +16,15 @@ enum CSIWriter { .bitmapFlag, .bytesPerRow(width: body.width), ]) - let payload = MLECBody.encode(width: body.width, height: body.height, pixelsBGRA: body.pixelsBGRA) + // actool writes 1 in the MLEC field after the magic for images and 3 + // for app icons (see MLECBody). With 3, iOS draws an image's + // transparent pixels black. + let payload = MLECBody.encode( + width: body.width, + height: body.height, + pixelsBGRA: body.pixelsBGRA, + pixelMode: body.kind == .appIcon ? .opaque : .alpha + ) // Bit 4 (0x10): generic-image category; set for `.image`, cleared // for `.appIcon`. Matches what UIImage(named:) walks for imageset diff --git a/Sources/AssetKit/CAR/MLECBody.swift b/Sources/AssetKit/CAR/MLECBody.swift index b5d9dc9..61bb216 100644 --- a/Sources/AssetKit/CAR/MLECBody.swift +++ b/Sources/AssetKit/CAR/MLECBody.swift @@ -5,8 +5,8 @@ import Foundation /// Layout verified against actool's reference Assets.car: /// /// MLEC magic 4 bytes -/// compressionType u32 (0 = raw, 3 = LZFSE) -/// bytesPerPixel u32 (4 for BGRA8) +/// pixelMode u32 (1 = with alpha, 3 = opaque, see PixelMode) +/// compression u32 (4 = LZFSE) /// chunkCount u32 (1 or 3) /// then chunkCount * KCBC chunks /// @@ -31,7 +31,16 @@ enum MLECBody { (Int(width) * 4 + 31) & ~31 } - static func encode(width: UInt32, height: UInt32, pixelsBGRA: [UInt8]) -> Data { + /// The u32 after the MLEC magic. actool writes 1 for every image with + /// transparency (534 of 534 renditions in Xcode's own catalogs) and 3 only + /// in app icon catalogs (the store icon, icon atlases). iOS treats a 3 + /// bitmap as opaque: its transparent pixels come out black. + enum PixelMode: UInt32 { + case alpha = 1 + case opaque = 3 + } + + static func encode(width: UInt32, height: UInt32, pixelsBGRA: [UInt8], pixelMode: PixelMode = .alpha) -> Data { let packedRow = Int(width) * 4 let bytesPerRow = Self.bytesPerRow(width: width) var padded = pixelsBGRA @@ -58,8 +67,8 @@ enum MLECBody { var w = ByteWriter() w.writeFourCC("MLEC") - w.writeLE(UInt32(3)) // compressionType = 3 (LZFSE) - w.writeLE(UInt32(4)) // bytesPerPixel (BGRA8 = 4) + w.writeLE(pixelMode.rawValue) // 1 = with alpha, 3 = opaque (app icons) + w.writeLE(UInt32(4)) // compression: 4 = LZFSE w.writeLE(chunkCount) for chunk in chunks { diff --git a/Tests/AssetKitTests/RowPaddingTests.swift b/Tests/AssetKitTests/RowPaddingTests.swift index a7fb7e6..fdb19e7 100644 --- a/Tests/AssetKitTests/RowPaddingTests.swift +++ b/Tests/AssetKitTests/RowPaddingTests.swift @@ -29,3 +29,15 @@ struct RowPaddingTests { } } } + +@Suite("Bitmap pixel mode") +struct PixelModeTests { + @Test("Images are written with alpha (1), app icons as opaque (3)") + func pixelMode() { + let pixels = [UInt8](repeating: 0, count: 4 * 4 * 4) + let image = MLECBody.encode(width: 4, height: 4, pixelsBGRA: pixels, pixelMode: .alpha) + let icon = MLECBody.encode(width: 4, height: 4, pixelsBGRA: pixels, pixelMode: .opaque) + #expect(Array(image[image.startIndex + 4..