Thumbnail API

pub use sb_thumbnails::{
    Pipeline, ThumbnailRequest, ThumbnailResult,
    CacheLayout, Error, Result,
    MAX_DIM, STANDARD_SIZES, THUMBNAIL_CONTENT_TYPE, THUMBNAIL_EXTENSION,
    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,     // Refused by the Cloudflare isolate; see below
    pub generate_3d_views: bool,        // Refused by the Cloudflare isolate; see below
}

{
  "status": "failed",
  "code": "unsupported_feature",
  "features": ["generate_gif_preview", "generate_3d_views"],
  "reason": "generate_gif_preview and generate_3d_views are not implemented by the isolate codec",
  "permanent": true,
  "exhausted": false,
  "attempt": 0
}

{
  "codecs": ["raster", "svg"],
  "unsupported_features": ["generate_gif_preview", "generate_3d_views"],
  "unsupported_feature_code": "unsupported_feature"
}

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}/
  thumbnails/{asset_id}_64.webp
  thumbnails/{asset_id}_256.webp
  thumbnails/{asset_id}_512.webp
  thumbnails/{asset_id}_gif.gif       // animated preview (video/gif)
  thumbnails/{asset_id}_3d_v1.webp    // front
  thumbnails/{asset_id}_3d_v2.webp    // side
  thumbnails/{asset_id}_3d_v3.webp    // top
  thumbnails/{asset_id}_3d_v4.webp    // 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 mut req = ThumbnailRequest::new(
    "/path/to/video.mp4",
    "tenant-abc",
    "asset-456",
);
req.generate_gif_preview = true;
// Isolate: permanent failure, features: ["generate_gif_preview"].
// Native video backend: Error::VideoError (ffmpeg stub). No asset-456_gif.gif.
 
let mut model = ThumbnailRequest::new(
    "/path/to/model.glb",
    "tenant-abc",
    "asset-789",
);
model.generate_3d_views = true;
// Isolate: permanent failure, features: ["generate_3d_views"].
// Native model3d backend: Error::Model3dError. No asset-789_3d_v{1..4} keys.

#[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
}