feat(gallery): Gallery templates, ThemeDesign, and Mustache rendering

CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **`ThemeDesign` domain model** — composes from Gallery-native types (`GalleryPalette` + `[Decoration]`) for structured theme output. Generated by AI once, applied deterministically to all screenshots
+- **`ThemeDesignApplier`** — re-renders through `GalleryHTMLRenderer.renderScreen()` pipeline with overridden palette and merged decorations (no HTML patching)
+- **`GalleryPalette.textColor`** — optional explicit text color, overrides the auto-detect heuristic
+- **`Decoration.label()` shape** — text/emoji decorative elements (e.g. `Decoration(shape: .label("✨"), ...)`)
+- **`DecorationAnimation`** — float, drift, pulse, spin, twinkle animations for decorations
+- **`ScreenLayout.withDecorations()`** — creates a copy with additional decorations
+- **`GalleryHTMLRenderer.renderDecorations()`** — renders `ScreenLayout.decorations` (previously dead code) using `cqi` units
+- **`buildDesignContext()` on `ScreenTheme`** — prompt method that instructs AI to return `ThemeDesign` JSON
+- **`design()` on `ThemeProvider`/`ThemeRepository`** — generate a ThemeDesign from AI in one call
+- **`--design-only` / `--apply-design` CLI flags** — batch theme workflow
+- **REST endpoints** — `POST /app-shots/themes/design` and `POST /app-shots/themes/apply-design`
+
+### Changed
+- **`GalleryHTMLRenderer` refactored to Mustache templates** — all HTML extracted from Swift into 7 `.mustache` template files using [swift-mustache](https://github.com/hummingbird-project/swift-mustache). The renderer only builds context dictionaries; all HTML, CSS colors (via CSS custom properties in `theme-vars.mustache`), and keyframe animations live in templates. Templates are pre-compiled at startup via `MustacheLibrary` for performance. Preview rendering is cached per template ID.
+- **`DecorationShape.displayCharacter`** — computed property on the model instead of renderer logic
+- **`GalleryPalette.isLight` + `headlineColor`** — theme detection and text color derivation moved from renderer to palette
+- **`Decoration` extended** — new optional fields: `color`, `background`, `borderRadius`, `animation`
+- **Theme selection no longer requires auto-compose** — clicking a theme applies immediately to slides with existing preview HTML via `ThemeDesign` (1 AI call for design, then deterministic apply to all slides)
+- **Blitz plugin: `design()` implemented** — generates `ThemeDesign` via compose bridge `mode: "design"`, enabling the fast design→apply-design flow
+
 ---
 
 ## [0.1.65] - 2026-04-06

Package.swift

@@ -17,6 +17,7 @@ let package = Package(
         .package(url: "https://github.com/steipete/SweetCookieKit.git", from: "0.3.0"),
         .package(url: "https://github.com/hummingbird-project/hummingbird.git", exact: "2.21.1"),
         .package(url: "https://github.com/hummingbird-project/hummingbird-websocket.git", from: "2.6.0"),
+        .package(url: "https://github.com/hummingbird-project/swift-mustache.git", from: "2.0.2"),
     ],
     targets: [
         .target(
@@ -31,7 +32,9 @@ let package = Package(
             name: "Domain",
             dependencies: [
                 .product(name: "Mockable", package: "Mockable"),
+                .product(name: "Mustache", package: "swift-mustache"),
             ],
+            resources: [.copy("Screenshots/Gallery/Resources")],
             swiftSettings: [.define("MOCKING")]
         ),
         .target(

Sources/ASCCommand/ClientProvider.swift

@@ -240,6 +240,10 @@ struct ClientProvider {
         AggregateTemplateRepository.shared
     }
 
+    static func makeGalleryTemplateRepository() -> AggregateGalleryTemplateRepository {
+        AggregateGalleryTemplateRepository.shared
+    }
+
     static func makeThemeRepository() -> AggregateThemeRepository {
         AggregateThemeRepository.shared
     }

Sources/ASCCommand/Commands/AppShots/AppShotsCommand.swift

@@ -5,6 +5,6 @@ struct AppShotsCommand: AsyncParsableCommand {
     static let configuration = CommandConfiguration(
         commandName: "app-shots",
         abstract: "AI-powered App Store screenshot planning and generation",
-        subcommands: [AppShotsTemplatesCommand.self, AppShotsThemesCommand.self, AppShotsGenerate.self, AppShotsExport.self, AppShotsConfig.self]
+        subcommands: [AppShotsTemplatesCommand.self, AppShotsGalleryTemplatesCommand.self, AppShotsThemesCommand.self, AppShotsGenerate.self, AppShotsExport.self, AppShotsConfig.self]
     )
 }

Sources/ASCCommand/Commands/AppShots/AppShotsExport.swift

@@ -43,15 +43,13 @@ struct AppShotsExport: AsyncParsableCommand {
     static func renderToPNG(html: String, width: Int = 1320, height: Int = 2868, renderer: any HTMLRenderer) async throws -> Data {
         var htmlContent = html
 
-        // Ensure preview fills the full viewport for image export
-        // Themed HTML from `themes apply` uses width:320px — replace with 100%
+        // Convert 320px preview container to fill viewport for export
         if htmlContent.contains("width:320px") {
             htmlContent = htmlContent
-                .replacingOccurrences(of: "width:320px", with: "width:100%;height:100%")
-                .replacingOccurrences(of: "min-height:100vh;background:#111", with: "margin:0;overflow:hidden")
+                .replacingOccurrences(of: "width:320px;aspect-ratio:1320/2868;container-type:inline-size", with: "width:100%;height:100%;container-type:inline-size")
                 .replacingOccurrences(of: "display:flex;justify-content:center;align-items:center;min-height:100vh;background:#111", with: "margin:0;overflow:hidden")
             if !htmlContent.contains("html,body{") {
-                htmlContent = htmlContent.replacingOccurrences(of: "box-sizing:border-box}", with: "box-sizing:border-box}html,body{width:100%;height:100%}")
+                htmlContent = htmlContent.replacingOccurrences(of: "box-sizing:border-box}", with: "box-sizing:border-box}html,body{width:100%;height:100%;margin:0;overflow:hidden}")
             }
         }
 

Sources/ASCCommand/Commands/AppShots/AppShotsGalleryTemplates.swift

@@ -0,0 +1,77 @@
+import ArgumentParser
+import Domain
+import Foundation
+
+struct AppShotsGalleryTemplatesCommand: AsyncParsableCommand {
+    static let configuration = CommandConfiguration(
+        commandName: "gallery-templates",
+        abstract: "Browse gallery templates (multi-screen sets)",
+        subcommands: [AppShotsGalleryTemplatesList.self, AppShotsGalleryTemplatesGet.self]
+    )
+}
+
+// MARK: - List
+
+struct AppShotsGalleryTemplatesList: AsyncParsableCommand {
+    static let configuration = CommandConfiguration(
+        commandName: "list",
+        abstract: "List available gallery templates"
+    )
+
+    @OptionGroup var globals: GlobalOptions
+
+    func run() async throws {
+        let repo = ClientProvider.makeGalleryTemplateRepository()
+        print(try await execute(repo: repo))
+    }
+
+    func execute(repo: any GalleryTemplateRepository, affordanceMode: AffordanceMode = .cli) async throws -> String {
+        let galleries = try await repo.listGalleries()
+        let formatter = OutputFormatter(format: globals.outputFormat, pretty: globals.pretty)
+        return try formatter.formatAgentItems(
+            galleries,
+            headers: ["App Name", "Shots", "Template", "Ready"],
+            rowMapper: { [$0.appName, "\($0.shotCount)", $0.template?.name ?? "-", $0.isReady ? "✓" : "✗"] },
+            affordanceMode: affordanceMode
+        )
+    }
+}
+
+// MARK: - Get
+
+struct AppShotsGalleryTemplatesGet: AsyncParsableCommand {
+    static let configuration = CommandConfiguration(
+        commandName: "get",
+        abstract: "Get details of a specific gallery template"
+    )
+
+    @OptionGroup var globals: GlobalOptions
+
+    @Option(name: .long, help: "Gallery template ID")
+    var id: String
+
+    @Flag(name: .long, help: "Output self-contained HTML gallery preview page")
+    var preview: Bool = false
+
+    func run() async throws {
+        let repo = ClientProvider.makeGalleryTemplateRepository()
+        print(try await execute(repo: repo))
+    }
+
+    func execute(repo: any GalleryTemplateRepository) async throws -> String {
+        guard let gallery = try await repo.getGallery(templateId: id) else {
+            throw ValidationError("Gallery template '\(id)' not found. Run `asc app-shots gallery-templates list` to see available templates.")
+        }
+
+        if preview {
+            return gallery.previewHTML
+        }
+
+        let formatter = OutputFormatter(format: globals.outputFormat, pretty: globals.pretty)
+        return try formatter.formatAgentItems(
+            [gallery],
+            headers: ["App Name", "Shots", "Template", "Ready"],
+            rowMapper: { [$0.appName, "\($0.shotCount)", $0.template?.name ?? "-", $0.isReady ? "✓" : "✗"] }
+        )
+    }
+}

Sources/ASCCommand/Commands/AppShots/AppShotsTemplates.swift

@@ -160,23 +160,30 @@ struct AppShotsTemplatesApply: AsyncParsableCommand {
             throw ValidationError("Template '\(id)' not found. Run `asc app-shots templates list` to see available templates.")
         }
 
+        let shot = AppShot(screenshot: screenshot, type: .feature)
+        shot.headline = headline
+        shot.body = subtitle
+        shot.tagline = tagline
+
         if preview == .image, let renderer {
-            let content = TemplateContent(headline: headline, subtitle: subtitle, tagline: tagline, screenshotFile: screenshot)
-            let html = template.apply(content: content, fillViewport: true)
+            let html = template.apply(shot: shot, fillViewport: true)
             return try await renderToImage(html: html, renderer: renderer)
         }
 
         if preview == .html {
-            let content = TemplateContent(headline: headline, subtitle: subtitle, tagline: tagline, screenshotFile: URL(fileURLWithPath: screenshot).lastPathComponent)
-            return template.apply(content: content)
+            let shotForHTML = AppShot(screenshot: URL(fileURLWithPath: screenshot).lastPathComponent, type: .feature)
+            shotForHTML.headline = headline
+            shotForHTML.body = subtitle
+            shotForHTML.tagline = tagline
+            return template.apply(shot: shotForHTML)
         }
 
-        let screen = ScreenDesign(index: 0, template: template, screenshotFile: screenshot, heading: headline, subheading: subtitle ?? "")
+        // Return the shot as JSON output
         let formatter = OutputFormatter(format: globals.outputFormat, pretty: globals.pretty)
         return try formatter.formatAgentItems(
-            [screen],
-            headers: ["Heading", "Screenshot", "Template", "Complete"],
-            rowMapper: { [$0.heading, $0.screenshotFile, $0.template?.name ?? "-", $0.isComplete ? "✓" : "✗"] }
+            [shot],
+            headers: ["Headline", "Screenshot", "Template", "Configured"],
+            rowMapper: { [$0.headline ?? "-", $0.screenshot, template.name, $0.isConfigured ? "✓" : "✗"] }
         )
     }
 

Sources/ASCCommand/Commands/AppShots/AppShotsThemes.swift

@@ -6,7 +6,13 @@ struct AppShotsThemesCommand: AsyncParsableCommand {
     static let configuration = CommandConfiguration(
         commandName: "themes",
         abstract: "Browse visual themes for screenshot composition",
-        subcommands: [AppShotsThemesList.self, AppShotsThemesGet.self, AppShotsThemesApply.self]
+        subcommands: [
+            AppShotsThemesList.self,
+            AppShotsThemesGet.self,
+            AppShotsThemesDesign.self,
+            AppShotsThemesApplyDesign.self,
+            AppShotsThemesApply.self,
+        ]
     )
 }
 
@@ -76,12 +82,125 @@ struct AppShotsThemesGet: AsyncParsableCommand {
     }
 }
 
-// MARK: - Apply
+// MARK: - Design (generate ThemeDesign JSON — 1 AI call)
+
+struct AppShotsThemesDesign: AsyncParsableCommand {
+    static let configuration = CommandConfiguration(
+        commandName: "design",
+        abstract: "Generate a ThemeDesign (palette + decorations) from AI — one call, reusable"
+    )
+
+    @OptionGroup var globals: GlobalOptions
+
+    @Option(name: .long, help: "Theme ID")
+    var id: String
+
+    func run() async throws {
+        let repo = ClientProvider.makeThemeRepository()
+        print(try await execute(themeRepo: repo))
+    }
+
+    func execute(themeRepo: any ThemeRepository) async throws -> String {
+        let design = try await themeRepo.design(themeId: id)
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        let data = try encoder.encode(design)
+        return String(data: data, encoding: .utf8) ?? "{}"
+    }
+}
+
+// MARK: - Apply Design (deterministic — no AI)
+
+struct AppShotsThemesApplyDesign: AsyncParsableCommand {
+    static let configuration = CommandConfiguration(
+        commandName: "apply-design",
+        abstract: "Apply a cached ThemeDesign to a template — deterministic, no AI"
+    )
+
+    @OptionGroup var globals: GlobalOptions
+
+    @Option(name: .long, help: "Path to ThemeDesign JSON file")
+    var design: String
+
+    @Option(name: .long, help: "Template ID")
+    var template: String
+
+    @Option(name: .long, help: "Path to screenshot file")
+    var screenshot: String
+
+    @Option(name: .long, help: "Headline text")
+    var headline: String = "Your Headline"
+
+    @Option(name: .long, help: "Subtitle text")
+    var subtitle: String?
+
+    @Option(name: .long, help: "Tagline text")
+    var tagline: String?
+
+    @Option(name: .long, help: "Preview format: html (default) or image")
+    var preview: PreviewFormat?
+
+    @Option(name: .long, help: "Output PNG path (for --preview image)")
+    var imageOutput: String?
+
+    @Option(name: .long, help: "Canvas width in pixels")
+    var canvasWidth: Int = 1320
+
+    @Option(name: .long, help: "Canvas height in pixels")
+    var canvasHeight: Int = 2868
+
+    func run() async throws {
+        let templateRepo = ClientProvider.makeTemplateRepository()
+        if preview == .image {
+            let renderer = ClientProvider.makeHTMLRenderer()
+            print(try await execute(templateRepo: templateRepo, renderer: renderer))
+        } else {
+            print(try await execute(templateRepo: templateRepo))
+        }
+    }
+
+    func execute(templateRepo: any TemplateRepository, renderer: (any HTMLRenderer)? = nil) async throws -> String {
+        let designData = try Data(contentsOf: URL(fileURLWithPath: design))
+        let themeDesign = try JSONDecoder().decode(ThemeDesign.self, from: designData)
+
+        guard let tmpl = try await templateRepo.getTemplate(id: template) else {
+            throw ValidationError("Template '\(template)' not found.")
+        }
+
+        let screenshotFile = (preview == .image) ? screenshot : URL(fileURLWithPath: screenshot).lastPathComponent
+        let shot = AppShot(screenshot: screenshotFile, type: .feature)
+        shot.headline = headline
+        shot.body = subtitle
+        shot.tagline = tagline
+
+        let themedHTML = ThemeDesignApplier.apply(themeDesign, shot: shot, screenLayout: tmpl.screenLayout)
+        let page = ThemedPage(body: themedHTML, width: canvasWidth, height: canvasHeight, fillViewport: preview == .image)
+
+        if preview == .image, let renderer {
+            return try await renderToImage(html: page.html, renderer: renderer)
+        }
+
+        return page.html
+    }
+
+    private func renderToImage(html: String, renderer: any HTMLRenderer) async throws -> String {
+        let pngData = try await renderer.render(html: html, width: canvasWidth, height: canvasHeight)
+        let outputPath = imageOutput ?? ".asc/app-shots/output/screen-0.png"
+        let fileURL = URL(fileURLWithPath: outputPath)
+        try FileManager.default.createDirectory(at: fileURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+        try pngData.write(to: fileURL)
+        let result: [String: Any] = ["exported": outputPath, "width": canvasWidth, "height": canvasHeight, "bytes": pngData.count]
+        let data = try JSONSerialization.data(withJSONObject: result, options: [.prettyPrinted, .sortedKeys])
+        return String(data: data, encoding: .utf8) ?? "{}"
+    }
+}
+
+// MARK: - Apply (full AI restyle — fallback)
 
 struct AppShotsThemesApply: AsyncParsableCommand {
     static let configuration = CommandConfiguration(
         commandName: "apply",
-        abstract: "Apply a theme to a template — renders deterministic layout, then AI restyles"
+        abstract: "Apply a theme via full AI restyle"
     )
 
     @OptionGroup var globals: GlobalOptions
@@ -133,10 +252,12 @@ struct AppShotsThemesApply: AsyncParsableCommand {
         }
 
         let screenshotFile = (preview == .image) ? screenshot : URL(fileURLWithPath: screenshot).lastPathComponent
-        let content = TemplateContent(headline: headline, subtitle: subtitle, tagline: tagline, screenshotFile: screenshotFile)
+        let shot = AppShot(screenshot: screenshotFile, type: .feature)
+        shot.headline = headline
+        shot.body = subtitle
+        shot.tagline = tagline
 
-        // Domain: template renders fragment, theme repo composes, ThemedPage wraps
-        let fragment = tmpl.renderFragment(content: content)
+        let fragment = tmpl.renderFragment(shot: shot)
         let themedHTML = try await themeRepo.compose(themeId: theme, html: fragment, canvasWidth: canvasWidth, canvasHeight: canvasHeight)
         let page = ThemedPage(body: themedHTML, width: canvasWidth, height: canvasHeight, fillViewport: preview == .image)
 
@@ -157,6 +278,4 @@ struct AppShotsThemesApply: AsyncParsableCommand {
         let data = try JSONSerialization.data(withJSONObject: result, options: [.prettyPrinted, .sortedKeys])
         return String(data: data, encoding: .utf8) ?? "{}"
     }
-
-    // wrapInPage logic moved to Domain/ScreenshotPlans/ThemedPage.swift
 }