Current state
This commit is contained in:
309
.copilot/thumbnails.md
Normal file
309
.copilot/thumbnails.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# Skinbase Thumbnails Generation Rules
|
||||
|
||||
## Project
|
||||
Skinbase.org – Artwork / Wallpapers / Skins CDN
|
||||
|
||||
CDN Base URL (Public):
|
||||
https://files.skinbase.org
|
||||
|
||||
All generated thumbnails must be publicly accessible under this domain.
|
||||
|
||||
---
|
||||
|
||||
## 1. Goals
|
||||
|
||||
- Generate fast-loading, high-quality thumbnails
|
||||
- Optimize for CDN delivery (Cloudflare + Apache)
|
||||
- Preserve visual quality
|
||||
- Keep consistent sizes
|
||||
- Use immutable filenames (hash-based)
|
||||
|
||||
---
|
||||
|
||||
## 2. Supported Input Formats
|
||||
|
||||
Source images may be:
|
||||
|
||||
- JPG / JPEG
|
||||
- PNG
|
||||
- WEBP
|
||||
- TIFF
|
||||
- PSD (flattened first)
|
||||
|
||||
Before thumbnail generation:
|
||||
- Strip EXIF metadata
|
||||
- Convert to RGB
|
||||
- Normalize orientation
|
||||
|
||||
---
|
||||
|
||||
## 3. Output Formats
|
||||
|
||||
Primary output:
|
||||
|
||||
- WEBP (preferred)
|
||||
- AVIF (optional, future use)
|
||||
- JPG (fallback only if WebP fails)
|
||||
|
||||
Default quality:
|
||||
|
||||
| Format | Quality |
|
||||
|--------|---------|
|
||||
| WebP | 82 |
|
||||
| AVIF | 45 |
|
||||
| JPG | 85 |
|
||||
|
||||
---
|
||||
|
||||
## 4. Thumbnail Sizes
|
||||
|
||||
Generate the following sizes for every image:
|
||||
|
||||
| Type | Width | Height | Crop |
|
||||
|------|--------|--------|------|
|
||||
| xs | 150px | auto | no |
|
||||
| sm | 300px | auto | no |
|
||||
| md | 600px | auto | no |
|
||||
| lg | 1200px | auto | no |
|
||||
| sq | 400px | 400px | yes |
|
||||
|
||||
Rules:
|
||||
- Keep aspect ratio for non-square
|
||||
- Never upscale
|
||||
- Use center crop for sq
|
||||
|
||||
---
|
||||
|
||||
## 5. File Naming Convention
|
||||
|
||||
All thumbnails must use hash-based paths.
|
||||
|
||||
Format:
|
||||
|
||||
/lg/ff/2e/ff2e9ba2277b6b8296a0011c618ebf20c8c334a2.webp
|
||||
|
||||
Public URL example:
|
||||
|
||||
https://files.skinbase.org/lg/ff/2e/ff2e9ba2277b6b8296a0011c618ebf20c8c334a2.webp
|
||||
|
||||
Rules:
|
||||
|
||||
- Hash = SHA1(original_file + size + timestamp)
|
||||
- First 2 bytes = dir1
|
||||
- Next 2 bytes = dir2
|
||||
- Next 2 bytes = dir3
|
||||
- Filename = full hash
|
||||
|
||||
---
|
||||
|
||||
## 6. Directory Structure
|
||||
|
||||
Base directory (server):
|
||||
|
||||
/opt/www/virtual/skinbase/files/
|
||||
|
||||
Public mapping:
|
||||
|
||||
/opt/www/virtual/skinbase/files/lg/...
|
||||
→ https://files.skinbase.org/lg/...
|
||||
|
||||
Structure:
|
||||
|
||||
/xs/
|
||||
/sm/
|
||||
/md/
|
||||
/lg/
|
||||
/sq/
|
||||
|
||||
Each contains hashed subfolders.
|
||||
|
||||
Do not store flat files.
|
||||
|
||||
---
|
||||
|
||||
## 7. Image Processing Rules
|
||||
|
||||
When generating thumbnails:
|
||||
|
||||
1. Load source image
|
||||
2. Auto-orient
|
||||
3. Strip metadata
|
||||
4. Resize
|
||||
5. Apply mild sharpening
|
||||
6. Encode WebP
|
||||
7. Save to CDN path
|
||||
|
||||
Sharpening:
|
||||
|
||||
- Radius: 0.5
|
||||
- Amount: 0.3
|
||||
- Threshold: 0
|
||||
|
||||
No heavy filters allowed.
|
||||
|
||||
---
|
||||
|
||||
## 8. Background Handling
|
||||
|
||||
For transparent images:
|
||||
|
||||
- Preserve alpha channel
|
||||
- Do NOT add background
|
||||
- Keep transparent WebP
|
||||
|
||||
For JPG fallback:
|
||||
|
||||
- Background: #000000
|
||||
|
||||
---
|
||||
|
||||
## 9. Performance Constraints
|
||||
|
||||
Target limits:
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Max size (lg) | 400 KB |
|
||||
| Max size (md) | 180 KB |
|
||||
| Max size (sm) | 80 KB |
|
||||
| Max size (xs) | 30 KB |
|
||||
| Max size (sq) | 150 KB |
|
||||
|
||||
If exceeded:
|
||||
- Lower quality by 5
|
||||
- Re-encode
|
||||
|
||||
---
|
||||
|
||||
## 10. Security Rules
|
||||
|
||||
- Never execute embedded scripts
|
||||
- Reject SVG with scripts
|
||||
- Reject malformed images
|
||||
- Validate MIME type
|
||||
- Validate dimensions
|
||||
|
||||
Max source size: 100 MB
|
||||
|
||||
---
|
||||
|
||||
## 11. Cache Compatibility
|
||||
|
||||
All outputs must be CDN-ready.
|
||||
|
||||
Headers expected:
|
||||
|
||||
Cache-Control: public, max-age=31536000, immutable
|
||||
|
||||
Never generate filenames that change.
|
||||
|
||||
---
|
||||
|
||||
## 12. Regeneration Rules
|
||||
|
||||
Thumbnails must be regenerated when:
|
||||
|
||||
- Source image changes
|
||||
- Processing rules change
|
||||
- Quality profile updated
|
||||
|
||||
Old thumbnails must remain (cache-safe).
|
||||
|
||||
---
|
||||
|
||||
## 13. Laravel Integration
|
||||
|
||||
When thumbnail is created:
|
||||
|
||||
1. Save metadata to DB
|
||||
2. Store hash
|
||||
3. Store size
|
||||
4. Store extension
|
||||
5. Store public URL
|
||||
|
||||
Public URL format:
|
||||
|
||||
https://files.skinbase.org/{size}/{dir1}/{dir2}/{hash}.webp
|
||||
|
||||
Where:
|
||||
|
||||
{size} ∈ { xs, sm, md, lg, sq }
|
||||
|
||||
Model fields:
|
||||
|
||||
- thumb_hash
|
||||
- thumb_ext
|
||||
- thumb_size
|
||||
- thumb_width
|
||||
- thumb_height
|
||||
- thumb_url
|
||||
|
||||
---
|
||||
|
||||
## 14. Logging
|
||||
|
||||
Every generation must log:
|
||||
|
||||
- Source path
|
||||
- Output path
|
||||
- Public URL
|
||||
- Size
|
||||
- Time
|
||||
- Result
|
||||
|
||||
Format: JSON
|
||||
|
||||
Example:
|
||||
|
||||
{
|
||||
"source": "upload/a.jpg",
|
||||
"target": "lg/ff/2e/...",
|
||||
"url": "https://files.skinbase.org/lg/ff/2e/...",
|
||||
"size": "lg",
|
||||
"time_ms": 120,
|
||||
"status": "ok"
|
||||
}
|
||||
|
||||
---
|
||||
|
||||
## 15. Error Handling
|
||||
|
||||
If generation fails:
|
||||
|
||||
- Log error
|
||||
- Mark record as failed
|
||||
- Do not retry more than 3x
|
||||
- Alert admin
|
||||
|
||||
---
|
||||
|
||||
## 16. Forbidden Actions
|
||||
|
||||
AI agents must NOT:
|
||||
|
||||
- Overwrite existing thumbnails
|
||||
- Change naming rules
|
||||
- Change directory layout
|
||||
- Serve via PHP
|
||||
- Store in public uploads
|
||||
- Generate relative URLs
|
||||
|
||||
All URLs must be absolute and use https://files.skinbase.org
|
||||
|
||||
---
|
||||
|
||||
## 17. Future Extensions
|
||||
|
||||
Planned:
|
||||
|
||||
- AVIF support
|
||||
- DPR variants (2x, 3x)
|
||||
- Smart cropping
|
||||
- Face detection
|
||||
- AI upscaling (optional)
|
||||
|
||||
Do not implement without approval.
|
||||
|
||||
---
|
||||
|
||||
## End of Rules
|
||||
Reference in New Issue
Block a user