palette async loading + cache (v1.5)

[2dubu]

Summary

• New SwiftUI AsyncPaletteGraphic + UIKit AsyncPaletteGraphicView — async-loading siblings of v1.4's PaletteGraphic pair. Pass an ImageSource (URL / Data / CGImage) and the view extracts the palette internally before rendering.
• New public PaletteCache (process-wide .shared singleton + DI-friendly instances) memoizes resolved palettes — eliminates redundant extraction across list cells, navigation back-and-forth, and shared brand images.
• Env-driven cross-fade AsyncPaletteGraphicTransition (SwiftUI) + per-instance Transition (UIKit), coordinated 0.20s / 0.35s / 0.50s presets matching KarrotUIKit/AsyncImage precedent. Cache hits skip the transition (sync resolution → no animation).
• Two SwiftUI init styles: simple convenience (auto-renders PaletteGraphic with placeholder slot) and phase content closure mirroring Apple's AsyncImage(url:content:) for telemetry / secondary UI composition / custom error rendering.

What's changed

Library

• Sources/PaletteKit/Graphic/Async/:
  • AsyncPaletteGraphic (SwiftUI View) — generic over Content: View, two public inits
  • AsyncPaletteGraphicView (UIKit UIView subclass) — pair of PaletteGraphicView
  • AsyncPaletteGraphicLoader — internal @MainActor ObservableObject, shared by both views
  • PaletteCache — public NSCache wrapper, countLimit = 100, String-keyed
  • AsyncPaletteGraphicTransition + View.asyncPaletteGraphicTransition(_:) modifier
  • AsyncPaletteGraphicPhase — public enum (.empty / .loading / .success / .failure)
• Sources/PaletteKit/Graphic/SwatchStrategy.swift — extracted from former CardPalette.swift
• Folder renames for naming consistency: Card/ → Graphic/, Support/ → Logging/

Tests

• 4 new test files — PaletteCacheTests, AsyncPaletteGraphicLoaderTests, AsyncPaletteGraphicTransitionTests, AsyncPaletteGraphicViewTests
• Strategy fallback hex-assertion tests ported into PaletteGraphicRendererTests after the GraphicPalette type was dropped
• 35 tests across 8 suites, all green on macOS host + iOS Simulator

Docs

• New DocC article AsyncLoading.md covering both init styles, caching, transitions, error handling
• Tutorials/Card.md gains async section
• PaletteKit.md Topics catalog gets Async loading subsection
• README: install snippet bumped to 1.5.0, async example added next to ### Generate a graphic, Roadmap updated (v1.5 ✅, v1.6 PaletteMeshGraphic listed)

Migration

This release is largely additive but contains two intentional breaks made under pre-tag low-user-count conditions:

Before (v1.4)	After (v1.5)
CardPalette public type	Removed. Use PaletteGraphic/AsyncPaletteGraphic directly; the resolved center/edge logic is internal to the renderer. Demo lab includes a local ResolvedColors struct if you need the same 4-color resolution pattern as a reference.
Sources/PaletteKit/Card/	Sources/PaletteKit/Graphic/ (file-level rename only — no API change beyond the CardPalette removal above)

API quick-look

// Simple — auto-renders PaletteGraphic on success
AsyncPaletteGraphic(image: .url(url)) {
    Color.gray.opacity(0.1)
}
.frame(width: 320, height: 320)
.clipShape(RoundedRectangle(cornerRadius: 24))

// Phase-based — caller renders every phase (telemetry, side-by-side composition, custom error UI)
AsyncPaletteGraphic(image: .url(url)) { phase in
    switch phase {
    case .empty, .loading: ProgressView()
    case .success(let palette, let swatches, _):
        PaletteGraphic(palette: palette, swatches: swatches, configuration: .init())
    case .failure(let error):
        Text(error.localizedDescription)
    }
}

// UIKit
let view = AsyncPaletteGraphicView(frame: .zero)
view.imageSource = .url(url)
view.onSuccess = { palette, swatches in /* analytics */ }

// Cache — automatic for URL sources; sign-out / theme reset clears
PaletteCache.shared.clear()

// Transition (SwiftUI env-driven)
NavigationStack { cardListView }
    .asyncPaletteGraphicTransition(.slow)   // .normal / .slow / .extraSlow / .custom(_:duration:)

Test plan

• swift build clean on macOS host
• swift test 35/35 pass
• Xcode iOS Simulator build of PaletteKitDemo succeeds (no new warnings introduced)
• Demo Card lab still renders + exports unchanged after Card→Graphic folder rename and CardPalette→GraphicPalette type removal
• Manual smoke: paste a URL into a consumer app, verify placeholder → graphic transition + cache hit on repeat load