Baseline: wave 1A server complete, wave 1B Android scaffold + design system green

assembleDebug, testDebugUnitTest, and recordPaparazziDebug all pass. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016bThmkmyUUdqQpy3MXFFe5
2026-09-06 01:58:37 +00:00
commit 6c17e42037
79 changed files with 3773 additions and 0 deletions
@@ -0,0 +1,93 @@
+Copyright 2017 The Literata Project Authors (https://github.com/googlefonts/literata)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
@@ -0,0 +1,117 @@
+plugins {
+    alias(libs.plugins.android.application)
+    // NOTE: no org.jetbrains.kotlin.android plugin — AGP 9's Kotlin support is
+    // built in. Only sub-plugins that add compiler extensions are applied here.
+    alias(libs.plugins.kotlin.compose)
+    alias(libs.plugins.kotlin.serialization)
+    alias(libs.plugins.ksp)
+    alias(libs.plugins.paparazzi)
+}
+
+android {
+    namespace = "org.modg.bookshelf"
+    compileSdk = 37
+    buildToolsVersion = "37.0.0"
+
+    defaultConfig {
+        applicationId = "org.modg.bookshelf"
+        minSdk = 26
+        targetSdk = 37
+        versionCode = 1
+        versionName = "1.0"
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_21
+        targetCompatibility = JavaVersion.VERSION_21
+    }
+
+    buildFeatures {
+        compose = true
+    }
+
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+        }
+    }
+
+    packaging {
+        resources {
+            excludes += "/META-INF/{AL2.0,LGPL2.1}"
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21)
+    }
+}
+
+// Paparazzi's Gradle plugin writes an HTML test report that trips on AGP 9's
+// new DSL (cashapp/paparazzi#2111). Disable it; the PNG snapshots/report task
+// output is what we actually care about here.
+tasks.withType<Test>().configureEach {
+    reports.html.required.set(false)
+}
+
+dependencies {
+    implementation(libs.androidx.core.ktx)
+    implementation(libs.androidx.activity.compose)
+    implementation(libs.androidx.lifecycle.runtime.ktx)
+    implementation(libs.androidx.lifecycle.viewmodel.compose)
+    implementation(libs.androidx.navigation.compose)
+
+    implementation(platform(libs.compose.bom))
+    implementation(libs.compose.ui)
+    implementation(libs.compose.ui.graphics)
+    implementation(libs.compose.ui.tooling.preview)
+    implementation(libs.compose.foundation)
+    implementation(libs.compose.material3)
+    implementation(libs.compose.material.icons.extended)
+    debugImplementation(libs.compose.ui.tooling)
+    debugImplementation(libs.compose.ui.test.manifest)
+
+    implementation(libs.androidx.room.runtime)
+    implementation(libs.androidx.room.ktx)
+    ksp(libs.androidx.room.compiler)
+
+    implementation(libs.retrofit.core)
+    implementation(libs.retrofit.kotlinx.serialization.converter)
+    implementation(libs.okhttp.logging.interceptor)
+    implementation(libs.kotlinx.serialization.json)
+    implementation(libs.kotlinx.coroutines.core)
+    implementation(libs.kotlinx.coroutines.android)
+
+    implementation(libs.coil.compose)
+    implementation(libs.coil.network.okhttp)
+
+    implementation(libs.androidx.camera.core)
+    implementation(libs.androidx.camera.camera2)
+    implementation(libs.androidx.camera.lifecycle)
+    implementation(libs.androidx.camera.view)
+    implementation(libs.mlkit.barcode.scanning)
+
+    implementation(libs.androidx.work.runtime.ktx)
+    implementation(libs.androidx.datastore.preferences)
+    implementation(libs.accompanist.permissions)
+
+    testImplementation(libs.junit)
+    testImplementation(libs.robolectric)
+    testImplementation(libs.androidx.test.core)
+    testImplementation(libs.androidx.test.ext.junit)
+    testImplementation(libs.androidx.room.testing)
+    testImplementation(libs.kotlinx.coroutines.test)
+    testImplementation(platform(libs.compose.bom))
+    testImplementation(libs.compose.ui.test.manifest)
+}
@@ -0,0 +1,3 @@
+# Add project specific ProGuard rules here.
+# Release minification is currently disabled (isMinifyEnabled = false); this
+# file is a placeholder for when wave-3+ enables it.
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- Camera for barcode scanning (ui.scan) -->
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-feature
+        android:name="android.hardware.camera"
+        android:required="false" />
+    <uses-feature
+        android:name="android.hardware.camera.autofocus"
+        android:required="false" />
+
+    <!-- PocketBase sync, metadata lookup (Open Library / Google Books), cover uploads -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+    <application
+        android:name=".BookshelfApplication"
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.Bookshelf"
+        tools:targetApi="31"
+        xmlns:tools="http://schemas.android.com/tools">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:theme="@style/Theme.Bookshelf">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>
@@ -0,0 +1,12 @@
+package org.modg.bookshelf
+
+import android.app.Application
+
+/**
+ * Application entry point. Per SPEC, DI is a hand-rolled [AppContainer] held
+ * here (no Hilt/kapt) — data.repo/data.local/data.remote wiring lands with
+ * the waves that introduce those packages. This scaffold wave intentionally
+ * leaves the container empty rather than stubbing out APIs that don't exist
+ * yet.
+ */
+class BookshelfApplication : Application()
@@ -0,0 +1,128 @@
+package org.modg.bookshelf
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.lazy.grid.GridCells
+import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
+import androidx.compose.foundation.lazy.grid.items
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.outlined.Settings
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import org.modg.bookshelf.ui.components.BookCover
+import org.modg.bookshelf.ui.components.BookshelfScaffold
+import org.modg.bookshelf.ui.components.EmptyState
+import org.modg.bookshelf.ui.components.GoldDivider
+import org.modg.bookshelf.ui.components.PaperSurface
+import org.modg.bookshelf.ui.components.PrimaryButton
+import org.modg.bookshelf.ui.components.SecondaryButton
+import org.modg.bookshelf.ui.components.SyncStatus
+import org.modg.bookshelf.ui.components.SyncStatusBar
+import org.modg.bookshelf.ui.theme.BookshelfTheme
+
+/**
+ * Wave 2's placeholder home screen. There is no navigation graph yet (that's
+ * ui.nav.BookshelfNavHost, a later wave) — this Activity exists purely as a
+ * living style reference for the component set above, so wave 3 can see
+ * exactly how BookshelfScaffold/BookCover/etc. are meant to be used.
+ */
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        enableEdgeToEdge()
+        setContent {
+            BookshelfTheme {
+                StyleReferenceScreen()
+            }
+        }
+    }
+}
+
+private data class SampleBook(val title: String, val coverUrl: String?)
+
+private val sampleBooks = listOf(
+    SampleBook("The Left Hand of Darkness", "https://covers.openlibrary.org/b/isbn/9780441478125-L.jpg"),
+    SampleBook("A broken cover URL", "https://example.invalid/nope.jpg"),
+    SampleBook("No cover on file", null),
+    SampleBook("Gödel, Escher, Bach", null),
+)
+
+@Composable
+private fun StyleReferenceScreen() {
+    var showEmptyState by remember { mutableStateOf(false) }
+
+    BookshelfScaffold(
+        title = "Bookshelf",
+        actions = {
+            IconButton(onClick = { showEmptyState = !showEmptyState }) {
+                Icon(Icons.Outlined.Settings, contentDescription = "Toggle empty state")
+            }
+        },
+        syncStatusBar = {
+            SyncStatusBar(status = SyncStatus.Synced, label = "Synced • just now")
+        },
+    ) { innerPadding ->
+        PaperSurface(modifier = Modifier.fillMaxWidth()) {
+            if (showEmptyState) {
+                EmptyState(
+                    modifier = Modifier.padding(innerPadding),
+                    title = "Your shelves are empty",
+                    message = "Scan a barcode to add your first book.",
+                    action = { PrimaryButton(text = "Scan a book", onClick = {}) },
+                )
+            } else {
+                Column(modifier = Modifier.padding(innerPadding)) {
+                    SectionLabel("Covers")
+                    LazyVerticalGrid(
+                        columns = GridCells.Fixed(3),
+                        contentPadding = PaddingValues(16.dp),
+                        horizontalArrangement = Arrangement.spacedBy(12.dp),
+                        verticalArrangement = Arrangement.spacedBy(12.dp),
+                        modifier = Modifier.fillMaxWidth(),
+                    ) {
+                        items(sampleBooks) { book ->
+                            BookCover(coverUrl = book.coverUrl, contentDescription = book.title)
+                        }
+                    }
+
+                    GoldDivider(modifier = Modifier.padding(vertical = 8.dp))
+                    SectionLabel("Buttons")
+                    Row(
+                        modifier = Modifier.padding(horizontal = 16.dp),
+                        horizontalArrangement = Arrangement.spacedBy(12.dp),
+                    ) {
+                        PrimaryButton(text = "Save", onClick = {})
+                        SecondaryButton(text = "Skip", onClick = {})
+                    }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun SectionLabel(text: String) {
+    Text(
+        text = text,
+        style = MaterialTheme.typography.titleSmall,
+        color = MaterialTheme.colorScheme.onSurfaceVariant,
+        modifier = Modifier.padding(start = 16.dp, top = 16.dp, bottom = 4.dp),
+    )
+}
@@ -0,0 +1,89 @@
+package org.modg.bookshelf.ui.components
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.aspectRatio
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.outlined.AutoStories
+import androidx.compose.material.icons.outlined.BrokenImage
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.layout.ContentScale
+import androidx.compose.ui.unit.dp
+import coil3.compose.AsyncImagePainter
+import coil3.compose.SubcomposeAsyncImage
+import coil3.compose.SubcomposeAsyncImageContent
+
+/** The canonical book-cover aspect ratio (standard trade paperback proportions). */
+const val BookCoverAspectRatio = 2f / 3f
+
+/**
+ * A book cover image, always drawn at [BookCoverAspectRatio]. Covers are the
+ * hero of this app's design — real art fills the whole shape edge to edge.
+ * When there's no [coverUrl], or the load fails, we fall back to the same
+ * restrained "letterpress" placeholder: a paper-toned panel with a debossed
+ * spine motif rather than a broken-image icon or empty grey box.
+ */
+@Composable
+fun BookCover(
+    coverUrl: String?,
+    contentDescription: String?,
+    modifier: Modifier = Modifier,
+    shape: androidx.compose.ui.graphics.Shape = MaterialTheme.shapes.small,
+) {
+    Box(
+        modifier = modifier
+            .aspectRatio(BookCoverAspectRatio)
+            .clip(shape),
+    ) {
+        if (coverUrl.isNullOrBlank()) {
+            CoverPlaceholder(errored = false)
+        } else {
+            SubcomposeAsyncImage(
+                model = coverUrl,
+                contentDescription = contentDescription,
+                modifier = Modifier.fillMaxSize(),
+                contentScale = ContentScale.Crop,
+            ) {
+                when (painter.state) {
+                    is AsyncImagePainter.State.Error -> CoverPlaceholder(errored = true)
+                    is AsyncImagePainter.State.Loading,
+                    is AsyncImagePainter.State.Empty,
+                        -> CoverPlaceholder(errored = false, loading = true)
+                    is AsyncImagePainter.State.Success -> SubcomposeAsyncImageContent()
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun CoverPlaceholder(errored: Boolean, loading: Boolean = false) {
+    val paperAlt = MaterialTheme.colorScheme.surfaceVariant
+    val ink = MaterialTheme.colorScheme.onSurfaceVariant
+    Box(
+        modifier = Modifier
+            .fillMaxSize()
+            .background(paperAlt)
+            .border(width = 1.dp, color = ink.copy(alpha = 0.15f))
+            .padding(2.dp)
+            .border(width = 1.dp, color = ink.copy(alpha = 0.1f)),
+        contentAlignment = Alignment.Center,
+    ) {
+        if (!loading) {
+            Icon(
+                imageVector = if (errored) Icons.Outlined.BrokenImage else Icons.Outlined.AutoStories,
+                contentDescription = null,
+                tint = ink.copy(alpha = if (errored) 0.35f else 0.28f),
+                modifier = Modifier.fillMaxSize(0.32f),
+            )
+        }
+    }
+}
@@ -0,0 +1,62 @@
+package org.modg.bookshelf.ui.components
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.CenterAlignedTopAppBar
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.FloatingActionButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.material3.TopAppBarDefaults
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+
+/**
+ * The shell every Bookshelf screen is built on: a top bar with the serif
+ * screen title and a gold hairline rule underneath, plus optional nav/action
+ * slots, FAB, and a bottom [SyncStatusBar] slot. Screens should reach for
+ * this instead of a bare [Scaffold] so the chrome stays consistent.
+ */
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun BookshelfScaffold(
+    title: String,
+    modifier: Modifier = Modifier,
+    navigationIcon: @Composable () -> Unit = {},
+    actions: @Composable () -> Unit = {},
+    floatingActionButton: @Composable () -> Unit = {},
+    syncStatusBar: @Composable () -> Unit = {},
+    content: @Composable (PaddingValues) -> Unit,
+) {
+    Scaffold(
+        modifier = modifier,
+        topBar = {
+            Column {
+                CenterAlignedTopAppBar(
+                    title = {
+                        Text(text = title, style = MaterialTheme.typography.titleLarge)
+                    },
+                    navigationIcon = navigationIcon,
+                    actions = { actions() },
+                    colors = TopAppBarDefaults.centerAlignedTopAppBarColors(
+                        containerColor = MaterialTheme.colorScheme.surface,
+                        titleContentColor = MaterialTheme.colorScheme.onSurface,
+                    ),
+                )
+                GoldDivider()
+            }
+        },
+        floatingActionButton = floatingActionButton,
+        containerColor = MaterialTheme.colorScheme.surface,
+        content = { innerPadding ->
+            Column(modifier = Modifier.fillMaxSize()) {
+                Column(modifier = Modifier.weight(1f)) {
+                    content(innerPadding)
+                }
+                syncStatusBar()
+            }
+        },
+    )
+}
@@ -0,0 +1,62 @@
+package org.modg.bookshelf.ui.components
+
+import androidx.compose.foundation.BorderStroke
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Button
+import androidx.compose.material3.ButtonDefaults
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+
+private val ButtonShape = RoundedCornerShape(6.dp)
+private val ButtonPadding = PaddingValues(horizontal = 24.dp, vertical = 12.dp)
+
+/** The mahogany-filled call to action button — Save, Add to shelf, Sign in, etc. */
+@Composable
+fun PrimaryButton(
+    text: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+) {
+    Button(
+        onClick = onClick,
+        modifier = modifier,
+        enabled = enabled,
+        shape = ButtonShape,
+        contentPadding = ButtonPadding,
+        colors = ButtonDefaults.buttonColors(
+            containerColor = MaterialTheme.colorScheme.primary,
+            contentColor = MaterialTheme.colorScheme.onPrimary,
+        ),
+    ) {
+        Text(text = text, style = MaterialTheme.typography.labelLarge)
+    }
+}
+
+/** The quieter outlined companion — Cancel, Skip, secondary actions. */
+@Composable
+fun SecondaryButton(
+    text: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+) {
+    OutlinedButton(
+        onClick = onClick,
+        modifier = modifier,
+        enabled = enabled,
+        shape = ButtonShape,
+        contentPadding = ButtonPadding,
+        colors = ButtonDefaults.outlinedButtonColors(
+            contentColor = MaterialTheme.colorScheme.primary,
+        ),
+        border = BorderStroke(1.dp, MaterialTheme.colorScheme.outline),
+    ) {
+        Text(text = text, style = MaterialTheme.typography.labelLarge)
+    }
+}
@@ -0,0 +1,64 @@
+package org.modg.bookshelf.ui.components
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.outlined.AutoStories
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+
+/**
+ * A quiet, on-brand empty state — an icon, a serif headline, a supporting
+ * line, and an optional call to action (e.g. library's "invite the first
+ * scan"). Never just blank space.
+ */
+@Composable
+fun EmptyState(
+    title: String,
+    modifier: Modifier = Modifier,
+    message: String? = null,
+    action: @Composable (() -> Unit)? = null,
+) {
+    Column(
+        modifier = modifier
+            .fillMaxSize()
+            .padding(32.dp),
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.Center,
+    ) {
+        Icon(
+            imageVector = Icons.Outlined.AutoStories,
+            contentDescription = null,
+            tint = MaterialTheme.colorScheme.secondary,
+            modifier = Modifier.padding(bottom = 16.dp),
+        )
+        Text(
+            text = title,
+            style = MaterialTheme.typography.headlineSmall,
+            color = MaterialTheme.colorScheme.onSurface,
+            textAlign = TextAlign.Center,
+        )
+        if (message != null) {
+            Text(
+                text = message,
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                textAlign = TextAlign.Center,
+                modifier = Modifier.padding(top = 8.dp),
+            )
+        }
+        if (action != null) {
+            Column(modifier = Modifier.padding(top = 24.dp)) {
+                action()
+            }
+        }
+    }
+}
@@ -0,0 +1,45 @@
+package org.modg.bookshelf.ui.components
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.drawBehind
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.unit.dp
+
+/**
+ * The thin gold hairline rule used under topbars and between sections — one
+ * of the app's few recurring "motifs" per the SPEC. Fades to transparent at
+ * both ends rather than terminating abruptly, so it reads as a rule on the
+ * page instead of a UI divider.
+ */
+@Composable
+fun GoldDivider(modifier: Modifier = Modifier) {
+    val gold = MaterialTheme.colorScheme.secondary
+    Box(
+        modifier = modifier
+            .fillMaxWidth()
+            .height(1.dp)
+            .drawBehind {
+                val brush = Brush.horizontalGradient(
+                    colors = listOf(
+                        gold.copy(alpha = 0f),
+                        gold.copy(alpha = 0.8f),
+                        gold.copy(alpha = 0f),
+                    ),
+                    startX = 0f,
+                    endX = size.width,
+                )
+                drawLine(
+                    brush = brush,
+                    start = Offset(0f, size.height / 2f),
+                    end = Offset(size.width, size.height / 2f),
+                    strokeWidth = size.height,
+                )
+            },
+    )
+}
@@ -0,0 +1,61 @@
+package org.modg.bookshelf.ui.components
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.drawWithCache
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.drawscope.drawIntoCanvas
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+import kotlin.random.Random
+
+/**
+ * The base surface for large areas of the app (screen backgrounds, cards).
+ * Paints [MaterialTheme]'s surface color plus a very faint, deterministic
+ * paper-grain speckle so big flat areas read as paper rather than a plain
+ * digital fill. The grain is intentionally subtle — this is restrained, not
+ * skeuomorphic parchment.
+ */
+@Composable
+fun PaperSurface(
+    modifier: Modifier = Modifier,
+    grain: Boolean = true,
+    contentPadding: Dp = 0.dp,
+    content: @Composable () -> Unit,
+) {
+    Box(
+        modifier = modifier
+            .background(MaterialTheme.colorScheme.surface)
+            .then(if (grain) Modifier.paperGrain() else Modifier)
+            .padding(contentPadding),
+    ) {
+        content()
+    }
+}
+
+/** Deterministic speckle grain, cheap enough to redraw every frame. */
+private fun Modifier.paperGrain(): Modifier = drawWithCache {
+    val random = Random(seed = 42)
+    val speckleCount = ((size.width * size.height) / 9000f).toInt().coerceIn(24, 900)
+    val speckles = List(speckleCount) {
+        Offset(random.nextFloat() * size.width, random.nextFloat() * size.height) to
+            (0.35f + random.nextFloat() * 0.5f)
+    }
+    onDrawWithContent {
+        drawContent()
+        drawIntoCanvas {
+            for ((offset, radiusScale) in speckles) {
+                drawCircle(
+                    color = Color.Black.copy(alpha = 0.018f * radiusScale),
+                    radius = 1.1f * radiusScale,
+                    center = offset,
+                )
+            }
+        }
+    }
+}
@@ -0,0 +1,100 @@
+package org.modg.bookshelf.ui.components
+
+import androidx.compose.animation.core.LinearEasing
+import androidx.compose.animation.core.RepeatMode
+import androidx.compose.animation.core.animateFloat
+import androidx.compose.animation.core.infiniteRepeatable
+import androidx.compose.animation.core.rememberInfiniteTransition
+import androidx.compose.animation.core.tween
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.graphicsLayer
+import androidx.compose.ui.unit.dp
+
+/**
+ * Presentation-only sync state for [SyncStatusBar]. The real sync engine
+ * (data.repo.SyncEngine) maps its richer state into this — never the other
+ * way around. Per SPEC: sync failure is a quiet status line, never a dialog.
+ */
+enum class SyncStatus {
+    Synced,
+    Syncing,
+    Offline,
+    Error,
+}
+
+/**
+ * A slim, quiet status line — never a blocking banner or dialog. Sits at the
+ * bottom of [BookshelfScaffold] screens.
+ */
+@Composable
+fun SyncStatusBar(
+    status: SyncStatus,
+    label: String,
+    modifier: Modifier = Modifier,
+) {
+    Row(
+        modifier = modifier
+            .fillMaxWidth()
+            .background(MaterialTheme.colorScheme.surfaceContainerLow)
+            .padding(horizontal = 16.dp, vertical = 8.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        StatusDot(status)
+        Text(
+            text = label,
+            style = MaterialTheme.typography.labelMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+        )
+    }
+}
+
+@Composable
+private fun StatusDot(status: SyncStatus) {
+    val color = when (status) {
+        SyncStatus.Synced -> MaterialTheme.colorScheme.secondary
+        SyncStatus.Syncing -> MaterialTheme.colorScheme.secondary
+        SyncStatus.Offline -> MaterialTheme.colorScheme.onSurfaceVariant
+        SyncStatus.Error -> MaterialTheme.colorScheme.error
+    }
+    if (status == SyncStatus.Syncing) {
+        val transition = rememberInfiniteTransition(label = "sync-pulse")
+        val alpha by transition.animateFloat(
+            initialValue = 0.3f,
+            targetValue = 1f,
+            animationSpec = infiniteRepeatable(
+                animation = tween(700, easing = LinearEasing),
+                repeatMode = RepeatMode.Reverse,
+            ),
+            label = "sync-pulse-alpha",
+        )
+        Dot(color = color, modifier = Modifier.graphicsLayer { this.alpha = alpha })
+    } else {
+        Dot(color = color)
+    }
+}
+
+@Composable
+private fun Dot(color: Color, modifier: Modifier = Modifier) {
+    Box(
+        modifier = modifier
+            .size(8.dp)
+            .clip(CircleShape)
+            .background(color),
+    )
+}
@@ -0,0 +1,57 @@
+package org.modg.bookshelf.ui.theme
+
+import androidx.compose.ui.graphics.Color
+
+// Palette straight from docs/SPEC.md — "feels like books": warm paper, dark
+// mahogany, gold + silver metallics. Do not add colors outside this family;
+// if a new role is needed, derive it from these rather than inventing a hue.
+
+// ---- Light ----
+val PaperLight = Color(0xFFF5EDE0)
+val PaperAltLight = Color(0xFFEDE3D2)
+val InkLight = Color(0xFF2B211A)
+val InkSoftLight = Color(0xFF5A4A3D)
+val MahoganyLight = Color(0xFF5C2E23)
+val MahoganyDeepLight = Color(0xFF3E1E17)
+val GoldLight = Color(0xFFC0932F)
+val GoldSoftLight = Color(0xFFD9B45B)
+val SilverLight = Color(0xFF9CA3AF)
+val SilverSoftLight = Color(0xFFC7CCD1)
+val ErrorLight = Color(0xFF8C3B2E)
+val ErrorContainerLight = Color(0xFFF2D9D1)
+val OnErrorContainerLight = Color(0xFF4A190F)
+
+// Extra surface tones derived from PaperLight/PaperAltLight for the M3
+// surface-container ladder (introduced after the base M3 ColorScheme; these
+// keep every elevation looking like a shade of paper, never grey).
+val SurfaceDimLight = Color(0xFFE4D8C5)
+val SurfaceBrightLight = Color(0xFFFBF6EC)
+val SurfaceContainerLowestLight = Color(0xFFFFFFFF)
+val SurfaceContainerLowLight = Color(0xFFF1E7D7)
+val SurfaceContainerLight = Color(0xFFEDE3D2)
+val SurfaceContainerHighLight = Color(0xFFE7DAC5)
+val SurfaceContainerHighestLight = Color(0xFFE0D0B7)
+
+// ---- Dark ----
+val GroundDark = Color(0xFF1C1411)
+val SurfaceDark = Color(0xFF241A15)
+val PaperTextDark = Color(0xFFE8DCC8)
+val MahoganyDark = Color(0xFF7A3E2F)
+val MahoganyDeepDark = Color(0xFF3E1E17)
+val GoldDark = Color(0xFFD9B45B)
+val SilverDark = Color(0xFFC7CCD1)
+val OnSurfaceVariantDark = Color(0xFFC7B9A3)
+val SurfaceVariantDark = Color(0xFF2E2119)
+val OutlineDark = Color(0xFF6B6F74)
+val OutlineVariantDark = Color(0xFF3A3D40)
+val ErrorDark = Color(0xFFC86A57)
+val ErrorContainerDark = Color(0xFF4A2620)
+val OnErrorContainerDark = Color(0xFFF2D9D1)
+
+val SurfaceDimDark = Color(0xFF1C1411)
+val SurfaceBrightDark = Color(0xFF3A2C22)
+val SurfaceContainerLowestDark = Color(0xFF140D0B)
+val SurfaceContainerLowDark = Color(0xFF211712)
+val SurfaceContainerDark = Color(0xFF271C16)
+val SurfaceContainerHighDark = Color(0xFF32241C)
+val SurfaceContainerHighestDark = Color(0xFF3D2C22)
@@ -0,0 +1,104 @@
+package org.modg.bookshelf.ui.theme
+
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.lightColorScheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.graphics.Color
+
+private val LightColors = lightColorScheme(
+    primary = MahoganyLight,
+    onPrimary = PaperLight,
+    primaryContainer = MahoganyDeepLight,
+    onPrimaryContainer = PaperLight,
+    secondary = GoldLight,
+    onSecondary = InkLight,
+    secondaryContainer = GoldSoftLight,
+    onSecondaryContainer = MahoganyDeepLight,
+    tertiary = SilverLight,
+    onTertiary = InkLight,
+    tertiaryContainer = SilverSoftLight,
+    onTertiaryContainer = InkLight,
+    error = ErrorLight,
+    onError = PaperLight,
+    errorContainer = ErrorContainerLight,
+    onErrorContainer = OnErrorContainerLight,
+    background = PaperLight,
+    onBackground = InkLight,
+    surface = PaperLight,
+    onSurface = InkLight,
+    surfaceVariant = PaperAltLight,
+    onSurfaceVariant = InkSoftLight,
+    outline = SilverLight,
+    outlineVariant = SilverSoftLight,
+    scrim = InkLight,
+    inverseSurface = InkLight,
+    inverseOnSurface = PaperLight,
+    inversePrimary = GoldSoftLight,
+    surfaceTint = MahoganyLight,
+    surfaceDim = SurfaceDimLight,
+    surfaceBright = SurfaceBrightLight,
+    surfaceContainerLowest = SurfaceContainerLowestLight,
+    surfaceContainerLow = SurfaceContainerLowLight,
+    surfaceContainer = SurfaceContainerLight,
+    surfaceContainerHigh = SurfaceContainerHighLight,
+    surfaceContainerHighest = SurfaceContainerHighestLight,
+)
+
+private val DarkColors = darkColorScheme(
+    primary = MahoganyDark,
+    onPrimary = PaperTextDark,
+    primaryContainer = MahoganyDeepDark,
+    onPrimaryContainer = PaperTextDark,
+    secondary = GoldDark,
+    onSecondary = GroundDark,
+    secondaryContainer = Color(0xFF4A3820),
+    onSecondaryContainer = GoldDark,
+    tertiary = SilverDark,
+    onTertiary = GroundDark,
+    tertiaryContainer = Color(0xFF3A3F45),
+    onTertiaryContainer = SilverDark,
+    error = ErrorDark,
+    onError = GroundDark,
+    errorContainer = ErrorContainerDark,
+    onErrorContainer = OnErrorContainerDark,
+    background = GroundDark,
+    onBackground = PaperTextDark,
+    surface = SurfaceDark,
+    onSurface = PaperTextDark,
+    surfaceVariant = SurfaceVariantDark,
+    onSurfaceVariant = OnSurfaceVariantDark,
+    outline = OutlineDark,
+    outlineVariant = OutlineVariantDark,
+    scrim = GroundDark,
+    inverseSurface = PaperLight,
+    inverseOnSurface = InkLight,
+    inversePrimary = MahoganyLight,
+    surfaceTint = MahoganyDark,
+    surfaceDim = SurfaceDimDark,
+    surfaceBright = SurfaceBrightDark,
+    surfaceContainerLowest = SurfaceContainerLowestDark,
+    surfaceContainerLow = SurfaceContainerLowDark,
+    surfaceContainer = SurfaceContainerDark,
+    surfaceContainerHigh = SurfaceContainerHighDark,
+    surfaceContainerHighest = SurfaceContainerHighestDark,
+)
+
+/**
+ * Bookshelf's Material3 theme. Dynamic color is intentionally never wired up
+ * here — a wallpaper-derived palette would fight the warm-paper-and-mahogany
+ * identity the SPEC calls for, so there is no dynamicColor parameter at all.
+ */
+@Composable
+fun BookshelfTheme(
+    darkTheme: Boolean = isSystemInDarkTheme(),
+    content: @Composable () -> Unit,
+) {
+    val colorScheme = if (darkTheme) DarkColors else LightColors
+    MaterialTheme(
+        colorScheme = colorScheme,
+        typography = BookshelfTypography,
+        content = content,
+    )
+}
@@ -0,0 +1,132 @@
+package org.modg.bookshelf.ui.theme
+
+import androidx.compose.material3.Typography
+import androidx.compose.ui.text.TextStyle
+import androidx.compose.ui.text.font.Font
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontStyle
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.sp
+import org.modg.bookshelf.R
+
+// Literata (OFL, bundled in res/font — see LICENSE-Literata-OFL.txt) is the
+// serif voice for anything that reads as a title or heading: it's what makes
+// this app feel like a shelf of books rather than a generic list app. Body
+// and UI copy stay on the system sans so long paragraphs (descriptions,
+// notes) stay easy to read at small sizes.
+val Literata = FontFamily(
+    Font(R.font.literata_regular, FontWeight.Normal),
+    Font(R.font.literata_italic, FontWeight.Normal, FontStyle.Italic),
+    Font(R.font.literata_medium, FontWeight.Medium),
+    Font(R.font.literata_medium_italic, FontWeight.Medium, FontStyle.Italic),
+    Font(R.font.literata_semibold, FontWeight.SemiBold),
+    Font(R.font.literata_semibold_italic, FontWeight.SemiBold, FontStyle.Italic),
+    Font(R.font.literata_bold, FontWeight.Bold),
+    Font(R.font.literata_bold_italic, FontWeight.Bold, FontStyle.Italic),
+)
+
+val SystemSans = FontFamily.Default
+
+// Generous line-height throughout per SPEC ("Generous line-height").
+val BookshelfTypography = Typography(
+    displayLarge = TextStyle(
+        fontFamily = Literata,
+        fontWeight = FontWeight.SemiBold,
+        fontSize = 57.sp,
+        lineHeight = 68.sp,
+        letterSpacing = (-0.25).sp,
+    ),
+    displayMedium = TextStyle(
+        fontFamily = Literata,
+        fontWeight = FontWeight.SemiBold,
+        fontSize = 45.sp,
+        lineHeight = 56.sp,
+    ),
+    displaySmall = TextStyle(
+        fontFamily = Literata,
+        fontWeight = FontWeight.Medium,
+        fontSize = 36.sp,
+        lineHeight = 46.sp,
+    ),
+    headlineLarge = TextStyle(
+        fontFamily = Literata,
+        fontWeight = FontWeight.Medium,
+        fontSize = 32.sp,
+        lineHeight = 42.sp,
+    ),
+    headlineMedium = TextStyle(
+        fontFamily = Literata,
+        fontWeight = FontWeight.Medium,
+        fontSize = 28.sp,
+        lineHeight = 38.sp,
+    ),
+    headlineSmall = TextStyle(
+        fontFamily = Literata,
+        fontWeight = FontWeight.Medium,
+        fontSize = 24.sp,
+        lineHeight = 34.sp,
+    ),
+    titleLarge = TextStyle(
+        // Topbar / screen titles — the "serif title" the scaffold calls for.
+        fontFamily = Literata,
+        fontWeight = FontWeight.SemiBold,
+        fontSize = 22.sp,
+        lineHeight = 30.sp,
+    ),
+    titleMedium = TextStyle(
+        fontFamily = Literata,
+        fontWeight = FontWeight.Medium,
+        fontSize = 18.sp,
+        lineHeight = 26.sp,
+        letterSpacing = 0.15.sp,
+    ),
+    titleSmall = TextStyle(
+        fontFamily = Literata,
+        fontWeight = FontWeight.Medium,
+        fontSize = 16.sp,
+        lineHeight = 24.sp,
+        letterSpacing = 0.1.sp,
+    ),
+    bodyLarge = TextStyle(
+        fontFamily = SystemSans,
+        fontWeight = FontWeight.Normal,
+        fontSize = 16.sp,
+        lineHeight = 26.sp,
+        letterSpacing = 0.5.sp,
+    ),
+    bodyMedium = TextStyle(
+        fontFamily = SystemSans,
+        fontWeight = FontWeight.Normal,
+        fontSize = 14.sp,
+        lineHeight = 22.sp,
+        letterSpacing = 0.25.sp,
+    ),
+    bodySmall = TextStyle(
+        fontFamily = SystemSans,
+        fontWeight = FontWeight.Normal,
+        fontSize = 12.sp,
+        lineHeight = 18.sp,
+        letterSpacing = 0.4.sp,
+    ),
+    labelLarge = TextStyle(
+        fontFamily = SystemSans,
+        fontWeight = FontWeight.Medium,
+        fontSize = 14.sp,
+        lineHeight = 20.sp,
+        letterSpacing = 0.1.sp,
+    ),
+    labelMedium = TextStyle(
+        fontFamily = SystemSans,
+        fontWeight = FontWeight.Medium,
+        fontSize = 12.sp,
+        lineHeight = 18.sp,
+        letterSpacing = 0.5.sp,
+    ),
+    labelSmall = TextStyle(
+        fontFamily = SystemSans,
+        fontWeight = FontWeight.Medium,
+        fontSize = 11.sp,
+        lineHeight = 16.sp,
+        letterSpacing = 0.5.sp,
+    ),
+)
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <path
+        android:fillColor="#5C2E23"
+        android:pathData="M0,0h108v108h-108z" />
+</vector>
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <!-- Three book spines, gold on mahogany, standing side by side. -->
+    <path
+        android:fillColor="#D9B45B"
+        android:pathData="M34,28 h10 v52 h-10 z" />
+    <path
+        android:fillColor="#C0932F"
+        android:pathData="M48,24 h10 v56 h-10 z" />
+    <path
+        android:fillColor="#D9B45B"
+        android:pathData="M62,30 h10 v50 h-10 z" />
+    <path
+        android:fillColor="#E8DCC8"
+        android:pathData="M30,80 h48 v6 h-48 z" />
+</vector>
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@drawable/ic_launcher_background" />
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@drawable/ic_launcher_background" />
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <style name="Theme.Bookshelf" parent="android:Theme.Material.NoActionBar">
+        <item name="android:windowBackground">@color/ground_dark</item>
+        <item name="android:statusBarColor">@color/ground_dark</item>
+        <item name="android:windowLightStatusBar">false</item>
+    </style>
+</resources>
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Mirrors ui.theme.Color.kt; used only for the pre-Compose XML window theme. -->
+    <color name="paper_light">#F5EDE0</color>
+    <color name="ground_dark">#1C1411</color>
+</resources>
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">Bookshelf</string>
+</resources>
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Base application theme. The real Material3 theming happens in Compose
+         (ui.theme.BookshelfTheme); this XML theme only needs to cover the
+         window background shown before the first Compose frame. -->
+    <style name="Theme.Bookshelf" parent="android:Theme.Material.Light.NoActionBar">
+        <item name="android:windowBackground">@color/paper_light</item>
+        <item name="android:statusBarColor">@color/paper_light</item>
+        <item name="android:windowLightStatusBar">true</item>
+    </style>
+</resources>
@@ -0,0 +1,114 @@
+package org.modg.bookshelf.ui.components
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.Text
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import app.cash.paparazzi.DeviceConfig
+import app.cash.paparazzi.Paparazzi
+import org.junit.Rule
+import org.junit.Test
+import org.modg.bookshelf.ui.theme.BookshelfTheme
+
+/**
+ * Renders the wave-2 component set to PNG on the JVM (no device/emulator).
+ * Every component gets a light and a dark snapshot so both themes required
+ * by the SPEC are actually exercised, not just assumed to work.
+ *
+ * Run `./gradlew recordPaparazziDebug` to (re)record golden PNGs under
+ * src/test/snapshots, or `./gradlew verifyPaparazziDebug` to diff against them.
+ */
+class ComponentGalleryPaparazziTest {
+
+    @get:Rule
+    val paparazzi = Paparazzi(deviceConfig = DeviceConfig.PIXEL_6)
+
+    @Test
+    fun scaffoldAndDividerLight() = snapshotBothThemes("scaffold") {
+        BookshelfScaffold(
+            title = "Bookshelf",
+            syncStatusBar = { SyncStatusBar(status = SyncStatus.Synced, label = "Synced") },
+        ) { padding ->
+            PaperSurface(modifier = Modifier.fillMaxWidth().padding(padding)) {
+                Column(modifier = Modifier.padding(16.dp)) {
+                    Text("A page of paper, with a gold rule below the title bar.")
+                    GoldDivider(modifier = Modifier.padding(vertical = 16.dp))
+                    Text("Restrained, not skeuomorphic.")
+                }
+            }
+        }
+    }
+
+    // Only the "no coverUrl" path is snapshotted here: it's the one
+    // deterministic BookCover state (no network I/O). The loading/error
+    // states are real code paths (see BookCover.kt's CoverPlaceholder /
+    // AsyncImagePainter.State.Error branch) but depend on an async Coil
+    // network load settling inside a single synchronous Paparazzi frame,
+    // which isn't reliable on a sandboxed JVM test — see BUILD_NOTES.md.
+    @Test
+    fun bookCoverPlaceholder() = snapshotBothThemes("book-cover") {
+        androidx.compose.foundation.layout.Row(
+            modifier = Modifier.padding(24.dp).fillMaxWidth(),
+            horizontalArrangement = Arrangement.spacedBy(12.dp),
+        ) {
+            BookCover(
+                coverUrl = null,
+                contentDescription = "No cover on file",
+                modifier = Modifier.weight(1f),
+            )
+            BookCover(
+                coverUrl = null,
+                contentDescription = "Another shelf slot",
+                modifier = Modifier.weight(1f),
+            )
+        }
+    }
+
+    @Test
+    fun buttons() = snapshotBothThemes("buttons") {
+        Column(modifier = Modifier.padding(24.dp), verticalArrangement = Arrangement.spacedBy(12.dp)) {
+            PrimaryButton(text = "Save", onClick = {})
+            SecondaryButton(text = "Skip", onClick = {})
+            PrimaryButton(text = "Disabled", onClick = {}, enabled = false)
+        }
+    }
+
+    @Test
+    fun emptyState() = snapshotBothThemes("empty-state") {
+        EmptyState(
+            title = "Your shelves are empty",
+            message = "Scan a barcode to add your first book.",
+            action = { PrimaryButton(text = "Scan a book", onClick = {}) },
+        )
+    }
+
+    @Test
+    fun syncStatusBarStates() = snapshotBothThemes("sync-status-bar") {
+        Column(verticalArrangement = Arrangement.spacedBy(1.dp)) {
+            SyncStatusBar(status = SyncStatus.Synced, label = "Synced • 2m ago")
+            SyncStatusBar(status = SyncStatus.Syncing, label = "Syncing…")
+            SyncStatusBar(status = SyncStatus.Offline, label = "Offline — will sync later")
+            SyncStatusBar(status = SyncStatus.Error, label = "Couldn't reach server")
+        }
+    }
+
+    /** Snapshots [content] once under the light theme and once under dark. */
+    private fun snapshotBothThemes(
+        name: String,
+        content: @androidx.compose.runtime.Composable () -> Unit,
+    ) {
+        paparazzi.snapshot(name = "$name-light") {
+            BookshelfTheme(darkTheme = false) {
+                PaperSurface { content() }
+            }
+        }
+        paparazzi.snapshot(name = "$name-dark") {
+            BookshelfTheme(darkTheme = true) {
+                PaperSurface { content() }
+            }
+        }
+    }
+}