@reidelsaltres/pureper 0.2.32 → 0.2.34

package/src/foundation/CacheManager.ts

@@ -0,0 +1,151 @@
+import Observable from "./api/Observer.js";
+import Fetcher from "./Fetcher.js";
+
+export type DownloadProgress = {
+    totalFiles: number;
+    completedFiles: number;
+    currentFile: string;
+    totalBytes: number;
+    downloadedBytes: number;
+    speed: number;
+    active: boolean;
+};
+
+export default class CacheManager {
+    private static readonly CACHE_NAME = 'purper-modules';
+
+    static resolveUrl(url: string): string {
+        return Fetcher.resolveUrl(url);
+    }
+
+    static async download(urls: string[], progress?: Observable<DownloadProgress>): Promise<number> {
+        if (urls.length === 0) return 0;
+
+        const totalFiles = urls.length;
+        let completedFiles = 0;
+        let downloadedBytes = 0;
+        let totalBytes = 0;
+        let lastTime = performance.now();
+        let lastBytes = 0;
+        let speed = 0;
+
+        const update = (currentFile: string, active: boolean) => {
+            progress?.setObject({ totalFiles, completedFiles, currentFile, totalBytes, downloadedBytes, speed, active });
+        };
+
+        // Estimate total size via HEAD
+        const sizes = await Promise.all(urls.map(async (url) => {
+            try {
+                const resp = await fetch(this.resolveUrl(url), { method: 'HEAD' });
+                const cl = resp.headers.get('content-length');
+                return cl ? parseInt(cl, 10) : 0;
+            } catch { return 0; }
+        }));
+        totalBytes = sizes.reduce((a, b) => a + b, 0);
+
+        update('', true);
+
+        const failedFiles: string[] = [];
+
+        for (const url of urls) {
+            const resolved = this.resolveUrl(url);
+            const fileName = url.split('/').pop() || url;
+            update(fileName, true);
+
+            try {
+                const response = await fetch(resolved);
+                if (!response.ok) {
+                    console.warn(`[CacheManager]: Failed to download ${url}: ${response.status}`);
+                    failedFiles.push(url);
+                    completedFiles++;
+                    continue;
+                }
+
+                const reader = response.body?.getReader();
+                const chunks: BlobPart[] = [];
+
+                if (reader) {
+                    while (true) {
+                        const { done, value } = await reader.read();
+                        if (done) break;
+                        chunks.push(value);
+                        downloadedBytes += value.byteLength;
+
+                        const now = performance.now();
+                        const elapsed = (now - lastTime) / 1000;
+                        if (elapsed >= 0.5) {
+                            speed = (downloadedBytes - lastBytes) / elapsed;
+                            lastTime = now;
+                            lastBytes = downloadedBytes;
+                        }
+
+                        update(fileName, true);
+                    }
+                }
+
+                if ('caches' in window) {
+                    try {
+                        const cache = await caches.open(this.CACHE_NAME);
+                        const blob = new Blob(chunks);
+                        const cacheResponse = new Response(blob, { headers: response.headers });
+                        await cache.put(resolved, cacheResponse);
+                    } catch (e) {
+                        console.warn(`[CacheManager]: Failed to cache ${url}`, e);
+                    }
+                }
+
+                completedFiles++;
+            } catch (e) {
+                console.warn(`[CacheManager]: Error downloading ${url}`, e);
+                failedFiles.push(url);
+                completedFiles++;
+            }
+        }
+
+        speed = 0;
+        update('', false);
+
+        if (failedFiles.length > 0) {
+            throw new Error(`[CacheManager]: ${failedFiles.length} file(s) failed to download: ${failedFiles.join(', ')}`);
+        }
+
+        return downloadedBytes;
+    }
+
+    static async delete(urls: string[]): Promise<void> {
+        if (!('caches' in window) || urls.length === 0) return;
+        const cache = await caches.open(this.CACHE_NAME);
+        for (const url of urls) {
+            await cache.delete(this.resolveUrl(url));
+        }
+    }
+
+    static async isCached(url: string): Promise<boolean> {
+        if (!('caches' in window)) return false;
+        const cache = await caches.open(this.CACHE_NAME);
+        const match = await cache.match(this.resolveUrl(url));
+        return match !== undefined;
+    }
+
+    static async getCachedSize(urls: string[]): Promise<number> {
+        if (!('caches' in window) || urls.length === 0) return 0;
+        const cache = await caches.open(this.CACHE_NAME);
+        let total = 0;
+        for (const url of urls) {
+            const match = await cache.match(this.resolveUrl(url));
+            if (match) {
+                const blob = await match.blob();
+                total += blob.size;
+            }
+        }
+        return total;
+    }
+
+    static formatBytes(bytes: number): string {
+        if (bytes === 0) return '0 B';
+        const k = 1024;
+        const sizes = ['B', 'KB', 'MB', 'GB'];
+        const i = Math.floor(Math.log(bytes) / Math.log(k));
+        return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+    }
+}

package/src/foundation/Injection.ts

@@ -165,6 +165,30 @@ export class Placeholder {
         console.info(`[Placeholder:${placeholderName}]: Reloaded ${reloads.length} instance(s)`);
     }
 
+    /** Return all registered placeholder names. */
+    public static getAllNames(): string[] {
+        return Array.from(this._all.keys());
+    }
+
+    /** Deactivate a placeholder — hides all instances. */
+    public static deactivate(name: string): void {
+        const p = this._all.get(name);
+        if (!p) return;
+        p.activeImpl.setObject(null);
+        console.info(`[Placeholder:${name}]: Deactivated`);
+    }
+
+    /** Activate a placeholder — restores the default implementation. */
+    public static activate(name: string): void {
+        const p = this._all.get(name);
+        if (!p) return;
+        const first = p.implementations.values().next().value;
+        if (first && !p.activeImpl.getObject()) {
+            p.activeImpl.setObject(first);
+            console.info(`[Placeholder:${name}]: Activated with "${first.name}"`);
+        }
+    }
+
     /**
      * Switch a single instance to a different implementation and reload it.
      * Does NOT change the global active implementation.

package/src/foundation/Module.ts

@@ -1,5 +1,14 @@
 import Observable from "./api/Observer.js";
-import { REGISTRY } from "./Triplet.js";
+import { Placeholder } from "./Injection.js";
+import { REGISTRY, RegistryCapture } from "./Triplet.js";
+import CacheManager, { DownloadProgress } from "./CacheManager.js";
+
+export type SubModuleStruct = {
+    name: string;
+    description?: string;
+    inbuilt?: boolean;
+    resources?: string[];
+};
 
 export type ModuleStruct = {
     name: string;
@@ -7,25 +16,51 @@ export type ModuleStruct = {
     icon?: string;
     core?: boolean;
     enabled?: boolean;
+    resources?: string[];
+    subModules?: SubModuleStruct[];
 };
 
-export default class Module {
+export default class Module extends Observable<boolean> {
     public readonly name: string;
     public readonly description?: string;
     public readonly icon?: string;
     public readonly core: boolean;
-    public readonly enabled: Observable<boolean>;
     public readonly downloaded: Observable<boolean>;
+    public readonly resources: string[];
+    public readonly totalSize: Observable<number>;
+    public readonly downloadProgress: Observable<DownloadProgress>;
+    public readonly downloadError: Observable<string>;
 
     private _registrations: (() => Promise<void>)[] = [];
+    private _placeholderNames: string[] = [];
+    private _initialized: boolean = false;
+    private _subModules: SubModule[] = [];
+    private static _claimedPlaceholders = new Set<string>();
+
+    public get enabled(): Observable<boolean> {
+        return this;
+    }
 
     public constructor(struct: ModuleStruct) {
+        super(struct.core ? true : (struct.enabled ?? false));
         this.name = struct.name;
         this.description = struct.description;
         this.icon = struct.icon;
         this.core = struct.core ?? false;
-        this.enabled = new Observable<boolean>(this.core ? true : (struct.enabled ?? false));
-        this.downloaded = new Observable<boolean>(this.core ? true : false);
+        this.downloaded = new Observable<boolean>(false);
+        this.resources = struct.resources ?? [];
+        this.totalSize = new Observable<number>(0);
+        this.downloadProgress = new Observable<DownloadProgress>({
+            totalFiles: 0, completedFiles: 0, currentFile: '',
+            totalBytes: 0, downloadedBytes: 0, speed: 0, active: false
+        });
+        this.downloadError = new Observable<string>('');
+
+        if (struct.subModules) {
+            for (const sub of struct.subModules) {
+                this.addSubModule(sub);
+            }
+        }
     }
 
     public addRegistration(fn: () => Promise<void>): void {
@@ -46,12 +81,60 @@ export default class Module {
     public captureRegistrations(registry: (() => Promise<void>)[]): void {
         const captured = registry.splice(0, registry.length);
         this._registrations.push(...captured);
-        console.log(`[Module]: "${this.name}" captured ${captured.length} registration(s)`);
+
+        // Discover placeholder names created by this module's imports
+        for (const name of Placeholder.getAllNames()) {
+            if (!Module._claimedPlaceholders.has(name)) {
+                Module._claimedPlaceholders.add(name);
+                this._placeholderNames.push(name);
+            }
+        }
+
+        console.log(`[Module]: "${this.name}" captured ${captured.length} registration(s), ${this._placeholderNames.length} placeholder(s)`);
+
+        const capturedResources = RegistryCapture.drain();
+        if (capturedResources.length > 0) {
+            this.resources.push(...capturedResources);
+            console.log(`[Module]: "${this.name}" auto-captured ${capturedResources.length} resource path(s)`);
+        }
+    }
+
+    public addPlaceholder(name: string): void {
+        this._placeholderNames.push(name);
+    }
+
+    public getPlaceholderNames(): ReadonlyArray<string> {
+        return this._placeholderNames;
+    }
+
+    public markInitialized(): void {
+        this._initialized = true;
     }
 
-    public enable(): void {
-        if (this.enabled.getObject() === true) return;
-        this.enabled.setObject(true);
+    public async enable(): Promise<void> {
+        if (this.getObject() === true) return;
+        this.setObject(true);
+
+        if (!this._initialized) {
+            this._initialized = true;
+            // Snapshot existing placeholders before running registrations
+            const before = new Set(Placeholder.getAllNames());
+            for (const reg of this._registrations) {
+                await reg();
+            }
+            // Discover which placeholders were added by this module
+            for (const name of Placeholder.getAllNames()) {
+                if (!before.has(name)) {
+                    this._placeholderNames.push(name);
+                }
+            }
+        } else {
+            // Re-activate previously registered placeholders
+            for (const name of this._placeholderNames) {
+                Placeholder.activate(name);
+            }
+        }
+
         console.log(`[Module]: "${this.name}" enabled`);
     }
 
@@ -59,13 +142,19 @@ export default class Module {
         if (this.core) {
             throw new Error(`[Module]: Cannot disable core module "${this.name}"`);
         }
-        if (this.enabled.getObject() === false) return;
-        this.enabled.setObject(false);
+        if (this.getObject() === false) return;
+        this.setObject(false);
+
+        // Deactivate placeholders
+        for (const name of this._placeholderNames) {
+            Placeholder.deactivate(name);
+        }
+
         console.log(`[Module]: "${this.name}" disabled`);
     }
 
     public isActive(): boolean {
-        return this.enabled.getObject() === true;
+        return this.getObject() === true;
     }
 
     /** True if enabled but not downloaded — works only in the current session. */
@@ -73,22 +162,161 @@ export default class Module {
         return this.isActive() && !this.downloaded.getObject();
     }
 
-    public download(): void {
-        this.downloaded.setObject(true);
-        console.log(`[Module]: "${this.name}" downloaded`);
+    public async download(): Promise<void> {
+        if (this.downloaded.getObject()) return;
+        this.downloadError.setObject('');
+
+        const hasInbuiltSubs = this._subModules.some(s => s.inbuilt && !s.downloaded.getObject() && s.resources.length > 0);
+        if (this.resources.length === 0 && !hasInbuiltSubs) {
+            this.downloaded.setObject(true);
+            console.log(`[Module]: "${this.name}" downloaded (no resources)`);
+            return;
+        }
+
+        try {
+            // Download module's own resources
+            let totalBytes = await CacheManager.download(this.resources, this.downloadProgress);
+
+            // Also download all inbuilt sub-modules
+            for (const sub of this._subModules) {
+                if (sub.inbuilt && !sub.downloaded.getObject()) {
+                    const subBytes = await CacheManager.download(sub.resources, this.downloadProgress);
+                    sub.totalSize.setObject(subBytes);
+                    sub.downloaded.setObject(true);
+                    totalBytes += subBytes;
+                }
+            }
+
+            this.totalSize.setObject(totalBytes);
+            this.downloaded.setObject(true);
+            // Clear ephemeral flag if re-downloaded
+            ModuleManager.clearEphemeralCore(this.name);
+            console.log(`[Module]: "${this.name}" downloaded (${this.resources.length} files, ${CacheManager.formatBytes(totalBytes)})`);
+        } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            this.downloadError.setObject(msg);
+            console.error(`[Module]: "${this.name}" download failed:`, msg);
+        }
     }
 
-    public undownload(): void {
-        if (this.core) {
-            throw new Error(`[Module]: Cannot remove core module "${this.name}" from downloads`);
+    public formatBytes(bytes: number): string {
+        return CacheManager.formatBytes(bytes);
+    }
+
+    public async undownload(): Promise<void> {
+        this.downloadError.setObject('');
+        await CacheManager.delete(this.resources);
+
+        // Also undownload all sub-modules
+        for (const sub of this._subModules) {
+            if (sub.downloaded.getObject()) {
+                if (sub.inbuilt) {
+                    // Inbuilt subs: clean up directly (bypass the guard)
+                    await CacheManager.delete(sub.resources);
+                    sub.downloaded.setObject(false);
+                    sub.totalSize.setObject(0);
+                    sub.downloadError.setObject('');
+                } else {
+                    await sub.undownload();
+                }
+            }
         }
+
         this.downloaded.setObject(false);
+        this.totalSize.setObject(0);
         console.log(`[Module]: "${this.name}" removed from downloads`);
     }
+
+    public addSubModule(struct: SubModuleStruct): SubModule {
+        const sub = new SubModule(struct, this);
+        this._subModules.push(sub);
+        return sub;
+    }
+
+    public getSubModules(): ReadonlyArray<SubModule> {
+        return this._subModules;
+    }
+}
+
+export class SubModule {
+    public readonly name: string;
+    public readonly description?: string;
+    public readonly inbuilt: boolean;
+    public readonly resources: string[];
+    public readonly downloaded: Observable<boolean>;
+    public readonly parent: Module;
+    public readonly totalSize: Observable<number>;
+    public readonly downloadProgress: Observable<DownloadProgress>;
+    public readonly downloadError: Observable<string>;
+
+    constructor(struct: SubModuleStruct, parent: Module) {
+        this.name = struct.name;
+        this.description = struct.description;
+        this.inbuilt = struct.inbuilt ?? true;
+        this.resources = struct.resources ?? [];
+        this.downloaded = new Observable<boolean>(false);
+        this.parent = parent;
+        this.totalSize = new Observable<number>(0);
+        this.downloadProgress = new Observable<DownloadProgress>({
+            totalFiles: 0, completedFiles: 0, currentFile: '',
+            totalBytes: 0, downloadedBytes: 0, speed: 0, active: false
+        });
+        this.downloadError = new Observable<string>('');
+    }
+
+    private assertParentActive(): void {
+        if (!this.parent.isActive()) {
+            throw new Error(`[SubModule]: Cannot access "${this.name}" — parent module "${this.parent.name}" is disabled`);
+        }
+    }
+    private assertParentDownloaded(): void {
+        if (!this.parent.downloaded.getObject()) {
+            throw new Error(`[SubModule]: Cannot access "${this.name}" — parent module "${this.parent.name}" is not downloaded`);
+        }
+    }
+
+    public async download(): Promise<void> {
+        if (this.inbuilt) {
+            throw new Error(`[SubModule]: "${this.name}" is inbuilt and cannot be downloaded separately`);
+        }
+        this.assertParentDownloaded();
+        if (this.downloaded.getObject()) return;
+        this.downloadError.setObject('');
+
+        if (this.resources.length === 0) {
+            this.downloaded.setObject(true);
+            return;
+        }
+
+        try {
+            const bytes = await CacheManager.download(this.resources, this.downloadProgress);
+            this.totalSize.setObject(bytes);
+            this.downloaded.setObject(true);
+            console.log(`[SubModule]: "${this.name}" of "${this.parent.name}" downloaded (${CacheManager.formatBytes(bytes)})`);
+        } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            this.downloadError.setObject(msg);
+            console.error(`[SubModule]: "${this.name}" download failed:`, msg);
+        }
+    }
+
+    public async undownload(): Promise<void> {
+        if (this.inbuilt) {
+            throw new Error(`[SubModule]: "${this.name}" is inbuilt and cannot be removed separately`);
+        }
+        if (!this.downloaded.getObject()) return;
+        this.downloadError.setObject('');
+
+        await CacheManager.delete(this.resources);
+        this.downloaded.setObject(false);
+        this.totalSize.setObject(0);
+        console.log(`[SubModule]: "${this.name}" of "${this.parent.name}" removed from downloads`);
+    }
 }
 
 export class ModuleManager {
     private static _modules: Map<string, Module> = new Map();
+    private static _userEphemeralCores = new Set<string>();
     private static readonly STORAGE_KEY = "purper:modules";
     private static readonly SESSION_KEY = "purper:modules:session";
 
@@ -129,6 +357,7 @@ export class ModuleManager {
 
         for (const mod of this._modules.values()) {
             if (mod.isActive()) {
+                mod.markInitialized();
                 console.log(`[Module]: Initializing module "${mod.name}" (${mod.getRegistrations().length} registration(s))`);
                 for (const reg of mod.getRegistrations()) {
                     promises.push(reg());
@@ -147,18 +376,50 @@ export class ModuleManager {
             }
         }
 
+        // Auto-download enabled modules that are not yet downloaded
+        // (fire-and-forget — does not block initialization)
+        this.autoDownload();
+
         return promises;
     }
 
+    private static async autoDownload(): Promise<void> {
+        for (const mod of this._modules.values()) {
+            if (mod.core && !mod.downloaded.getObject() && !this._userEphemeralCores.has(mod.name)) {
+                console.log(`[Module]: Auto-downloading "${mod.name}"...`);
+                mod.download().then(() => {
+                    this.persistState();
+                }).catch(e => {
+                    console.warn(`[Module]: Auto-download failed for "${mod.name}"`, e);
+                });
+            }
+        }
+    }
+
     static persistState(): void {
-        const localState: Record<string, { enabled: boolean, downloaded: boolean }> = {};
+        const localState: Record<string, { enabled: boolean, downloaded: boolean, size: number, subModules?: Record<string, { downloaded: boolean, size: number }> }> = {};
         const sessionState: Record<string, { enabled: boolean }> = {};
 
         for (const mod of this._modules.values()) {
-            if (mod.core) continue;
+            const subs = mod.getSubModules();
+            let subModules: Record<string, { downloaded: boolean, size: number }> | undefined;
+            if (subs.length > 0) {
+                subModules = {};
+                for (const sub of subs) {
+                    subModules[sub.name] = {
+                        downloaded: sub.downloaded.getObject() === true,
+                        size: sub.totalSize.getObject() ?? 0
+                    };
+                }
+            }
 
-            if (mod.downloaded.getObject()) {
-                localState[mod.name] = { enabled: mod.isActive(), downloaded: true };
+            if (mod.downloaded.getObject() || mod.core) {
+                localState[mod.name] = {
+                    enabled: mod.isActive(),
+                    downloaded: mod.downloaded.getObject() === true,
+                    size: mod.totalSize.getObject() ?? 0,
+                    ...(subModules ? { subModules } : {})
+                };
             } else if (mod.isActive()) {
                 sessionState[mod.name] = { enabled: true };
             }
@@ -173,25 +434,49 @@ export class ModuleManager {
         }
     }
 
+    static clearEphemeralCore(name: string): void {
+        this._userEphemeralCores.delete(name);
+    }
+
     static restoreState(): void {
         // Restore from localStorage (downloaded modules)
         try {
             const raw = localStorage.getItem(this.STORAGE_KEY);
             if (raw) {
-                const state: Record<string, { enabled: boolean, downloaded: boolean } | boolean> = JSON.parse(raw);
+                const state: Record<string, { enabled: boolean, downloaded: boolean, size?: number, subModules?: Record<string, { enabled?: boolean, downloaded: boolean, size?: number }> } | boolean> = JSON.parse(raw);
                 for (const [name, data] of Object.entries(state)) {
                     const mod = this._modules.get(name);
-                    if (mod && !mod.core) {
+                    if (mod) {
                         if (typeof data === 'boolean') {
                             // Old format: value is just a boolean for enabled state
-                            mod.enabled.setObject(data);
+                            if (!mod.core) mod.setObject(data);
                             console.log(`[Module]: Migrated old format "${name}" → enabled=${data}`);
                             continue;
                         }
                         if (data.downloaded) {
                             mod.downloaded.setObject(true);
                         }
-                        mod.enabled.setObject(data.enabled);
+                        if (data.size) {
+                            mod.totalSize.setObject(data.size);
+                        }
+                        if (!mod.core) {
+                            mod.setObject(data.enabled);
+                        }
+                        // Track core modules explicitly made ephemeral by user
+                        if (mod.core && !data.downloaded) {
+                            this._userEphemeralCores.add(name);
+                        }
+                        if (data.subModules) {
+                            for (const sub of mod.getSubModules()) {
+                                const subData = data.subModules[sub.name];
+                                if (subData) {
+                                    sub.downloaded.setObject(subData.downloaded);
+                                    if (subData.size) {
+                                        sub.totalSize.setObject(subData.size);
+                                    }
+                                }
+                            }
+                        }
                         console.log(`[Module]: Restored "${name}" → downloaded=${data.downloaded}, enabled=${data.enabled}`);
                     }
                 }
@@ -208,7 +493,7 @@ export class ModuleManager {
                 for (const [name, data] of Object.entries(state)) {
                     const mod = this._modules.get(name);
                     if (mod && !mod.core && !mod.downloaded.getObject()) {
-                        mod.enabled.setObject(data.enabled);
+                        mod.setObject(data.enabled);
                         console.log(`[Module]: Restored ephemeral "${name}" → enabled=${data.enabled}`);
                     }
                 }

package/src/foundation/Theme.ts

@@ -1,6 +1,7 @@
 import Fetcher from "./Fetcher.js";
 import Observable from "./api/Observer.js";
 
+export const DEFAULT_THEME = "Blazor";
 export let ACTIVE_THEME_KEY = "Empty";
 let activeThemeSheet: CSSStyleSheet | null = null;
 let _internalThemeSwitch = false;
@@ -20,7 +21,7 @@ export async function init() {
     if (ACTIVE_THEME_KEY) {
         await setTheme(ACTIVE_THEME_KEY);
     } else {
-        await setTheme("Blazor");
+        await setTheme(DEFAULT_THEME);
     }
 }
 export async function setTheme(name: string) {
@@ -168,3 +169,11 @@ export async function deactivateAppTheme(): Promise<void> {
     console.info(`[Theme]: AppTheme "${current.name}" deactivated`);
 }
 
+export async function resetToDefault(): Promise<void> {
+    await deactivateAppTheme();
+    await setTheme(DEFAULT_THEME);
+    ACTIVE_THEME_KEY = DEFAULT_THEME;
+    localStorage.setItem("theme", DEFAULT_THEME);
+    console.info(`[Theme]: Reset to default theme "${DEFAULT_THEME}"`);
+}
+

package/src/foundation/Triplet.ts

@@ -10,6 +10,27 @@ import { Implementation, ImplementationStruct, Placeholder } from "./Injection.j
 
 export const REGISTRY: (() => Promise<void>)[] = [];
 
+export class RegistryCapture {
+    private static _unclaimed: string[] = [];
+    private static _classResources = new Map<Function, string[]>();
+
+    /** Called by decorators to record which file paths a class uses. */
+    static capture(cls: Function, paths: string[]): void {
+        this._classResources.set(cls, paths);
+        this._unclaimed.push(...paths);
+    }
+
+    /** Drain all unclaimed resource paths. Called by Module.captureRegistrations(). */
+    static drain(): string[] {
+        return this._unclaimed.splice(0);
+    }
+
+    /** Get resource paths for a specific class. */
+    static getResources(cls: Function): string[] {
+        return this._classResources.get(cls) ?? [];
+    }
+}
+
 export enum AccessType {
     NONE = 0,
     OFFLINE = 1 << 0,