@tidyfactor/design 1.5.0

package/scripts/minify_assets.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+Asset Bundler & Minifier Script
+Combines and minifies CSS and JavaScript files relative to the project root.
+"""
+
+import re
+from pathlib import Path
+
+# Project root is the parent directory of this script's directory (i.e. scripts/ -> root)
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+# --- BUNDLE CONFIGURATION (Relative to PROJECT_ROOT) ---
+CSS_BUNDLES = {
+    "assets/css/style.min.css": [
+        "assets/css/style.css"
+    ]
+}
+
+JS_BUNDLES = {
+    "assets/js/bundle.min.js": [
+        "assets/js/gsap/3.12.5/gsap.min.js",
+        "assets/js/gsap/3.12.5/ScrollTrigger.min.js",
+        "assets/js/lenis@1.1.13/dist/lenis.min.js",
+        "assets/js/main.js"
+    ]
+}
+
+
+def get_size_format(b, factor=1024, suffix="B"):
+    for unit in ["", "K", "M", "G"]:
+        if b < factor:
+            return f"{b:.2f}{unit}{suffix}"
+        b /= factor
+    return f"{b:.2f}T{suffix}"
+
+
+def minify_css(css_content):
+    # Remove comments
+    css = re.sub(r'/\*.*?\*/', '', css_content, flags=re.DOTALL)
+    # Remove extra spaces around braces and symbols
+    css = re.sub(r'\s*([\{\}:;,])\s*', r'\1', css)
+    # Replace multiple spaces with a single space
+    css = re.sub(r'\s+', ' ', css)
+    # Remove unnecessary semicolons before closing braces
+    css = re.sub(r';\}', '}', css)
+    return css.strip()
+
+
+def minify_js(js_content):
+    # Save string literals to avoid corrupting comments inside quotes
+    strings = []
+    def save_str(match):
+        strings.append(match.group(0))
+        return f"__STR_PLACEHOLDER_{len(strings)-1}__"
+
+    string_pattern = r'("(?:[^"\\]|\\.)*"|\'(?:[^\'\\]|\\.)*\'|`(?:[^`\\]|\\.)*`)'
+    js = re.sub(string_pattern, save_str, js_content)
+
+    # Remove single-line comments // (protecting http:// style links)
+    js = re.sub(r'(?<!:)\/\/.*$', '', js, flags=re.MULTILINE)
+    # Remove multi-line comments /* ... */
+    js = re.sub(r'/\*.*?\*/', '', js, flags=re.DOTALL)
+    # Remove multiple spaces/newlines around operator boundaries
+    js = re.sub(r'\s*([=\+\-\*\/\:\?\{\}\(\)\[\]\,\;])\s*', r'\1', js)
+    # Replace multiple whitespaces/newlines with single line-break or space
+    js = re.sub(r'\n+', '\n', js)
+    js = re.sub(r'[ \t]+', ' ', js)
+
+    # Restore string literals
+    for i, s in enumerate(strings):
+        js = js.replace(f"__STR_PLACEHOLDER_{i}__", s)
+
+    return js.strip()
+
+
+def build_bundle(dest_path_rel, src_files_rel, file_type):
+    dest_path = PROJECT_ROOT / dest_path_rel
+    print(f"Building bundle -> {dest_path.relative_to(PROJECT_ROOT)}")
+    combined_content = []
+    total_src_size = 0
+
+    for src_file in src_files_rel:
+        src_path = PROJECT_ROOT / src_file
+        if not src_path.exists():
+            print(f"  [ERROR] Source file not found: {src_file}")
+            continue
+
+        size = src_path.stat().st_size
+        total_src_size += size
+        print(f"  + {src_path.name} ({get_size_format(size)})")
+
+        with open(src_path, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        is_already_minified = src_path.name.endswith(".min.js") or src_path.name.endswith(".min.css")
+        
+        if is_already_minified:
+            combined_content.append(content)
+        else:
+            if file_type == "css":
+                minified = minify_css(content)
+            elif file_type == "js":
+                minified = minify_js(content)
+            else:
+                minified = content
+            combined_content.append(minified)
+
+    output_content = "\n".join(combined_content)
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    with open(dest_path, "w", encoding="utf-8") as f:
+        f.write(output_content)
+
+    final_size = dest_path.stat().st_size
+    saved = total_src_size - final_size
+    pct = (saved / total_src_size) * 100 if total_src_size > 0 else 0
+    
+    print(f"  [SUCCESS] Combined Size: {get_size_format(total_src_size)} -> {get_size_format(final_size)} (-{pct:.1f}%)")
+    print(f"  Saved: {get_size_format(saved)}\n")
+
+
+def main():
+    print("="*50)
+    print("Beginning Asset Bundler and Minifier (Scripts Folder)...")
+    print("="*50 + "\n")
+
+    for dest, sources in CSS_BUNDLES.items():
+        build_bundle(dest, sources, "css")
+
+    for dest, sources in JS_BUNDLES.items():
+        build_bundle(dest, sources, "js")
+
+    print("="*50)
+    print("Bundling process completed successfully!")
+    print("="*50)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/optimize_assets.py

@@ -0,0 +1,91 @@
+import argparse
+import os
+import shutil
+import sys
+
+try:
+    from PIL import Image
+except ImportError:
+    print("Required package not installed. Run:  pip install Pillow", file=sys.stderr)
+    sys.exit(1)
+
+def resize_image_max_dim(path, max_dim, output=None):
+    if not os.path.exists(path):
+        print(f"[skip] {path} not found")
+        return
+    try:
+        img = Image.open(path)
+        w, h = img.size
+        if w <= max_dim and h <= max_dim:
+            print(f"[ok]   {path} already within {max_dim}px ({w}x{h})")
+            return
+        if w > h:
+            new_w = max_dim
+            new_h = int(h * (max_dim / w))
+        else:
+            new_h = max_dim
+            new_w = int(w * (max_dim / h))
+        print(f"[resize] {path}  {w}x{h} -> {new_w}x{new_h}")
+        img = img.resize((new_w, new_h), Image.Resampling.LANCZOS)
+        dest = output or path
+        img.save(dest)
+        print(f"[saved] {dest}")
+    except Exception as e:
+        print(f"[error] {path}: {e}")
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Resize images so their largest dimension does not exceed a given pixel limit. "
+                    "Overwrites in place unless --output is specified.",
+    )
+    parser.add_argument(
+        "inputs",
+        nargs="*",
+        help="Image file paths. Each can be followed by a colon and a max-dim value "
+             "(e.g. assets/logo.png:240). The colon suffix is only recognised when the "
+             "trailing segment is purely numeric, so Windows paths like C:\\images\\photo.png "
+             "work without ambiguity. If no colon value is given, --max-dim is used.",
+    )
+    parser.add_argument(
+        "--max-dim",
+        type=int,
+        default=1200,
+        help="Default max dimension in pixels (default: 1200)",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        help="Optional output path (only valid when a single input is given)",
+    )
+    args = parser.parse_args()
+
+    if not args.inputs:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.output and len(args.inputs) > 1:
+        parser.error("--output can only be used with a single input file")
+
+    output_for_single = args.output if len(args.inputs) == 1 else None
+    for spec in args.inputs:
+        # Split spec into path + optional max-dim ONLY when the trailing segment
+        # after the last colon is purely numeric.  This avoids corrupting
+        # Windows absolute paths like  C:\images\photo.png  (which contain a
+        # drive-letter colon that is NOT a dimension modifier).
+        path = spec
+        dim = args.max_dim
+        if ":" in spec:
+            left, right = spec.rsplit(":", 1)
+            if right.isdigit():
+                path, dim = left, int(right)
+
+        dest = output_for_single or path
+        if not output_for_single and os.path.exists(path):
+            backup = path + ".bak"
+            print(f"[warn] overwriting in-place: {path}  (backup -> {backup})")
+            shutil.copy2(path, backup)
+
+        resize_image_max_dim(path, dim, output=dest)
+
+if __name__ == "__main__":
+    main()

package/scripts/optimize_images.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+Image Optimization Utility
+Optimizes JPEGs, PNGs, and WebP images in a directory using Python's Pillow library.
+Resolves paths relative to the project root.
+"""
+
+import os
+import sys
+import argparse
+from pathlib import Path
+
+# Project root is parent of scripts/
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+try:
+    from PIL import Image
+except ImportError:
+    print("Error: The 'Pillow' library is required to run this script.")
+    print("Install it by running: pip install Pillow")
+    sys.exit(1)
+
+
+def get_size_format(b, factor=1024, suffix="B"):
+    for unit in ["", "K", "M", "G", "T", "P"]:
+        if b < factor:
+            return f"{b:.2f}{unit}{suffix}"
+        b /= factor
+    return f"{b:.2f}Y{suffix}"
+
+
+def optimize_image(file_path, quality=85, convert_to_webp=False, replace=True, backup=True):
+    path = Path(file_path)
+    ext = path.suffix.lower()
+
+    if ext not in [".jpg", ".jpeg", ".png", ".webp"]:
+        return None
+
+    orig_size = path.stat().st_size
+    
+    try:
+        # Determine destination path
+        if convert_to_webp:
+            dest_path = path.with_suffix(".webp")
+        else:
+            dest_path = path
+
+        # Backup handling: Rename the original file BEFORE opening it
+        # This prevents WinError 32 (file in use) on Windows
+        backup_path = None
+        source_path = path
+        
+        if replace and dest_path == path and backup:
+            bp = path.with_name(f"{path.stem}_backup{ext}")
+            if not bp.exists():
+                os.rename(path, bp)
+                backup_path = bp
+                source_path = bp
+            else:
+                source_path = bp
+        
+        # Now process the image from source_path and write to dest_path
+        with Image.open(source_path) as img:
+            # Handle conversion for JPEG
+            if (not convert_to_webp and ext in [".jpg", ".jpeg"]) or (convert_to_webp and ext in [".jpg", ".jpeg"]):
+                if img.mode != "RGB":
+                    img = img.convert("RGB")
+                    
+            if convert_to_webp:
+                img.save(dest_path, "WEBP", quality=quality, method=6)
+            elif ext in [".jpg", ".jpeg"]:
+                img.save(dest_path, "JPEG", optimize=True, quality=quality, progressive=True)
+            elif ext == ".png":
+                if img.mode != "P" and img.mode in ("RGB", "RGBA"):
+                    try:
+                        quantized = img.quantize(colors=256)
+                        quantized.save(dest_path, "PNG", optimize=True)
+                    except Exception:
+                        img.save(dest_path, "PNG", optimize=True, compress_level=9)
+                else:
+                    img.save(dest_path, "PNG", optimize=True, compress_level=9)
+            elif ext == ".webp":
+                img.save(dest_path, "WEBP", quality=quality, method=6)
+
+        new_size = dest_path.stat().st_size
+        saved_bytes = orig_size - new_size
+        
+        if saved_bytes > 0:
+            saving_pct = (saved_bytes / orig_size) * 100
+            print(f"[OPTIMIZED] {path.name} -> {dest_path.name}")
+            print(f"  Size: {get_size_format(orig_size)} -> {get_size_format(new_size)} (-{saving_pct:.1f}%)")
+            return orig_size, new_size
+        else:
+            # If the file didn't compress further (new size >= original), restore original
+            if backup_path and backup_path.exists():
+                if dest_path.exists():
+                    os.remove(dest_path)
+                os.rename(backup_path, dest_path)
+            print(f"[SKIPPED]   {path.name} (Already optimized)")
+            return orig_size, orig_size
+
+    except Exception as e:
+        print(f"[ERROR]     Could not optimize {path.name}: {e}")
+        # Restore backup in case of half-saved/failed operations
+        if 'backup_path' in locals() and backup_path and backup_path.exists():
+            if path.exists():
+                os.remove(path)
+            os.rename(backup_path, path)
+        return None
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Optimize assets in a folder using Pillow.")
+    parser.add_argument("directory", help="Path to the directory containing images (relative to project root)")
+    parser.add_argument("--quality", type=int, default=85, help="JPEG/WebP quality setting (0-100, default: 85)")
+    parser.add_argument("--webp", action="store_true", help="Convert JPEGs and PNGs to WebP format")
+    parser.add_argument("--no-backup", action="store_true", help="Do not keep backups of replaced images")
+    
+    args = parser.parse_args()
+    
+    target_dir = PROJECT_ROOT / args.directory
+    if not target_dir.exists() or not target_dir.is_dir():
+        print(f"Error: '{target_dir}' is not a valid directory.")
+        sys.exit(1)
+
+    print(f"Scanning '{target_dir.relative_to(PROJECT_ROOT)}' for images...")
+    
+    supported_extensions = {".png", ".jpg", ".jpeg", ".webp"}
+    image_files = []
+    
+    for root, _, files in os.walk(target_dir):
+        for file in files:
+            file_path = Path(root) / file
+            if file_path.suffix.lower() in supported_extensions and "_backup" not in file_path.name:
+                image_files.append(file_path)
+
+    if not image_files:
+        print("No supported images found in the directory.")
+        sys.exit(0)
+
+    print(f"Found {len(image_files)} image files. Beginning optimization...\n")
+    
+    total_original = 0
+    total_optimized = 0
+    optimized_count = 0
+
+    for file_path in image_files:
+        result = optimize_image(
+            file_path, 
+            quality=args.quality, 
+            convert_to_webp=args.webp,
+            replace=True, 
+            backup=not args.no_backup
+        )
+        if result:
+            orig, new = result
+            total_original += orig
+            total_optimized += new
+            optimized_count += 1
+
+    print("\n" + "="*40)
+    print("Optimization Summary:")
+    print("="*40)
+    print(f"Total Images Scanned:   {len(image_files)}")
+    print(f"Total Optimized/Saved: {optimized_count}")
+    if total_original > 0:
+        saved = total_original - total_optimized
+        pct = (saved / total_original) * 100
+        print(f"Total Original Size:   {get_size_format(total_original)}")
+        print(f"Total Optimized Size:  {get_size_format(total_optimized)}")
+        print(f"Total Disk Space Saved: {get_size_format(saved)} (-{pct:.1f}%)")
+    print("="*40)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/prepare_images.py

@@ -0,0 +1,67 @@
+import argparse
+import os
+import sys
+
+try:
+    from PIL import Image
+except ImportError:
+    print("Required package not installed. Run:  pip install Pillow", file=sys.stderr)
+    sys.exit(1)
+
+PNG_EXTS = {".png", ".webp", ".tga", ".bmp", ".tiff"}
+
+def convert_to_jpg(src, dest, quality=87):
+    if not os.path.exists(src):
+        print(f"[skip] {src} not found")
+        return
+    try:
+        img = Image.open(src)
+        rgb_img = img.convert("RGB")
+        os.makedirs(os.path.dirname(dest) or ".", exist_ok=True)
+        rgb_img.save(dest, "JPEG", quality=quality)
+        print(f"[ok]   {src} -> {dest}  (q={quality})")
+    except Exception as e:
+        print(f"[error] {src}: {e}")
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Convert PNG/WEBP images to optimised JPEG. "
+                    "Accepts explicit src:dest pairs or an input/output directory pair.",
+    )
+    parser.add_argument(
+        "pairs",
+        nargs="*",
+        help="src:dest pairs  e.g.  assets/hero.png:assets/hero.jpg",
+    )
+    parser.add_argument(
+        "--input-dir",
+        help="Scan a directory for PNG/WEBP files (alternative to positional pairs)",
+    )
+    parser.add_argument("--output-dir", help="Directory for converted JPEGs (default: same as input)")
+    parser.add_argument("--quality", "-q", type=int, default=87, help="JPEG quality 1-100 (default: 87)")
+    args = parser.parse_args()
+
+    if args.input_dir and args.pairs:
+        parser.error("Use either --input-dir OR positional pairs, not both.")
+
+    if args.input_dir:
+        out_dir = args.output_dir or args.input_dir
+        os.makedirs(out_dir, exist_ok=True)
+        for f in sorted(os.listdir(args.input_dir)):
+            if os.path.splitext(f)[1].lower() in PNG_EXTS:
+                src = os.path.join(args.input_dir, f)
+                dest = os.path.join(out_dir, os.path.splitext(f)[0] + ".jpg")
+                convert_to_jpg(src, dest, args.quality)
+    elif args.pairs:
+        for pair in args.pairs:
+            if ":" not in pair:
+                print(f"[skip] '{pair}' — expected format  src:dest", file=sys.stderr)
+                continue
+            src, dest = pair.split(":", 1)
+            convert_to_jpg(src.strip(), dest.strip(), args.quality)
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+if __name__ == "__main__":
+    main()

package/scripts/remove_backgrounds.py

@@ -0,0 +1,61 @@
+import argparse
+import os
+import sys
+
+try:
+    from rembg import remove
+    from PIL import Image
+except ImportError:
+    print("Required packages not installed. Run:  pip install rembg pillow", file=sys.stderr)
+    sys.exit(1)
+
+from _utils import split_spec
+
+def remove_bg(src, dest):
+    if not os.path.exists(src):
+        print(f"[skip] {src} not found")
+        return
+    try:
+        print(f"[work] {src} -> {dest}")
+        img = Image.open(src)
+        out = remove(img)
+        os.makedirs(os.path.dirname(dest) or ".", exist_ok=True)
+        out.save(dest)
+        print(f"[ok]   {dest}")
+    except Exception as e:
+        print(f"[error] {src}: {e}")
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Remove backgrounds from images using rembg. "
+                    "Accepts src:dest pairs or a single file with --output.",
+    )
+    parser.add_argument(
+        "inputs",
+        nargs="*",
+        help="Image paths. Use  src:dest  syntax for explicit output names, "
+             "or plain paths (output appends '_cut' before the extension).",
+    )
+    parser.add_argument("--output", "-o", help="Output path (valid only with a single input)")
+    args = parser.parse_args()
+
+    if not args.inputs:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.output and len(args.inputs) > 1:
+        parser.error("--output can only be used with a single input file")
+
+    for spec in args.inputs:
+        if ":" in spec:
+            parts = split_spec(spec)
+            src, dest = parts[0], parts[1] if len(parts) > 1 else parts[0]
+        elif args.output:
+            src, dest = spec, args.output
+        else:
+            root, ext = os.path.splitext(spec)
+            src, dest = spec, f"{root}_cut{ext}"
+        remove_bg(src.strip(), dest.strip())
+
+if __name__ == "__main__":
+    main()