diff --git a/frontend/src/lib/stores/github.svelte.ts b/frontend/src/lib/stores/github.svelte.ts
new file mode 100644
index 00000000..ab683048
--- /dev/null
+++ b/frontend/src/lib/stores/github.svelte.ts
@@ -0,0 +1,104 @@
+import type {githubsource} from '../../../wailsjs/go/models';
+
+let url = $state('');
+let results = $state
([]);
+let isLoading = $state(false);
+let error = $state('');
+let requestSequence = 0;
+
+export function getURL(): string {
+ return url;
+}
+export function getResults(): githubsource.ImageInfo[] {
+ return results;
+}
+export function getIsLoading(): boolean {
+ return isLoading;
+}
+export function getError(): string {
+ return error;
+}
+
+export function setURL(value: string): void {
+ requestSequence++;
+ url = value.trim();
+ results = [];
+ error = '';
+ isLoading = false;
+}
+
+function navigationURL(): URL | null {
+ try {
+ const parsed = new URL(url);
+ const parts = parsed.pathname.split('/').filter(Boolean);
+ if (parsed.hostname === 'raw.githubusercontent.com') {
+ const index = parts[2] === 'refs' && parts[3] === 'heads' ? 4 : 2;
+ parsed.hostname = 'github.com';
+ parsed.pathname =
+ '/' +
+ [...parts.slice(0, 2), 'tree', ...parts.slice(index)].join('/');
+ }
+ if (parsed.hostname !== 'github.com') return null;
+ parsed.search = '';
+ parsed.hash = '';
+ return parsed;
+ } catch {
+ return null;
+ }
+}
+
+export function getCanGoUp(): boolean {
+ const parsed = navigationURL();
+ if (!parsed) return false;
+ const parts = parsed.pathname.split('/').filter(Boolean);
+ return parts.length > (parts[2] === 'tree' || parts[2] === 'blob' ? 4 : 2);
+}
+
+export function navigateToDir(name: string): void {
+ const parsed = navigationURL();
+ if (!parsed) return;
+ parsed.pathname =
+ parsed.pathname.replace(/\/+$/, '') + '/' + encodeURIComponent(name);
+ setURL(parsed.toString());
+ void fetchImages();
+}
+
+export function goUp(): void {
+ if (!getCanGoUp()) return;
+ const parsed = navigationURL()!;
+ const parts = parsed.pathname.split('/').filter(Boolean);
+ parts.pop();
+ parsed.pathname = '/' + parts.join('/');
+ setURL(parsed.toString());
+ void fetchImages();
+}
+
+export async function fetchImages(): Promise {
+ const source = url.trim();
+ const sequence = ++requestSequence;
+ if (!source) {
+ isLoading = false;
+ results = [];
+ return;
+ }
+ isLoading = true;
+ error = '';
+ results = [];
+ try {
+ const {ListGitHubImages} = await import('../../../wailsjs/go/main/App');
+ if (sequence !== requestSequence) return;
+ const result = await ListGitHubImages(source);
+ if (sequence === requestSequence)
+ results = Array.isArray(result?.items) ? result.items : [];
+ } catch (failure: unknown) {
+ if (sequence === requestSequence)
+ error =
+ typeof failure === 'string'
+ ? failure
+ : failure instanceof Error
+ ? failure.message
+ : 'Could not fetch repository images';
+ } finally {
+ if (sequence === requestSequence) isLoading = false;
+ }
+}
diff --git a/frontend/src/lib/stores/ui.svelte.ts b/frontend/src/lib/stores/ui.svelte.ts
index 1812574a..fd1cd0aa 100644
--- a/frontend/src/lib/stores/ui.svelte.ts
+++ b/frontend/src/lib/stores/ui.svelte.ts
@@ -3,6 +3,7 @@ import {STORAGE_KEYS} from '$lib/constants/storage';
export type Tab =
| 'editor'
| 'wallhaven'
+ | 'github'
| 'local'
| 'favorites'
| 'blueprints'
diff --git a/frontend/tests/apply-save-dialog.test.ts b/frontend/tests/apply-save-dialog.test.ts
index 4568b1ca..e1e04312 100644
--- a/frontend/tests/apply-save-dialog.test.ts
+++ b/frontend/tests/apply-save-dialog.test.ts
@@ -23,13 +23,11 @@ beforeEach(() => {
theme.setIsApplying(false);
theme.setWallpaperPath('/original.png');
vi.mocked(ThemeFolderExists).mockReset().mockResolvedValue(false);
- vi.mocked(SaveAndApplyTheme)
- .mockReset()
- .mockResolvedValue({
- success: true,
- isOmarchy: true,
- themePath: '/theme',
- });
+ vi.mocked(SaveAndApplyTheme).mockReset().mockResolvedValue({
+ success: true,
+ isOmarchy: true,
+ themePath: '/theme',
+ });
});
function enter() {
diff --git a/frontend/tests/github-source.test.ts b/frontend/tests/github-source.test.ts
new file mode 100644
index 00000000..cb92fd9d
--- /dev/null
+++ b/frontend/tests/github-source.test.ts
@@ -0,0 +1,180 @@
+import {beforeEach, expect, test, vi} from 'vitest';
+import GitHubCard from '../src/lib/components/github/GitHubCard.svelte';
+import GitHubBrowser from '../src/lib/components/github/GitHubBrowser.svelte';
+import HeaderBar from '../src/lib/components/layout/HeaderBar.svelte';
+import * as source from '../src/lib/stores/github.svelte';
+import * as favorites from '../src/lib/stores/favorites.svelte';
+import * as theme from '../src/lib/stores/theme.svelte';
+import {getActiveTab, setActiveTab} from '../src/lib/stores/ui.svelte';
+import {
+ ListGitHubImages,
+ GetGitHubThumbnail,
+ DownloadWallpaper,
+ ToggleFavorite,
+ GetFavorites,
+} from '../wailsjs/go/main/App';
+import {deferred, render, settle} from './setup';
+
+vi.mock('../src/lib/components/layout/ReleaseIndicator.svelte', async () => ({
+ default: (await import('./Empty.svelte')).default,
+}));
+vi.mock('../src/lib/stores/omarchy.svelte', () => ({
+ getOmarchyAvailable: () => true,
+ getOmarchyCapabilities: () => ({overrideApps: ['kitty']}),
+ initOmarchyCapabilities: vi.fn().mockResolvedValue(undefined),
+}));
+vi.mock('../wailsjs/go/main/App', () => ({
+ ListGitHubImages: vi.fn(),
+ GetGitHubThumbnail: vi.fn(),
+ DownloadWallpaper: vi.fn(),
+ ToggleFavorite: vi.fn(),
+ GetFavorites: vi.fn().mockResolvedValue([]),
+ GetWallpaperTags: vi.fn().mockResolvedValue({labels: [], assignments: {}}),
+ IsMacOS: vi.fn().mockResolvedValue(false),
+}));
+
+const image = {
+ name: 'wall.png',
+ path: 'wall.png',
+ type: 'file',
+ size: 1024,
+ url: 'https://raw.githubusercontent.com/owner/repo/main/wall.png',
+};
+const thumbnail = {
+ dataURL: 'data:image/png;base64,AA==',
+ width: 20,
+ height: 10,
+};
+
+beforeEach(async () => {
+ await settle();
+ source.setURL('');
+ theme.reset();
+ setActiveTab('github');
+ vi.mocked(ListGitHubImages).mockReset().mockResolvedValue({items: []});
+ vi.mocked(GetGitHubThumbnail).mockReset().mockResolvedValue(thumbnail);
+ vi.mocked(DownloadWallpaper)
+ .mockReset()
+ .mockResolvedValue('/downloaded.png');
+ vi.mocked(ToggleFavorite).mockReset().mockResolvedValue(true);
+ vi.mocked(GetFavorites).mockReset().mockResolvedValue([]);
+ await favorites.refreshFavorites();
+ vi.stubGlobal(
+ 'IntersectionObserver',
+ class {
+ constructor(
+ private callback: (entries: {isIntersecting: boolean}[]) => void
+ ) {}
+ observe() {
+ this.callback([{isIntersecting: true}]);
+ }
+ disconnect() {}
+ }
+ );
+});
+
+test('the newest repository response wins', async () => {
+ const old = deferred<{items: (typeof image)[]}>();
+ const next = deferred<{items: (typeof image)[]}>();
+ vi.mocked(ListGitHubImages)
+ .mockReturnValueOnce(old.promise)
+ .mockReturnValueOnce(next.promise);
+ source.setURL('https://github.com/owner/old');
+ const first = source.fetchImages();
+ await settle();
+ source.setURL('https://github.com/owner/new');
+ const second = source.fetchImages();
+ await settle();
+ next.resolve({items: [{...image, name: 'new.png'}]});
+ await second;
+ old.resolve({items: [image]});
+ await first;
+ expect(source.getURL()).toBe('https://github.com/owner/new');
+ expect(source.getResults()[0].name).toBe('new.png');
+});
+
+test('directory navigation escapes names and stops at the repository root', async () => {
+ source.setURL('https://github.com/owner/repo/tree/main?tab=readme#readme');
+ expect(source.getCanGoUp()).toBe(false);
+ source.navigateToDir('a #b');
+ await settle();
+ expect(source.getURL()).toBe(
+ 'https://github.com/owner/repo/tree/main/a%20%23b'
+ );
+ source.goUp();
+ await settle();
+ expect(source.getCanGoUp()).toBe(false);
+ expect(source.getURL()).toBe('https://github.com/owner/repo/tree/main');
+});
+
+test('failed thumbnails expose a retry', async () => {
+ vi.mocked(GetGitHubThumbnail).mockRejectedValueOnce(new Error('offline'));
+ const {target} = render(GitHubCard, {image, onpreview: vi.fn()});
+ await settle();
+ const retry = [...target.querySelectorAll('button')].find(
+ button => button.textContent === 'Retry preview'
+ )!;
+ expect(retry).not.toBeUndefined();
+ retry.click();
+ await settle();
+ expect(GetGitHubThumbnail).toHaveBeenCalledTimes(2);
+ expect(target.querySelector('img')?.getAttribute('src')).toBe(
+ thumbnail.dataURL
+ );
+});
+
+test('repository hearts use the shared favorites store', async () => {
+ const {target} = render(GitHubCard, {image, onpreview: vi.fn()});
+ await settle();
+ target
+ .querySelector('[aria-label="Add to favorites"]')!
+ .click();
+ await settle();
+ expect(ToggleFavorite).toHaveBeenCalledExactlyOnceWith(
+ image.url,
+ 'github',
+ {name: image.name}
+ );
+ expect(favorites.isFavorite(image.url)).toBe(true);
+});
+
+test('a late download does not replace a newer wallpaper choice', async () => {
+ const pending = deferred();
+ vi.mocked(DownloadWallpaper).mockReturnValue(pending.promise);
+ const {target} = render(GitHubCard, {image, onpreview: vi.fn()});
+ await settle();
+ target
+ .querySelector(
+ 'button[title="Set as wallpaper and open in editor"]'
+ )!
+ .click();
+ await settle();
+ theme.setWallpaperPath('/newer.png');
+ pending.resolve('/old.png');
+ await settle();
+ expect(theme.getWallpaperPath()).toBe('/newer.png');
+ expect(getActiveTab()).toBe('github');
+});
+
+test('GitHub navigation remains a standard focusable button', async () => {
+ const {target} = render(HeaderBar, {});
+ await settle();
+ setActiveTab('editor');
+ const button = [...target.querySelectorAll('nav button')].find(
+ button => button.textContent?.trim() === 'GitHub'
+ ) as HTMLButtonElement;
+ button.focus();
+ button.click();
+ await settle();
+ expect(document.activeElement).toBe(button);
+ expect(getActiveTab()).toBe('github');
+ expect(button.getAttribute('aria-current')).toBe('page');
+});
+
+test('malformed saved repository preferences do not break the browser', () => {
+ localStorage.setItem('aether-saved-repos', '{"invalid":true}');
+ const {target} = render(GitHubBrowser, {});
+ expect(
+ target.querySelector('[aria-label="GitHub repository URL"]')
+ ).not.toBeNull();
+});
diff --git a/frontend/wailsjs/go/main/App.d.ts b/frontend/wailsjs/go/main/App.d.ts
index 9d361a5a..99b7cccc 100755
--- a/frontend/wailsjs/go/main/App.d.ts
+++ b/frontend/wailsjs/go/main/App.d.ts
@@ -4,6 +4,7 @@ import {color} from '../models';
import {theme} from '../models';
import {main} from '../models';
import {favorites} from '../models';
+import {githubsource} from '../models';
import {icontheme} from '../models';
import {omarchy} from '../models';
import {ipc} from '../models';
@@ -81,6 +82,10 @@ export function GetFavorites(): Promise>;
export function GetFocusTab(): Promise;
+export function GetGitHubThumbnail(
+ arg1: string
+): Promise;
+
export function GetIconThemePreview(
arg1: string
): Promise;
@@ -125,6 +130,10 @@ export function IsPreviewCached(arg1: string): Promise;
export function ListBlueprints(): Promise>>;
+export function ListGitHubImages(
+ arg1: string
+): Promise;
+
export function ListInstalledIconThemes(): Promise<
Array
>;
diff --git a/frontend/wailsjs/go/main/App.js b/frontend/wailsjs/go/main/App.js
index db775357..350b3fd3 100755
--- a/frontend/wailsjs/go/main/App.js
+++ b/frontend/wailsjs/go/main/App.js
@@ -110,6 +110,10 @@ export function GetFocusTab() {
return window['go']['main']['App']['GetFocusTab']();
}
+export function GetGitHubThumbnail(arg1) {
+ return window['go']['main']['App']['GetGitHubThumbnail'](arg1);
+}
+
export function GetIconThemePreview(arg1) {
return window['go']['main']['App']['GetIconThemePreview'](arg1);
}
@@ -194,6 +198,10 @@ export function ListBlueprints() {
return window['go']['main']['App']['ListBlueprints']();
}
+export function ListGitHubImages(arg1) {
+ return window['go']['main']['App']['ListGitHubImages'](arg1);
+}
+
export function ListInstalledIconThemes() {
return window['go']['main']['App']['ListInstalledIconThemes']();
}
diff --git a/frontend/wailsjs/go/models.ts b/frontend/wailsjs/go/models.ts
index d408d597..5e3f7fc5 100755
--- a/frontend/wailsjs/go/models.ts
+++ b/frontend/wailsjs/go/models.ts
@@ -54,6 +54,77 @@ export namespace favorites {
}
}
+export namespace githubsource {
+ export class ImageInfo {
+ name: string;
+ url: string;
+ size: number;
+ type: string;
+ path: string;
+
+ static createFrom(source: any = {}) {
+ return new ImageInfo(source);
+ }
+
+ constructor(source: any = {}) {
+ if ('string' === typeof source) source = JSON.parse(source);
+ this.name = source['name'];
+ this.url = source['url'];
+ this.size = source['size'];
+ this.type = source['type'];
+ this.path = source['path'];
+ }
+ }
+ export class ListContentsResult {
+ items: ImageInfo[];
+
+ static createFrom(source: any = {}) {
+ return new ListContentsResult(source);
+ }
+
+ constructor(source: any = {}) {
+ if ('string' === typeof source) source = JSON.parse(source);
+ this.items = this.convertValues(source['items'], ImageInfo);
+ }
+
+ convertValues(a: any, classs: any, asMap: boolean = false): any {
+ if (!a) {
+ return a;
+ }
+ if (a.slice && a.map) {
+ return (a as any[]).map(elem =>
+ this.convertValues(elem, classs)
+ );
+ } else if ('object' === typeof a) {
+ if (asMap) {
+ for (const key of Object.keys(a)) {
+ a[key] = new classs(a[key]);
+ }
+ return a;
+ }
+ return new classs(a);
+ }
+ return a;
+ }
+ }
+ export class ThumbnailResult {
+ dataURL: string;
+ width: number;
+ height: number;
+
+ static createFrom(source: any = {}) {
+ return new ThumbnailResult(source);
+ }
+
+ constructor(source: any = {}) {
+ if ('string' === typeof source) source = JSON.parse(source);
+ this.dataURL = source['dataURL'];
+ this.width = source['width'];
+ this.height = source['height'];
+ }
+ }
+}
+
export namespace icontheme {
export class PreviewSample {
kind: string;
diff --git a/internal/favorites/service.go b/internal/favorites/service.go
index 744928a4..882824d1 100644
--- a/internal/favorites/service.go
+++ b/internal/favorites/service.go
@@ -99,7 +99,10 @@ func (s *Service) GetAll() []Favorite {
fav := Favorite{Path: path, Data: make(map[string]interface{})}
- if _, ok := obj["id"]; ok {
+ if obj["type"] == "github" {
+ fav.Type = "github"
+ fav.Data["name"] = obj["name"]
+ } else if _, ok := obj["id"]; ok {
// Wallhaven format
fav.Type = "wallhaven"
fav.Data["id"] = obj["id"]
@@ -223,6 +226,9 @@ func (s *Service) buildEntry(path, favType string, data map[string]interface{})
e.Name = filepath.Base(path)
}
return e
+ case "github":
+ name, _ := data["name"].(string)
+ return map[string]string{"path": path, "type": "github", "name": name}
default:
return map[string]string{"path": path}
}
diff --git a/internal/favorites/service_test.go b/internal/favorites/service_test.go
new file mode 100644
index 00000000..006a9712
--- /dev/null
+++ b/internal/favorites/service_test.go
@@ -0,0 +1,16 @@
+package favorites
+
+import "testing"
+
+func TestGitHubFavoritePreservesNameAndTypeAcrossReload(t *testing.T) {
+ t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+ service := NewService()
+ path := "https://raw.githubusercontent.com/owner/repo/main/wall.png"
+ if !service.Toggle(path, "github", map[string]interface{}{"name": "wall.png"}) {
+ t.Fatal("favorite is not added")
+ }
+ loaded := NewService().GetAll()
+ if len(loaded) != 1 || loaded[0].Path != path || loaded[0].Type != "github" || loaded[0].Data["name"] != "wall.png" {
+ t.Fatalf("favorite = %+v", loaded)
+ }
+}
diff --git a/internal/githubsource/cache.go b/internal/githubsource/cache.go
new file mode 100644
index 00000000..a13f2ff7
--- /dev/null
+++ b/internal/githubsource/cache.go
@@ -0,0 +1,82 @@
+package githubsource
+
+import (
+ "sync"
+ "time"
+)
+
+type cacheEntry struct {
+ data *ListContentsResult
+ expiresAt time.Time
+}
+
+type ttlCache struct {
+ mu sync.RWMutex
+ items map[string]*cacheEntry
+ order []string
+ ttl time.Duration
+ max int
+}
+
+func newTTLCache(ttl time.Duration, max int) *ttlCache {
+ return &ttlCache{
+ items: make(map[string]*cacheEntry),
+ order: make([]string, 0, max),
+ ttl: ttl,
+ max: max,
+ }
+}
+
+func (c *ttlCache) get(key string) (*ListContentsResult, bool) {
+ c.mu.RLock()
+ entry, ok := c.items[key]
+ c.mu.RUnlock()
+ if !ok {
+ return nil, false
+ }
+ if time.Now().After(entry.expiresAt) {
+ c.mu.Lock()
+ if c.items[key] == entry {
+ delete(c.items, key)
+ c.removeOrder(key)
+ }
+ c.mu.Unlock()
+ return nil, false
+ }
+ return entry.data, true
+}
+
+func (c *ttlCache) set(key string, data *ListContentsResult) {
+ c.mu.Lock()
+ defer c.mu.Unlock()
+
+ if _, exists := c.items[key]; !exists {
+ if len(c.items) >= c.max {
+ oldest := c.order[0]
+ delete(c.items, oldest)
+ c.order = c.order[1:]
+ }
+ c.order = append(c.order, key)
+ }
+
+ c.items[key] = &cacheEntry{
+ data: data,
+ expiresAt: time.Now().Add(c.ttl),
+ }
+}
+
+func (c *ttlCache) removeOrder(key string) {
+ for i, k := range c.order {
+ if k == key {
+ c.order = append(c.order[:i], c.order[i+1:]...)
+ return
+ }
+ }
+}
+
+func (c *ttlCache) clear() {
+ c.mu.Lock()
+ defer c.mu.Unlock()
+ c.items = make(map[string]*cacheEntry)
+ c.order = make([]string, 0, c.max)
+}
diff --git a/internal/githubsource/provider.go b/internal/githubsource/provider.go
new file mode 100644
index 00000000..0312ae75
--- /dev/null
+++ b/internal/githubsource/provider.go
@@ -0,0 +1,218 @@
+package githubsource
+
+import (
+ "encoding/base64"
+ "encoding/json"
+ "fmt"
+ "image"
+ "io"
+ "net/http"
+ "net/url"
+ "os"
+ "regexp"
+ "strings"
+ "time"
+
+ "aether/internal/wallpaper"
+)
+
+const githubAPIBase = "https://api.github.com"
+const maxAPIBytes = 4 << 20
+
+var repositoryPart = regexp.MustCompile(`^[A-Za-z0-9_.-]{1,100}$`)
+var thumbnailSlots = make(chan struct{}, 4)
+
+type parsedGitHubURL struct {
+ Owner string
+ Repo string
+ Branch string
+ Path string
+}
+
+// Client shares a bounded metadata cache across repository requests.
+type Client struct {
+ http *http.Client
+ cache *ttlCache
+}
+
+func NewClient() *Client {
+ client := wallpaper.NewPublicHTTPClient()
+ client.Timeout = 30 * time.Second
+ return &Client{http: client, cache: newTTLCache(5*time.Minute, 32)}
+}
+
+func (c *Client) ClearCache() { c.cache.clear() }
+
+// ListImages lists one public repository directory or image.
+func (c *Client) ListImages(rawURL string) (*ListContentsResult, error) {
+ location, err := parseURL(rawURL)
+ if err != nil {
+ return nil, err
+ }
+ if cached, ok := c.cache.get(rawURL); ok {
+ return cached, nil
+ }
+ contents, err := c.listContents(location.Owner, location.Repo, location.Path, location.Branch)
+ if err != nil {
+ return nil, err
+ }
+ items := make([]ImageInfo, 0, len(contents))
+ for _, entry := range contents {
+ if entry.Type == "dir" {
+ items = append(items, ImageInfo{Name: entry.Name, Path: entry.Path, Type: "dir"})
+ } else if entry.Type == "file" && isImageFile(entry.Name) && wallpaper.ValidateRemoteURL(entry.DownloadURL) == nil {
+ items = append(items, ImageInfo{Name: entry.Name, URL: entry.DownloadURL, Size: entry.Size, Type: "file", Path: entry.Path})
+ }
+ }
+ result := &ListContentsResult{Items: items}
+ c.cache.set(rawURL, result)
+ return result, nil
+}
+
+func (c *Client) listContents(owner, repo, filePath, branch string) ([]githubContent, error) {
+ endpoint, _ := url.Parse(githubAPIBase)
+ endpoint.Path = "/repos/" + owner + "/" + repo + "/contents/" + filePath
+ query := endpoint.Query()
+ if branch != "" {
+ query.Set("ref", branch)
+ }
+ endpoint.RawQuery = query.Encode()
+ req, err := http.NewRequest(http.MethodGet, endpoint.String(), nil)
+ if err != nil {
+ return nil, err
+ }
+ req.Header.Set("Accept", "application/vnd.github+json")
+ req.Header.Set("User-Agent", "Aether")
+ response, err := c.http.Do(req)
+ if err != nil {
+ return nil, fmt.Errorf("GitHub request: %w", err)
+ }
+ defer response.Body.Close()
+ if response.StatusCode == http.StatusForbidden || response.StatusCode == http.StatusTooManyRequests {
+ return nil, fmt.Errorf("GitHub access or rate limit reached. Try again later")
+ }
+ if response.StatusCode == http.StatusNotFound {
+ return nil, fmt.Errorf("public repository, branch, or path not found")
+ }
+ if response.StatusCode != http.StatusOK {
+ return nil, fmt.Errorf("GitHub returned HTTP %d", response.StatusCode)
+ }
+ if response.ContentLength > maxAPIBytes {
+ return nil, fmt.Errorf("GitHub response exceeds the size limit")
+ }
+ data, err := io.ReadAll(io.LimitReader(response.Body, maxAPIBytes+1))
+ if err != nil {
+ return nil, err
+ }
+ if len(data) > maxAPIBytes {
+ return nil, fmt.Errorf("GitHub response exceeds the size limit")
+ }
+ var entries []githubContent
+ if err := json.Unmarshal(data, &entries); err == nil {
+ return entries, nil
+ }
+ var entry githubContent
+ if err := json.Unmarshal(data, &entry); err != nil {
+ return nil, fmt.Errorf("invalid GitHub response: %w", err)
+ }
+ return []githubContent{entry}, nil
+}
+
+func isImageFile(name string) bool { return wallpaper.IsImageFile(name) }
+
+func parseURL(rawURL string) (*parsedGitHubURL, error) {
+ if err := wallpaper.ValidateRemoteURL(rawURL); err != nil {
+ return nil, err
+ }
+ u, err := url.Parse(rawURL)
+ if err != nil {
+ return nil, err
+ }
+ host := strings.ToLower(u.Hostname())
+ if strings.HasSuffix(host, ".github.io") {
+ return nil, fmt.Errorf("use the GitHub repository URL instead of its Pages URL")
+ }
+ if host != "github.com" && host != "raw.githubusercontent.com" {
+ return nil, fmt.Errorf("enter a github.com repository or raw.githubusercontent.com image URL")
+ }
+ if u.Port() != "" && u.Port() != "443" {
+ return nil, fmt.Errorf("GitHub URLs must use the standard HTTPS port")
+ }
+ segments := splitPath(u.EscapedPath())
+ for i, segment := range segments {
+ decoded, err := url.PathUnescape(segment)
+ if err != nil || decoded == "." || decoded == ".." {
+ return nil, fmt.Errorf("invalid GitHub path")
+ }
+ segments[i] = decoded
+ }
+ if len(segments) < 2 {
+ return nil, fmt.Errorf("GitHub URL requires an owner and repository")
+ }
+ result := &parsedGitHubURL{Owner: segments[0], Repo: strings.TrimSuffix(segments[1], ".git")}
+ if !repositoryPart.MatchString(result.Owner) || !repositoryPart.MatchString(result.Repo) || result.Repo == "." || result.Repo == ".." {
+ return nil, fmt.Errorf("invalid GitHub owner or repository")
+ }
+ if host == "raw.githubusercontent.com" {
+ if len(segments) < 4 {
+ return nil, fmt.Errorf("raw image URL requires a branch and file path")
+ }
+ start := 2
+ if len(segments) > 5 && segments[2] == "refs" && segments[3] == "heads" {
+ start = 4
+ }
+ result.Branch = segments[start]
+ result.Path = strings.Join(segments[start+1:], "/")
+ } else if len(segments) >= 3 && (segments[2] == "tree" || segments[2] == "blob") {
+ if len(segments) < 4 {
+ return nil, fmt.Errorf("GitHub URL requires a branch after tree or blob")
+ }
+ result.Branch = segments[3]
+ result.Path = strings.Join(segments[4:], "/")
+ } else {
+ result.Path = strings.Join(segments[2:], "/")
+ }
+ return result, nil
+}
+
+func splitPath(value string) []string {
+ return strings.FieldsFunc(value, func(r rune) bool { return r == '/' })
+}
+
+// DownloadThumbnail uses the shared public downloader and bounded image decoder.
+func DownloadThumbnail(rawURL string) (*ThumbnailResult, error) {
+ return downloadThumbnail(rawURL, wallpaper.DownloadToCache)
+}
+
+func downloadThumbnail(rawURL string, download func(string, int64) (string, error)) (*ThumbnailResult, error) {
+ if err := wallpaper.ValidateRemoteURL(rawURL); err != nil {
+ return nil, err
+ }
+ thumbnailSlots <- struct{}{}
+ defer func() { <-thumbnailSlots }()
+ path, err := download(rawURL, wallpaper.MaxImageBytes)
+ if err != nil {
+ return nil, err
+ }
+ if err := wallpaper.ValidateImageFile(path); err != nil {
+ return nil, err
+ }
+ file, err := os.Open(path)
+ if err != nil {
+ return nil, err
+ }
+ config, _, err := image.DecodeConfig(file)
+ _ = file.Close()
+ if err != nil {
+ return nil, err
+ }
+ thumb, err := wallpaper.GetThumbnail(path)
+ if err != nil {
+ return nil, err
+ }
+ data, err := os.ReadFile(thumb)
+ if err != nil {
+ return nil, err
+ }
+ return &ThumbnailResult{DataURL: "data:image/png;base64," + base64.StdEncoding.EncodeToString(data), Width: config.Width, Height: config.Height}, nil
+}
diff --git a/internal/githubsource/provider_test.go b/internal/githubsource/provider_test.go
new file mode 100644
index 00000000..1f6fb3fb
--- /dev/null
+++ b/internal/githubsource/provider_test.go
@@ -0,0 +1,158 @@
+package githubsource
+
+import (
+ "bytes"
+ "encoding/base64"
+ "encoding/binary"
+ "hash/crc32"
+ "image"
+ "image/png"
+ "io"
+ "net/http"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "aether/internal/wallpaper"
+)
+
+func TestParseRepositoryURLs(t *testing.T) {
+ for _, test := range []struct{ url, branch, path string }{
+ {"https://github.com/example-user/wallpapers", "", ""},
+ {"https://github.com/example-user/wallpapers.git", "", ""},
+ {"https://github.com/example-user/wallpapers/tree/main/nature", "main", "nature"},
+ {"https://github.com/example-user/wallpapers/blob/main/one.png", "main", "one.png"},
+ {"https://github.com/example-user/wallpapers/tree/feature%2Fimages/folder%20name", "feature/images", "folder name"},
+ {"https://raw.githubusercontent.com/example-user/wallpapers/main/one.png", "main", "one.png"},
+ {"https://raw.githubusercontent.com/example-user/wallpapers/refs/heads/main/one.png", "main", "one.png"},
+ } {
+ t.Run(test.url, func(t *testing.T) {
+ got, err := parseURL(test.url)
+ if err != nil || got.Owner != "example-user" || got.Repo != "wallpapers" || got.Branch != test.branch || got.Path != test.path {
+ t.Fatalf("parsed URL = %+v, error = %v", got, err)
+ }
+ })
+ }
+}
+
+func TestRejectUnsupportedRepositoryURLs(t *testing.T) {
+ for _, value := range []string{
+ "", "http://github.com/owner/repo", "https://user@github.com/owner/repo",
+ "https://127.0.0.1/repo", "https://gitlab.com/owner/repo", "https://github.com/owner",
+ "https://github.com/owner/repo/tree", "https://github.com/owner/repo/%2e%2e/other",
+ "https://github.com/owner%2frepo/other", "https://github.com:8443/owner/repo",
+ "https://example-user.github.io/wallpapers", "https://raw.githubusercontent.com/owner/repo/main",
+ } {
+ if _, err := parseURL(value); err == nil {
+ t.Errorf("accepted %q", value)
+ }
+ }
+}
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(request *http.Request) (*http.Response, error) { return f(request) }
+
+func TestListImagesUsesEscapedRequestsAndCachesMetadata(t *testing.T) {
+ client := NewClient()
+ calls := 0
+ client.http.Transport = roundTripFunc(func(req *http.Request) (*http.Response, error) {
+ calls++
+ if req.URL.Host != "api.github.com" || req.URL.Query().Get("ref") != "feature/images" || req.URL.Path != "/repos/owner/repo/contents/folder name" {
+ t.Fatalf("request = %s", req.URL)
+ }
+ body := `[{"name":"dir","path":"dir","type":"dir"},{"name":"one.png","path":"one.png","type":"file","download_url":"https://raw.githubusercontent.com/owner/repo/main/one.png"},{"name":"bad.png","type":"file","download_url":"https://127.0.0.1/bad.png"},{"name":"README.md","type":"file"}]`
+ return &http.Response{StatusCode: 200, Body: io.NopCloser(strings.NewReader(body))}, nil
+ })
+ for i := 0; i < 2; i++ {
+ result, err := client.ListImages("https://github.com/owner/repo/tree/feature%2Fimages/folder%20name")
+ if err != nil || len(result.Items) != 2 || result.Items[1].Name != "one.png" {
+ t.Fatalf("result = %+v, error = %v", result, err)
+ }
+ }
+ if calls != 1 {
+ t.Fatalf("metadata cache makes %d requests", calls)
+ }
+}
+
+func TestListImagesBoundsResponsesAndReturnsErrors(t *testing.T) {
+ for _, status := range []int{403, 404, 429, 500, 200} {
+ client := NewClient()
+ client.http.Transport = roundTripFunc(func(req *http.Request) (*http.Response, error) {
+ return &http.Response{StatusCode: status, Body: io.NopCloser(strings.NewReader(strings.Repeat(" ", maxAPIBytes+1)))}, nil
+ })
+ if _, err := client.ListImages("https://github.com/owner/repo"); err == nil {
+ t.Errorf("HTTP %d accepts an error or oversized body", status)
+ }
+ }
+}
+
+func TestThumbnailUsesSharedImageLimits(t *testing.T) {
+ t.Setenv("XDG_CACHE_HOME", t.TempDir())
+ var encoded bytes.Buffer
+ if err := png.Encode(&encoded, image.NewRGBA(image.Rect(0, 0, 20, 10))); err != nil {
+ t.Fatal(err)
+ }
+ path := filepath.Join(t.TempDir(), "image.png")
+ if err := os.WriteFile(path, encoded.Bytes(), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ result, err := downloadThumbnail("https://example.com/image.png", func(url string, limit int64) (string, error) {
+ if limit != wallpaper.MaxImageBytes {
+ t.Fatal("download limit changed")
+ }
+ return path, nil
+ })
+ if err != nil || result.Width != 20 || result.Height != 10 {
+ t.Fatalf("thumbnail = %+v, error = %v", result, err)
+ }
+ data, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(result.DataURL, "data:image/png;base64,"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ config, err := png.DecodeConfig(bytes.NewReader(data))
+ if err != nil || config.Width > 300 || config.Height > 300 {
+ t.Fatalf("thumbnail dimensions = %+v, %v", config, err)
+ }
+ oversized := append([]byte(nil), encoded.Bytes()...)
+ binary.BigEndian.PutUint32(oversized[16:20], 20000)
+ binary.BigEndian.PutUint32(oversized[29:33], crc32.ChecksumIEEE(oversized[12:29]))
+ if err := os.WriteFile(path, oversized, 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := downloadThumbnail("https://example.com/huge.png", func(string, int64) (string, error) { return path, nil }); err == nil {
+ t.Fatal("oversized source header is accepted")
+ }
+}
+
+func TestThumbnailRejectsPrivateDestinationsBeforeDownload(t *testing.T) {
+ for _, value := range []string{"http://example.com/image.png", "https://127.0.0.1/image.png", "https://192.168.1.1/image.png", "https://localhost/image.png"} {
+ _, err := downloadThumbnail(value, func(string, int64) (string, error) { t.Fatal("private destination reaches downloader"); return "", nil })
+ if err == nil {
+ t.Errorf("accepted %s", value)
+ }
+ }
+}
+
+func TestMetadataCacheExpiryAndEviction(t *testing.T) {
+ cache := newTTLCache(time.Minute, 2)
+ for _, key := range []string{"one", "two", "three"} {
+ cache.set(key, &ListContentsResult{})
+ }
+ if _, ok := cache.get("one"); ok {
+ t.Fatal("oldest entry survives eviction")
+ }
+ if _, ok := cache.get("three"); !ok {
+ t.Fatal("new entry is missing")
+ }
+ cache.items["three"].expiresAt = time.Now().Add(-time.Second)
+ if _, ok := cache.get("three"); ok {
+ t.Fatal("expired entry survives")
+ }
+ cache.clear()
+ if _, ok := cache.get("two"); ok {
+ t.Fatal("clear preserves an entry")
+ }
+}
diff --git a/internal/githubsource/types.go b/internal/githubsource/types.go
new file mode 100644
index 00000000..fd551504
--- /dev/null
+++ b/internal/githubsource/types.go
@@ -0,0 +1,32 @@
+package githubsource
+
+// ImageInfo describes a single item (file or directory) from a GitHub repository.
+type ImageInfo struct {
+ Name string `json:"name"`
+ URL string `json:"url"` // raw.githubusercontent.com download URL (empty for dirs)
+ Size int64 `json:"size"`
+ Type string `json:"type"` // "file" or "dir"
+ Path string `json:"path"` // repo-relative path
+}
+
+// ListContentsResult is returned by ListImages, containing both files and dirs.
+type ListContentsResult struct {
+ Items []ImageInfo `json:"items"`
+}
+
+// ThumbnailResult is returned by GetGitHubThumbnail / DownloadThumbnail,
+// containing the thumbnail data URL and the original image dimensions.
+type ThumbnailResult struct {
+ DataURL string `json:"dataURL"`
+ Width int `json:"width"`
+ Height int `json:"height"`
+}
+
+// githubContent is a single item from the GitHub Contents API response.
+type githubContent struct {
+ Name string `json:"name"`
+ Type string `json:"type"` // "file" or "dir"
+ Path string `json:"path"`
+ Size int64 `json:"size"`
+ DownloadURL string `json:"download_url"`
+}
diff --git a/internal/wallhaven/client.go b/internal/wallhaven/client.go
index 422ebbdd..332da27d 100644
--- a/internal/wallhaven/client.go
+++ b/internal/wallhaven/client.go
@@ -2,6 +2,7 @@ package wallhaven
import (
"context"
+ "crypto/sha256"
"encoding/json"
"fmt"
"io"
@@ -250,6 +251,15 @@ func (c *Client) downloadContext(ctx context.Context, rawURL, destDir string, ma
return "", fmt.Errorf("invalid download filename")
}
destPath := filepath.Join(destDir, filename)
+ host := strings.ToLower(u.Hostname())
+ if host != "wallhaven.cc" && !strings.HasSuffix(host, ".wallhaven.cc") {
+ sum := sha256.Sum256([]byte(rawURL))
+ ext := path.Ext(u.Path)
+ if len(ext) > 8 {
+ ext = ""
+ }
+ destPath = filepath.Join(destDir, fmt.Sprintf("%x%s", sum[:8], ext))
+ }
client := *c.http
if maxBytes == wallpaper.MaxImageBytes {
client.Timeout = 5 * time.Minute
diff --git a/internal/wallhaven/client_test.go b/internal/wallhaven/client_test.go
index 2550caac..e76be1ca 100644
--- a/internal/wallhaven/client_test.go
+++ b/internal/wallhaven/client_test.go
@@ -201,7 +201,7 @@ func TestDownloadBoundsAndCache(t *testing.T) {
calls++
return &http.Response{StatusCode: http.StatusOK, Body: body, ContentLength: length}, nil
})
- const rawURL = "https://example.com/image.jpg?token=value#fragment"
+ const rawURL = "https://w.wallhaven.cc/image.jpg?token=value#fragment"
if _, err := tc.call(c, rawURL); err == nil || !strings.Contains(err.Error(), "exceeds") || body.read != 0 || !body.closed {
t.Fatalf("advertised overflow: error %v, read %d, closed %v", err, body.read, body.closed)
}
@@ -226,3 +226,29 @@ func TestDownloadBoundsAndCache(t *testing.T) {
})
}
}
+
+func TestRemoteSourcesWithSameFilenameUseDistinctCacheEntries(t *testing.T) {
+ t.Setenv("HOME", t.TempDir())
+ t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+ t.Setenv("XDG_DATA_HOME", t.TempDir())
+ t.Setenv("XDG_CACHE_HOME", t.TempDir())
+ client := NewClient()
+ client.http.Transport = roundTripFunc(func(req *http.Request) (*http.Response, error) {
+ return &http.Response{StatusCode: 200, Body: io.NopCloser(strings.NewReader(req.URL.Path))}, nil
+ })
+ one, err := client.Download("https://example.com/one/wall.png")
+ if err != nil {
+ t.Fatal(err)
+ }
+ two, err := client.Download("https://example.com/two/wall.png")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if one == two {
+ t.Fatal("different remote sources share a cache path")
+ }
+ data, err := os.ReadFile(two)
+ if err != nil || string(data) != "/two/wall.png" {
+ t.Fatalf("wrong source bytes: %q, %v", data, err)
+ }
+}
+ {:else}{thumbError
+ ? 'Preview unavailable'
+ : 'Loading preview…'}{/if}
+ {/snippet}
+