@almadar/orb-shell-typescript-linux-x64 18.0.0 → 19.0.3

package/templates/almadar-renderers-typescript/src/hooks/useGameAudio.ts

@@ -0,0 +1,411 @@
+'use client';
+/**
+ * useGameAudio Hook
+ *
+ * Manages HTMLAudioElement pools for low-latency, concurrent sound playback,
+ * plus a dedicated music player with crossfade transitions.
+ *
+ * Two separate systems:
+ *   SFX pool:    play(key)  — instant, concurrent, pooled instances
+ *   Music player: playMusic(key) — crossfades between looping background tracks
+ *
+ * Autoplay policy:
+ *   Browsers block audio until a user gesture. This hook registers a one-time
+ *   listener (click/keydown/touchstart) that:
+ *   - Starts all `autostart: true` SFX entries
+ *   - Plays any pending music that was requested before unlock
+ *
+ * @packageDocumentation
+ */
+
+import { useRef, useState, useCallback, useEffect } from 'react';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Core owns the sound-manifest shape (`@almadar/core` `types/asset.ts`) so the
+ *  pattern extractor and the generated `.lolo` factories resolve the same
+ *  declaration; re-exported here for the hook's existing consumers. */
+export type { SoundEntry, AudioManifest } from '@almadar/core';
+import type { SoundEntry, AudioManifest } from '@almadar/core';
+
+export interface GameAudioControls {
+    /** Play a sound effect (instant, pooled) */
+    play: (key: string) => void;
+    /** Stop all instances of a sound effect */
+    stop: (key: string) => void;
+    /** Stop all sounds including music */
+    stopAll: () => void;
+    /** Crossfade to a new music track */
+    playMusic: (key: string) => void;
+    /** Fade out and stop the current music */
+    stopMusic: (fadeDurationMs?: number) => void;
+    muted: boolean;
+    setMuted: (muted: boolean) => void;
+    masterVolume: number;
+    setMasterVolume: (volume: number) => void;
+}
+
+export interface UseGameAudioOptions {
+    /** Sound definitions keyed by logical name */
+    manifest: AudioManifest;
+    /** Prefix prepended to all `path` values (default '') */
+    baseUrl?: string;
+    /** Start muted (default false) */
+    initialMuted?: boolean;
+    /** Master volume 0–1 (default 1) */
+    initialVolume?: number;
+}
+
+// =============================================================================
+// Internal helpers
+// =============================================================================
+
+type AudioPool = HTMLAudioElement[];
+
+function pickPath(entry: SoundEntry): string {
+    if (Array.isArray(entry.path)) {
+        return entry.path[Math.floor(Math.random() * entry.path.length)];
+    }
+    return entry.path;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useGameAudio({
+    manifest,
+    baseUrl = '',
+    initialMuted = false,
+    initialVolume = 1,
+}: UseGameAudioOptions): GameAudioControls {
+    const [muted, setMutedState] = useState(initialMuted);
+    const [masterVolume, setMasterVolumeState] = useState(initialVolume);
+
+    // Refs avoid stale closures in RAF / setTimeout / interval callbacks
+    const mutedRef = useRef(muted);
+    const volumeRef = useRef(masterVolume);
+    const manifestRef = useRef(manifest);
+    mutedRef.current = muted;
+    volumeRef.current = masterVolume;
+    manifestRef.current = manifest;
+
+    // -------------------------------------------------------------------------
+    // SFX pool
+    // -------------------------------------------------------------------------
+
+    const poolsRef = useRef(new Map<string, AudioPool>());
+
+    const getOrCreateElement = useCallback((key: string): HTMLAudioElement | null => {
+        const entry = manifestRef.current[key];
+        if (!entry) return null;
+
+        let pool = poolsRef.current.get(key);
+        if (!pool) {
+            pool = [];
+            poolsRef.current.set(key, pool);
+        }
+
+        const maxSize = entry.poolSize ?? 1;
+
+        // Prefer a finished/idle element
+        for (const audio of pool) {
+            if (audio.paused && (audio.ended || audio.currentTime === 0)) {
+                return audio;
+            }
+        }
+
+        // Create a new element if pool isn't at capacity
+        if (pool.length < maxSize) {
+            const src = baseUrl + pickPath(entry);
+            const audio = new Audio(src);
+            audio.loop = entry.loop ?? false;
+            pool.push(audio);
+            return audio;
+        }
+
+        // Pool full: for non-looping sounds, reuse the furthest-along one
+        if (!entry.loop) {
+            let oldest = pool[0];
+            for (const audio of pool) {
+                if (audio.currentTime > oldest.currentTime) {
+                    oldest = audio;
+                }
+            }
+            oldest.pause();
+            oldest.currentTime = 0;
+            return oldest;
+        }
+
+        // Looping sound already playing — don't interrupt
+        return null;
+    }, [baseUrl]);
+
+    const play = useCallback((key: string) => {
+        if (mutedRef.current) return;
+        const entry = manifestRef.current[key];
+        if (!entry) return;
+
+        const audio = getOrCreateElement(key);
+        if (!audio) return;
+
+        audio.volume = Math.min(1, (entry.volume ?? 1) * volumeRef.current);
+        if (!entry.loop) {
+            audio.currentTime = 0;
+        }
+
+        const promise = audio.play();
+        if (promise) {
+            promise.catch(() => {
+                // Autoplay blocked — silently ignored. The unlock mechanism
+                // will start autostart sounds after the first user gesture.
+            });
+        }
+    }, [getOrCreateElement]);
+
+    const stop = useCallback((key: string) => {
+        const pool = poolsRef.current.get(key);
+        if (!pool) return;
+        for (const audio of pool) {
+            audio.pause();
+            audio.currentTime = 0;
+        }
+    }, []);
+
+    // -------------------------------------------------------------------------
+    // Music player (crossfade)
+    // -------------------------------------------------------------------------
+
+    const currentMusicKeyRef = useRef<string | null>(null);
+    const currentMusicElRef = useRef<HTMLAudioElement | null>(null);
+    const musicFadeRef = useRef<ReturnType<typeof setInterval> | null>(null);
+    /** Music key requested before browser unlock — played on first gesture */
+    const pendingMusicKeyRef = useRef<string | null>(null);
+
+    const clearMusicFade = useCallback(() => {
+        if (musicFadeRef.current) {
+            clearInterval(musicFadeRef.current);
+            musicFadeRef.current = null;
+        }
+    }, []);
+
+    const playMusic = useCallback((key: string) => {
+        if (key === currentMusicKeyRef.current) return;
+        pendingMusicKeyRef.current = key;
+
+        const entry = manifestRef.current[key];
+        if (!entry) return;
+
+        const fadeDurationMs = entry.crossfadeDurationMs ?? 1500;
+        const stepMs = 50;
+        const totalSteps = Math.max(1, fadeDurationMs / stepMs);
+        const targetVolume = Math.min(1, (entry.volume ?? 1) * volumeRef.current);
+
+        clearMusicFade();
+
+        // Create new music element
+        const src = baseUrl + (Array.isArray(entry.path) ? entry.path[0] : entry.path);
+        const incoming = new Audio(src);
+        incoming.loop = true;
+        incoming.volume = 0;
+
+        const outgoing = currentMusicElRef.current;
+        const outgoingStartVol = outgoing?.volume ?? 0;
+
+        currentMusicKeyRef.current = key;
+        currentMusicElRef.current = incoming;
+
+        if (!mutedRef.current) {
+            incoming.play().catch(() => {
+                // Blocked — will retry when user interacts (pendingMusicKeyRef is set)
+                currentMusicKeyRef.current = null;
+                currentMusicElRef.current = outgoing;
+            });
+        }
+
+        let step = 0;
+        musicFadeRef.current = setInterval(() => {
+            step++;
+            const progress = Math.min(step / totalSteps, 1);
+
+            // Fade in incoming
+            incoming.volume = Math.min(1, targetVolume * progress);
+
+            // Fade out outgoing
+            if (outgoing) {
+                outgoing.volume = Math.max(0, outgoingStartVol * (1 - progress));
+            }
+
+            if (progress >= 1) {
+                clearMusicFade();
+                if (outgoing) {
+                    outgoing.pause();
+                    outgoing.src = '';
+                }
+            }
+        }, stepMs);
+    }, [baseUrl, clearMusicFade]);
+
+    const stopMusic = useCallback((fadeDurationMs = 1000) => {
+        const outgoing = currentMusicElRef.current;
+        if (!outgoing) return;
+
+        currentMusicKeyRef.current = null;
+        currentMusicElRef.current = null;
+        pendingMusicKeyRef.current = null;
+        clearMusicFade();
+
+        const startVolume = outgoing.volume;
+        const stepMs = 50;
+        const totalSteps = Math.max(1, fadeDurationMs / stepMs);
+        let step = 0;
+
+        musicFadeRef.current = setInterval(() => {
+            step++;
+            const progress = step / totalSteps;
+            outgoing.volume = Math.max(0, startVolume * (1 - progress));
+            if (progress >= 1) {
+                clearMusicFade();
+                outgoing.pause();
+                outgoing.src = '';
+            }
+        }, stepMs);
+    }, [clearMusicFade]);
+
+    // -------------------------------------------------------------------------
+    // Mute / volume controls
+    // -------------------------------------------------------------------------
+
+    const stopAll = useCallback(() => {
+        for (const pool of poolsRef.current.values()) {
+            for (const audio of pool) {
+                audio.pause();
+                audio.currentTime = 0;
+            }
+        }
+        stopMusic(0);
+    }, [stopMusic]);
+
+    const setMuted = useCallback((value: boolean) => {
+        setMutedState(value);
+        if (value) {
+            // Pause all looping SFX
+            for (const [key, pool] of poolsRef.current.entries()) {
+                if (manifestRef.current[key]?.loop) {
+                    for (const audio of pool) {
+                        if (!audio.paused) audio.pause();
+                    }
+                }
+            }
+            // Pause music
+            currentMusicElRef.current?.pause();
+        } else {
+            // Resume looping autostart SFX
+            for (const [key, pool] of poolsRef.current.entries()) {
+                const entry = manifestRef.current[key];
+                if (entry?.loop && entry?.autostart) {
+                    for (const audio of pool) {
+                        if (audio.paused) audio.play().catch(() => {});
+                    }
+                }
+            }
+            // Resume music
+            const musicEl = currentMusicElRef.current;
+            if (musicEl) {
+                musicEl.play().catch(() => {});
+            }
+        }
+    }, []);
+
+    const setMasterVolume = useCallback((volume: number) => {
+        const clamped = Math.max(0, Math.min(1, volume));
+        setMasterVolumeState(clamped);
+        // Update all SFX elements
+        for (const [key, pool] of poolsRef.current.entries()) {
+            const entryVol = manifestRef.current[key]?.volume ?? 1;
+            for (const audio of pool) {
+                audio.volume = Math.min(1, entryVol * clamped);
+            }
+        }
+        // Update music element (only if not mid-fade)
+        if (!musicFadeRef.current && currentMusicElRef.current) {
+            const key = currentMusicKeyRef.current;
+            const entryVol = key ? (manifestRef.current[key]?.volume ?? 1) : 1;
+            currentMusicElRef.current.volume = Math.min(1, entryVol * clamped);
+        }
+    }, []);
+
+    // -------------------------------------------------------------------------
+    // Autoplay unlock (first user gesture)
+    // -------------------------------------------------------------------------
+
+    const unlockedRef = useRef(false);
+
+    useEffect(() => {
+        const autoKeys = Object.keys(manifest).filter(k => manifest[k].autostart);
+        const hasPendingMusic = () => pendingMusicKeyRef.current !== null;
+        const hasAutoStart = autoKeys.length > 0;
+
+        if (!hasAutoStart && !hasPendingMusic()) return;
+
+        const unlock = () => {
+            if (unlockedRef.current) return;
+            unlockedRef.current = true;
+
+            if (!mutedRef.current) {
+                // Play autostart SFX
+                for (const key of autoKeys) {
+                    play(key);
+                }
+                // Play pending music (requested before unlock)
+                const pending = pendingMusicKeyRef.current;
+                if (pending && pending !== currentMusicKeyRef.current) {
+                    playMusic(pending);
+                }
+            }
+        };
+
+        document.addEventListener('click', unlock, { once: true });
+        document.addEventListener('keydown', unlock, { once: true });
+        document.addEventListener('touchstart', unlock, { once: true });
+
+        return () => {
+            document.removeEventListener('click', unlock);
+            document.removeEventListener('keydown', unlock);
+            document.removeEventListener('touchstart', unlock);
+        };
+    }, [manifest, play, playMusic]);
+
+    // -------------------------------------------------------------------------
+    // Cleanup on unmount
+    // -------------------------------------------------------------------------
+
+    useEffect(() => {
+        return () => {
+            clearMusicFade();
+            for (const pool of poolsRef.current.values()) {
+                for (const audio of pool) {
+                    audio.pause();
+                    audio.src = '';
+                }
+            }
+            poolsRef.current.clear();
+            if (currentMusicElRef.current) {
+                currentMusicElRef.current.pause();
+                currentMusicElRef.current.src = '';
+                currentMusicElRef.current = null;
+            }
+        };
+    }, [clearMusicFade]);
+
+    return {
+        play, stop, stopAll,
+        playMusic, stopMusic,
+        muted, setMuted,
+        masterVolume, setMasterVolume,
+    };
+}
+
+useGameAudio.displayName = 'useGameAudio';

package/templates/almadar-renderers-typescript/src/hooks/useGitHub.ts

@@ -0,0 +1,152 @@
+'use client';
+/**
+ * GitHub Integration Hooks
+ *
+ * React hooks for GitHub OAuth and repository management.
+ */
+
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { useCallback } from 'react';
+
+/**
+ * GitHub connection status
+ */
+export interface GitHubStatus {
+  connected: boolean;
+  username?: string;
+  avatarUrl?: string;
+  scopes?: string[];
+  connectedAt?: number;
+  lastUsedAt?: number;
+}
+
+/**
+ * GitHub repository
+ */
+export interface GitHubRepo {
+  id: number;
+  name: string;
+  fullName: string;
+  owner: string;
+  isPrivate: boolean;
+  description: string | null;
+  defaultBranch: string;
+  url: string;
+}
+
+/**
+ * API base URL
+ */
+const API_BASE = (typeof process !== 'undefined' && process.env?.VITE_API_URL)
+  ? process.env.VITE_API_URL
+  : 'http://localhost:3000';
+
+/**
+ * Get user ID from context/auth
+ * TODO: Replace with actual auth context
+ */
+function getUserId(): string {
+  // This should come from your auth context
+  return localStorage.getItem('userId') || 'anonymous';
+}
+
+/**
+ * Fetch with auth headers
+ */
+async function fetchWithAuth<T>(endpoint: string, options?: RequestInit): Promise<T> {
+  const userId = getUserId();
+
+  const response = await fetch(`${API_BASE}${endpoint}`, {
+    ...options,
+    headers: {
+      'Content-Type': 'application/json',
+      'x-user-id': userId,
+      ...options?.headers,
+    },
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ error: response.statusText }));
+    throw new Error(error.error || error.message || 'Request failed');
+  }
+
+  return response.json();
+}
+
+/**
+ * Hook to get GitHub connection status
+ */
+export function useGitHubStatus() {
+  return useQuery<GitHubStatus>({
+    queryKey: ['github', 'status'],
+    queryFn: () => fetchWithAuth<GitHubStatus>('/api/github/status'),
+    staleTime: 60000, // 1 minute
+    retry: false,
+  });
+}
+
+/**
+ * Hook to connect GitHub (initiate OAuth flow)
+ */
+export function useConnectGitHub() {
+  const connectGitHub = useCallback(() => {
+    const userId = getUserId();
+    const state = btoa(JSON.stringify({ userId, returnUrl: window.location.href }));
+    window.location.href = `${API_BASE}/api/github/oauth/authorize?state=${state}`;
+  }, []);
+
+  return { connectGitHub };
+}
+
+/**
+ * Hook to disconnect GitHub
+ */
+export function useDisconnectGitHub() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: () => fetchWithAuth('/api/github/disconnect', { method: 'POST' }),
+    onSuccess: () => {
+      // Invalidate status query
+      queryClient.invalidateQueries({ queryKey: ['github', 'status'] });
+      // Clear repos cache
+      queryClient.removeQueries({ queryKey: ['github', 'repos'] });
+    },
+  });
+}
+
+/**
+ * Hook to list GitHub repositories
+ */
+export function useGitHubRepos(page = 1, perPage = 30) {
+  return useQuery<{ repos: GitHubRepo[]; page: number; perPage: number }>({
+    queryKey: ['github', 'repos', page, perPage],
+    queryFn: () => fetchWithAuth(`/api/github/repos?page=${page}&per_page=${perPage}`),
+    enabled: true, // Only fetch if user is connected
+    staleTime: 300000, // 5 minutes
+  });
+}
+
+/**
+ * Hook to get repository details
+ */
+export function useGitHubRepo(owner: string, repo: string, enabled = true) {
+  return useQuery<{ repo: GitHubRepo }>({
+    queryKey: ['github', 'repo', owner, repo],
+    queryFn: () => fetchWithAuth(`/api/github/repos/${owner}/${repo}`),
+    enabled: enabled && !!owner && !!repo,
+    staleTime: 300000, // 5 minutes
+  });
+}
+
+/**
+ * Hook to list repository branches
+ */
+export function useGitHubBranches(owner: string, repo: string, enabled = true) {
+  return useQuery<{ branches: string[] }>({
+    queryKey: ['github', 'branches', owner, repo],
+    queryFn: () => fetchWithAuth(`/api/github/repos/${owner}/${repo}/branches`),
+    enabled: enabled && !!owner && !!repo,
+    staleTime: 60000, // 1 minute
+  });
+}

package/templates/almadar-renderers-typescript/src/hooks/useImageCache.ts

@@ -0,0 +1,78 @@
+'use client';
+/**
+ * useImageCache Hook
+ *
+ * Preloads and caches images by URL for canvas rendering.
+ * Returns a getter function that returns loaded HTMLImageElement instances.
+ * Tracks loading progress to support isLoading state.
+ *
+ * @packageDocumentation
+ */
+
+import { useRef, useEffect, useState, useCallback } from 'react';
+import { updateAssetStatus } from '../lib/verificationRegistry';
+
+interface ImageCacheResult {
+    /** Get a cached image by URL. Returns undefined if not yet loaded. */
+    getImage: (url: string) => HTMLImageElement | undefined;
+    /** Whether all requested images have loaded */
+    isLoaded: boolean;
+    /** Number of images currently loading */
+    pendingCount: number;
+}
+
+/**
+ * Preload and cache images for canvas rendering.
+ *
+ * @param urls - Array of image URLs to preload
+ * @returns Cache getter, loading state, and pending count
+ */
+export function useImageCache(urls: string[]): ImageCacheResult {
+    const cacheRef = useRef<Map<string, HTMLImageElement>>(new Map());
+    const loadingRef = useRef<Set<string>>(new Set());
+    const [pendingCount, setPendingCount] = useState(0);
+
+    useEffect(() => {
+        const cache = cacheRef.current;
+        const loading = loadingRef.current;
+
+        // Collect URLs that aren't already cached or loading
+        const newUrls = urls.filter(url => url && !cache.has(url) && !loading.has(url));
+
+        if (newUrls.length === 0) return;
+
+        setPendingCount(prev => prev + newUrls.length);
+
+        for (const url of newUrls) {
+            loading.add(url);
+            const img = new Image();
+            img.crossOrigin = 'anonymous';
+
+            img.onload = () => {
+                cache.set(url, img);
+                loading.delete(url);
+                setPendingCount(prev => Math.max(0, prev - 1));
+                updateAssetStatus(url, 'loaded');
+            };
+
+            img.onerror = () => {
+                loading.delete(url);
+                setPendingCount(prev => Math.max(0, prev - 1));
+                updateAssetStatus(url, 'failed');
+            };
+
+            updateAssetStatus(url, 'pending');
+            img.src = url;
+        }
+    }, [urls.join(',')]);
+
+    const getImage = useCallback((url: string): HTMLImageElement | undefined => {
+        return cacheRef.current.get(url);
+    }, []);
+
+    return {
+        getImage,
+        isLoaded: pendingCount === 0,
+        pendingCount,
+    };
+}