feat(codes): share scannable-code geometry via KMP; export tip codes as PNG/SVG (#1287)

Tip cards need PNG and SVG export. Rather than write that twice, the part that
actually has to agree between platforms -- where every mark goes -- moves into a
new KMP module, and each platform keeps only a thin painter over it.

:libs:codes:kikcode (commonMain, no platform APIs):
  - KikCodeGeometry.describe(payload, dimension) -> KikCodeDescription: the
    centre, badge well, dot diameter, and an ordered list of Dot/Arc/Ring marks.
    Runs of consecutive set bits collapse to one stroked arc with round caps --
    the same union as per-bit dots plus connecting bands, far fewer elements.
  - KikCodeSvg.render(...) -> a self-contained SVG document. Export is code-only
    (matching the existing share preview), so there is no text and no font to
    embed.
  - Exported through :kmp:shared-core, so iOS gets it in the SharedCore
    XCFramework.

Android is now a painter, not a second implementation. KikCodeContentRendererImpl
drops from 139 lines of fused maths-and-drawing to ~30 lines of draw calls, so the
on-screen view, the exported PNG, the exported SVG, and iOS are all the same
numbers. TipCodeExporter writes either format to cacheDir/share_exports/ behind
the existing FileProvider.

Framing: adopt iOS's canonical outer ratio of 0.5. Android used to inset the
graphic to 0.93 and then have KikCodeContentView overscan by 1.03 to compensate,
a net 0.958; the code is now ~4.2% larger within the same box and the badge well
grows from 0.298 to 0.32 of the graphic, matching iOS.

Gated by test-vectors/kikcode.json plus a golden SVG, generated by an independent
Python implementation written from the spec ratios rather than transcribed from
the Kotlin. Both run on the JVM host and on Kotlin/Native: the byte-for-byte SVG
comparison is what proves the two toolchains agree, since Double.toString() is
unspecified across Kotlin targets and libm trig can differ in the last place
(both handled by formatting every emitted number at 3 decimals via roundToLong).

Fixtures are compiled into commonTest as generated Kotlin -- Kotlin/Native test
binaries ship no resource bundle, so a resource-based loader silently only ever
runs on the JVM.

Five Robolectric tests cover what the vectors cannot reach: that arc sweeps are
not inverted, that the badge fills its well, and that the graphic frames
correctly.

TipCodeExporter has no UI entry point yet; that lands with the You tab work.

Author: bmc08gt

apps/flipcash/app/src/main/res/xml/file_paths.xml

@@ -3,4 +3,6 @@
     <files-path name="traces" path="traces/" />
     <!-- Rendered tip-code Sharesheet previews (cacheDir/share_previews/). -->
     <cache-path name="share_previews" path="share_previews/" />
+    <!-- Exported tip codes, PNG + SVG (cacheDir/share_exports/). -->
+    <cache-path name="share_exports" path="share_exports/" />
 </paths>

apps/flipcash/core/src/main/kotlin/com/flipcash/app/core/share/TipCodeExport.kt

@@ -0,0 +1,69 @@
+package com.flipcash.app.core.share
+
+import android.content.Context
+import android.net.Uri
+import androidx.core.content.FileProvider
+import java.io.File
+
+/**
+ * A user-facing export of a tip code: the scannable graphic on its own, written to a file the
+ * Sharesheet (or a "save to Files" target) can consume.
+ *
+ * Distinct from [TipCodePreview], which exists only to give the Sharesheet a thumbnail while the
+ * thing actually shared stays the tip URL. An export *is* the payload.
+ */
+data class TipCodeExport(
+    val uri: Uri,
+    val format: TipCodeExportFormat,
+) {
+    val mimeType: String get() = format.mimeType
+}
+
+enum class TipCodeExportFormat(val extension: String, val mimeType: String) {
+    /** Raster. Universally pasteable; fixed resolution. */
+    Png("png", "image/png"),
+
+    /**
+     * Vector. Scales to any size (print, large-format) and stays a few KB.
+     *
+     * Self-contained by construction — no fonts, no embedded raster, no external references —
+     * because the export is code-only, so there is no text to worry about.
+     */
+    Svg("svg", "image/svg+xml"),
+}
+
+/**
+ * Where exported codes live on disk and how they map to `content://` URIs.
+ *
+ * Separate directory from [TipCodePreviewStorage] so the preview cache's aggressive pruning can't
+ * delete an export out from under a share in progress, and so the two can be tuned independently.
+ * Files are named by the card's content [tipCodePreviewSignature], so re-exporting the same card
+ * overwrites rather than accumulates.
+ */
+object TipCodeExportStorage {
+    const val SUBDIR = "share_exports"
+
+    fun dir(context: Context): File =
+        File(context.cacheDir, SUBDIR).apply { if (!exists()) mkdirs() }
+
+    /**
+     * Name is user-visible in some share targets ("save to Files"), hence the readable prefix
+     * rather than a bare hash.
+     */
+    fun file(context: Context, signature: String, format: TipCodeExportFormat): File =
+        File(dir(context), "flipcash-code-$signature.${format.extension}")
+
+    fun uriFor(context: Context, file: File): Uri =
+        FileProvider.getUriForFile(context, TipCodePreviewStorage.authority(context), file)
+
+    /** See [TipCodePreviewStorage.prune]; exports are re-creatable, so over-pruning only costs a re-render. */
+    fun prune(
+        context: Context,
+        maxTotalBytes: Long = DEFAULT_MAX_TOTAL_BYTES,
+        maxAge: Long = DEFAULT_MAX_AGE_MILLIS,
+        now: Long = System.currentTimeMillis(),
+    ) = pruneDirectory(dir(context), maxTotalBytes, maxAge, now)
+
+    private const val DEFAULT_MAX_TOTAL_BYTES = 8L * 1024 * 1024 // 8 MiB
+    private const val DEFAULT_MAX_AGE_MILLIS = 24L * 60 * 60 * 1000 // 1 day
+}

apps/flipcash/core/src/main/kotlin/com/flipcash/app/core/share/TipCodeExporter.kt

@@ -0,0 +1,91 @@
+package com.flipcash.app.core.share
+
+import android.content.Context
+import android.graphics.Bitmap
+import androidx.core.content.ContextCompat
+import com.flipcash.core.R
+import com.flipcash.app.core.bill.Scannable
+import com.flipcash.libs.coroutines.DispatcherProvider
+import com.getcode.codes.kikcode.KikCodeSvg
+import com.getcode.codes.kikcode.kikCodeBitmap
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.withContext
+import java.io.File
+import java.io.FileOutputStream
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Exports a tip card's scannable code as a PNG or an SVG.
+ *
+ * Code-only, matching what the share preview already shows: no display name, no avatar, no card
+ * chrome. That keeps the SVG honest (nothing to embed a font for) and makes both formats render the
+ * same thing.
+ *
+ * Both formats come off the *same* shared geometry (`:libs:codes:kikcode`), which is also what the
+ * on-screen `KikCodeContentView` and iOS draw — so an exported file and the code the user is looking
+ * at cannot disagree. Rasterisation stays native (Android [Bitmap] here, `CGContext` on iOS); only
+ * the maths is shared.
+ */
+@Singleton
+class TipCodeExporter @Inject constructor(
+    @ApplicationContext private val context: Context,
+    private val dispatchers: DispatcherProvider,
+) {
+
+    /**
+     * Writes [card]'s code in [format] and returns a `content://` handle to it, or `null` if the
+     * write failed — callers should degrade (share the URL alone) rather than surface an error.
+     *
+     * [sizePx] applies to [TipCodeExportFormat.Png] only; the SVG carries a `viewBox` and scales.
+     */
+    suspend fun export(
+        card: Scannable.TipCard,
+        format: TipCodeExportFormat,
+        sizePx: Int = DEFAULT_PNG_SIZE_PX,
+    ): TipCodeExport? = withContext(dispatchers.IO) {
+        val payload = card.data.toByteArray()
+        if (payload.isEmpty()) return@withContext null
+
+        runCatching {
+            val file = TipCodeExportStorage.file(
+                context = context,
+                signature = tipCodePreviewSignature(card),
+                format = format,
+            )
+            when (format) {
+                TipCodeExportFormat.Png -> writePng(payload, sizePx, file)
+                TipCodeExportFormat.Svg -> writeSvg(payload, file)
+            }
+            TipCodeExport(uri = TipCodeExportStorage.uriFor(context, file), format = format)
+        }.getOrNull()
+    }
+
+    private fun writePng(payload: ByteArray, sizePx: Int, file: File) {
+        val badge = ContextCompat.getDrawable(context, R.drawable.ic_logo_round_white)
+        val bitmap = kikCodeBitmap(payload = payload, size = sizePx, badge = badge)
+        try {
+            FileOutputStream(file).use { out ->
+                bitmap.compress(Bitmap.CompressFormat.PNG, PNG_QUALITY, out)
+            }
+        } finally {
+            bitmap.recycle()
+        }
+    }
+
+    private fun writeSvg(payload: ByteArray, file: File) {
+        file.writeText(KikCodeSvg.render(payload))
+    }
+
+    private companion object {
+        /**
+         * Large enough that the code stays crisp when a share target scales it up, small enough to
+         * stay well under a megabyte -- the graphic is flat white on transparent, so PNG compresses
+         * it hard.
+         */
+        const val DEFAULT_PNG_SIZE_PX = 1024
+
+        // PNG is lossless; the parameter only controls compression effort.
+        const val PNG_QUALITY = 100
+    }
+}

apps/flipcash/core/src/main/kotlin/com/flipcash/app/core/share/TipCodePreviewStorage.kt

@@ -45,20 +45,27 @@ object TipCodePreviewStorage {
         maxAge: Long = DEFAULT_MAX_AGE_MILLIS,
         now: Long = System.currentTimeMillis(),
     ) {
-        runCatching {
-            val files = dir(context).listFiles()?.sortedByDescending { it.lastModified() }
-                ?: return
-            var kept = 0L
-            for (file in files) {
-                val expired = now - file.lastModified() > maxAge
-                kept += file.length()
-                if (expired || kept > maxTotalBytes) {
-                    file.delete()
-                }
-            }
-        }
+        pruneDirectory(dir(context), maxTotalBytes, maxAge, now)
     }
 
     private const val DEFAULT_MAX_TOTAL_BYTES = 8L * 1024 * 1024 // 8 MiB
     private const val DEFAULT_MAX_AGE_MILLIS = 24L * 60 * 60 * 1000 // 1 day
 }
+
+/**
+ * Deletes anything in [dir] older than [maxAge], then -- newest first -- keeps files until
+ * [maxTotalBytes] is reached and deletes the rest. Never throws; cleanup is best-effort.
+ */
+internal fun pruneDirectory(dir: File, maxTotalBytes: Long, maxAge: Long, now: Long) {
+    runCatching {
+        val files = dir.listFiles()?.sortedByDescending { it.lastModified() } ?: return
+        var kept = 0L
+        for (file in files) {
+            val expired = now - file.lastModified() > maxAge
+            kept += file.length()
+            if (expired || kept > maxTotalBytes) {
+                file.delete()
+            }
+        }
+    }
+}

apps/flipcash/core/src/test/kotlin/com/flipcash/app/core/share/KikCodePainterTest.kt

@@ -0,0 +1,111 @@
+package com.flipcash.app.core.share
+
+import android.graphics.Bitmap
+import android.graphics.Color
+import android.graphics.drawable.ColorDrawable
+import com.getcode.codes.kikcode.kikCodeBitmap
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.GraphicsMode
+import kotlin.math.hypot
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+/**
+ * Covers the Android *painter* — the half of code rendering that the cross-platform vectors can't
+ * reach. `:libs:codes:kikcode` gates the geometry and the SVG on both toolchains; these assertions
+ * gate the translation of that geometry into `Canvas` draw calls, where an inverted arc sweep or a
+ * mis-scaled badge would be invisible to the vectors.
+ *
+ * Native graphics so `Canvas` actually rasterises rather than recording no-ops.
+ */
+@RunWith(RobolectricTestRunner::class)
+@GraphicsMode(GraphicsMode.Mode.NATIVE)
+@Config(sdk = [34])
+class KikCodePainterTest {
+
+    /**
+     * The full 35-byte payload with every bit set -> all six rings full, i.e. the largest graphic
+     * the geometry can produce. A 20-byte tip payload leaves the outermost ring empty (24 bytes of
+     * finder+payload is 192 bits, and ring 5 starts at bit 240), so it can't measure the framing.
+     */
+    private val saturated = ByteArray(35) { 0xFF.toByte() }
+
+    /** Irregular, so runs, isolated dots and gaps all appear. */
+    private val scattered = ByteArray(20) { (it * 7 + 1).toByte() }
+
+    @Test
+    fun `renders marks`() {
+        val bitmap = kikCodeBitmap(scattered, SIZE)
+        assertEquals(SIZE, bitmap.width)
+        assertEquals(SIZE, bitmap.height)
+        assertTrue(bitmap.opaquePixelCount() > 0, "nothing was drawn")
+    }
+
+    @Test
+    fun `graphic fills its box without overflowing it`() {
+        // The outermost stroke reaches ~0.939 of the radius by construction (ring centre 0.90625
+        // plus half a 0.0656 stroke). Both bounds matter: the upper one catches clipping, and the
+        // lower one catches a re-introduced inset -- Android used to shrink the code to 0.93 and
+        // then overscan the view by 1.03 to compensate, which put it ~4% under iOS.
+        val extent = kikCodeBitmap(saturated, SIZE).maxOpaqueRadius() / (SIZE / 2.0)
+        assertTrue(extent in 0.93..0.96, "outer extent was $extent of the radius")
+    }
+
+    @Test
+    fun `centre well is left empty when there is no badge`() {
+        val bitmap = kikCodeBitmap(scattered, SIZE)
+        assertEquals(Color.TRANSPARENT, bitmap.getPixel(SIZE / 2, SIZE / 2))
+    }
+
+    @Test
+    fun `badge is drawn into the centre well`() {
+        val bitmap = kikCodeBitmap(scattered, SIZE, badge = ColorDrawable(Color.RED))
+        assertEquals(Color.RED, bitmap.getPixel(SIZE / 2, SIZE / 2))
+
+        // The well is INNER_RING_RATIO (0.32) of the outer radius, and the badge fills it exactly.
+        val expected = (SIZE / 2.0) * 0.32
+        val actual = bitmap.run {
+            var left = width
+            for (x in 0 until width) {
+                if (getPixel(x, height / 2) == Color.RED) { left = x; break }
+            }
+            width / 2.0 - left
+        }
+        assertTrue(kotlin.math.abs(actual - expected) <= 1.0, "badge half-width $actual, want $expected")
+    }
+
+    @Test
+    fun `output scales linearly with size`() {
+        val small = kikCodeBitmap(saturated, SIZE).maxOpaqueRadius() / SIZE
+        val large = kikCodeBitmap(saturated, SIZE * 2).maxOpaqueRadius() / (SIZE * 2)
+        assertTrue(kotlin.math.abs(small - large) < 0.005, "extent $small vs $large")
+    }
+
+    private fun Bitmap.pixels(): IntArray =
+        IntArray(width * height).also { getPixels(it, 0, width, 0, 0, width, height) }
+
+    private fun Bitmap.opaquePixelCount(): Int = pixels().count { Color.alpha(it) > ALPHA_FLOOR }
+
+    /** Distance from the centre to the furthest drawn pixel, in px. */
+    private fun Bitmap.maxOpaqueRadius(): Double {
+        val centre = width / 2.0
+        val pixels = pixels()
+        var furthest = 0.0
+        for (index in pixels.indices) {
+            if (Color.alpha(pixels[index]) <= ALPHA_FLOOR) continue
+            val distance = hypot(index % width - centre, (index / width) - centre)
+            if (distance > furthest) furthest = distance
+        }
+        return furthest
+    }
+
+    private companion object {
+        const val SIZE = 512
+
+        // Ignore antialiasing fringes so the extent measurement tracks the shape, not its feather.
+        const val ALPHA_FLOOR = 128
+    }
+}

kmp/shared-core/build.gradle.kts

@@ -20,6 +20,7 @@ kotlin {
         it.binaries.framework {
             baseName = "SharedCore"
             isStatic = true
+            export(project(":libs:codes:kikcode"))
             export(project(":libs:encryption:base58"))
             export(project(":libs:encryption:sha256"))
             export(project(":libs:encryption:sha512"))
@@ -31,6 +32,7 @@ kotlin {
     sourceSets {
         commonMain {
             dependencies {
+                api(project(":libs:codes:kikcode"))
                 api(project(":libs:encryption:base58"))
                 api(project(":libs:encryption:sha256"))
                 api(project(":libs:encryption:sha512"))

libs/codes/kikcode/.gitignore

@@ -0,0 +1 @@
+/build