Thumbnail API

pub use sb_thumbnails::{
    Pipeline, ThumbnailRequest, ThumbnailResult,
    CacheLayout, Error, Result,
    MAX_DIM, STANDARD_SIZES, JPEG_QUALITY,
    detect_format, clamp_size, FormatKind,
};

pub struct Pipeline {
    cache: CacheLayout,
}
 
impl Pipeline {
    pub fn new(cache: CacheLayout) -> Self;
    pub fn cache(&self) -> &CacheLayout;
    pub fn supported_formats(&self) -> Vec<&'static str>;
    pub async fn generate(&self, req: ThumbnailRequest) -> Result<ThumbnailResult>;
}

pub struct ThumbnailRequest {
    pub source_path: PathBuf,           // Path to the source file
    pub tenant_id: String,              // Tenant scope for cache layout
    pub asset_id: String,               // Stable asset ID for output keys
    pub format_hint: Option<String>,    // Optional mime type or extension hint
    pub sizes: Vec<u32>,                // Sizes to generate (default: 64, 256, 512)
    pub generate_gif_preview: bool,     // Generate animated GIF preview (video/gif)
    pub generate_3d_views: bool,        // Generate 4 view thumbnails (3D models)
}

pub struct ThumbnailResult {
    pub asset_id: String,           // The asset this result is for
    pub format: Option<String>,     // Detected format slug
    pub generated: Vec<PathBuf>,    // List of generated thumbnail file paths
    pub errors: Vec<String>,        // Per-size errors (does not short-circuit)
}

pub struct CacheLayout {
    // Private fields
}
 
impl CacheLayout {
    pub fn new(root: impl Into<PathBuf>, tenant_id: impl Into<String>) -> Result<Self>;
    pub fn root(&self) -> &Path;
    pub fn tenant_id(&self) -> &str;
    pub fn entity_key(&self, entity_type: &str, id: &str) -> String;
    pub fn thumbnail_key(&self, asset_id: &str, size: u32) -> String;
    pub fn gif_preview_key(&self, asset_id: &str) -> String;
    pub fn model3d_view_key(&self, asset_id: &str, view: Model3dView) -> String;
    pub fn local_path(&self, key: &str) -> PathBuf;
}

pub fn detect_format(path: &Path, hint: Option<&str>) -> Option<String>;
pub fn clamp_size(size: u32) -> u32;
 
pub enum FormatKind {
    Raster,
    Svg,
    Pdf,
    Video,
    Model3d,
}
 
impl FormatKind {
    pub fn from_slug(slug: &str) -> Option<Self>;
}

~/.studiobrain/cache/{tenant_id}/
  entities/{type}/{id}.md
  thumbnails/{asset_id}_64.jpg
  thumbnails/{asset_id}_256.jpg
  thumbnails/{asset_id}_512.jpg
  thumbnails/{asset_id}_gif.gif      // animated preview (video/gif)
  thumbnails/{asset_id}_3d_v1.jpg    // front
  thumbnails/{asset_id}_3d_v2.jpg    // side
  thumbnails/{asset_id}_3d_v3.jpg    // top
  thumbnails/{asset_id}_3d_v4.jpg    // iso

use sb_thumbnails::{CacheLayout, Pipeline, ThumbnailRequest, STANDARD_SIZES};
 
// Set up cache for a tenant
let cache = CacheLayout::new("/home/user/.studiobrain/cache", "tenant-abc")?;
let pipeline = Pipeline::new(cache);
 
// Generate thumbnails for a source asset
let req = ThumbnailRequest::new(
    "/path/to/source/image.png",
    "tenant-abc",
    "asset-123",
);
 
let result = pipeline.generate(req).await?;
println!("Generated {} thumbnails", result.generated.len());

let req = ThumbnailRequest::new(
    "/path/to/video.mp4",
    "tenant-abc",
    "asset-456",
)
.with_generate_gif_preview(true);
 
let result = pipeline.generate(req).await?;
// result.generated includes: asset-456_64.jpg, asset-456_256.jpg,
// asset-456_512.jpg, and asset-456_gif.gif

let req = ThumbnailRequest::new(
    "/path/to/model.glb",
    "tenant-abc",
    "asset-789",
)
.with_generate_3d_views(true);
 
let result = pipeline.generate(req).await?;
// result.generated includes: asset-789_64.jpg, asset-789_256.jpg,
// asset-789_512.jpg, and asset-789_3d_v{1..4}.jpg

#[derive(Debug, thiserror::Error)]
pub enum Error {
    UnsupportedFormat(String),      // Format not recognized
    Io(io::Error),                  // Filesystem / IO error
    ImageError(String),             // image crate backend error
    SvgError(String),               // SVG backend error
    PdfError(String),               // PDF backend error
    VideoError(String),             // Video backend error
    Model3dError(String),           // 3D model backend error
    CacheError(String),             // Cache layout / write error
    MissingFeature(&'static str),   // Feature flag not enabled in this build
    InvalidInput(String),           // Malformed request
}