synthos 0.10.1 → 0.11.0

package/src/pages.ts

@@ -1,6 +1,13 @@
 import {checkIfExists, listFolders, loadFile} from './files';
 import path from 'path';
 import { SynthOSConfig } from './init';
+import { SectionMode } from './builders/types';
+
+const VALID_SECTION_MODES: ReadonlySet<SectionMode> = new Set<SectionMode>([
+    'always-full',
+    'classifier-decides',
+    'always-omit-when-empty',
+]);
 
 /**
  * Derive the list of required page names by scanning *.html files
@@ -28,6 +35,7 @@ export const PAGE_VERSION = 3;
 export interface PageInfo {
     name: string;
     title: string;
+    description: string;   // one-line summary of what the page does
     categories: string[];
     pinned: boolean;
     showInAll: boolean;    // true = visible in "All" filter, false = only in category filters
@@ -35,6 +43,14 @@ export interface PageInfo {
     lastModified: string;  // ISO 8601, empty string if unknown
     pageVersion: number;   // integer, 0 = pre-versioning
     mode: 'unlocked' | 'locked';
+    greeting: string;              // initial greeting shown when page loads
+    firstRunGreeting: string;      // greeting shown when ?firstRun=true (e.g. builder first launch)
+    /**
+     * Per-page overrides for builder context-section modes. Maps a section
+     * title (e.g. "<FLUENTLM_COMPONENTS>") to a SectionMode that overrides
+     * the producer-declared default. Optional and rarely needed.
+     */
+    sectionModes?: Record<string, SectionMode>;
 }
 
 export type PageMetadata = Omit<PageInfo, 'name'>;
@@ -75,8 +91,9 @@ export async function loadPageMetadata(config: SynthOSConfig, name: string, fall
 }
 
 export function parseMetadata(parsed: Record<string, unknown>): PageMetadata {
-    return {
+    const result: PageMetadata = {
         title: typeof parsed.title === 'string' ? parsed.title : '',
+        description: typeof parsed.description === 'string' ? parsed.description : '',
         categories: Array.isArray(parsed.categories) ? parsed.categories : [],
         pinned: typeof parsed.pinned === 'boolean' ? parsed.pinned : false,
         showInAll: typeof parsed.showInAll === 'boolean' ? parsed.showInAll : true,
@@ -85,7 +102,19 @@ export function parseMetadata(parsed: Record<string, unknown>): PageMetadata {
         pageVersion: typeof parsed.pageVersion === 'number' ? parsed.pageVersion
             : typeof parsed.uxVersion === 'number' ? parsed.uxVersion : 0,
         mode: parsed.mode === 'locked' ? 'locked' : 'unlocked',
+        greeting: typeof parsed.greeting === 'string' ? parsed.greeting : '',
+        firstRunGreeting: typeof parsed.firstRunGreeting === 'string' ? parsed.firstRunGreeting : '',
     };
+    if (parsed.sectionModes && typeof parsed.sectionModes === 'object' && !Array.isArray(parsed.sectionModes)) {
+        const out: Record<string, SectionMode> = {};
+        for (const [title, mode] of Object.entries(parsed.sectionModes as Record<string, unknown>)) {
+            if (typeof mode === 'string' && VALID_SECTION_MODES.has(mode as SectionMode)) {
+                out[title] = mode as SectionMode;
+            }
+        }
+        if (Object.keys(out).length > 0) result.sectionModes = out;
+    }
+    return result;
 }
 
 export async function savePageMetadata(config: SynthOSConfig, name: string, metadata: PageMetadata): Promise<void> {
@@ -97,6 +126,7 @@ export async function savePageMetadata(config: SynthOSConfig, name: string, meta
 
 const DEFAULT_METADATA: PageMetadata = {
     title: '',
+    description: '',
     categories: [],
     pinned: false,
     showInAll: true,
@@ -104,6 +134,8 @@ const DEFAULT_METADATA: PageMetadata = {
     lastModified: '',
     pageVersion: 0,
     mode: 'unlocked',
+    greeting: '',
+    firstRunGreeting: '',
 };
 
 export async function listPages(config: SynthOSConfig, fallbackPagesFolders: string[]): Promise<PageInfo[]> {
@@ -142,6 +174,7 @@ export async function listPages(config: SynthOSConfig, fallbackPagesFolders: str
             pageMap.set(name, {
                 name,
                 title,
+                description: '',
                 categories,
                 pinned: false,
                 showInAll: true,
@@ -149,6 +182,8 @@ export async function listPages(config: SynthOSConfig, fallbackPagesFolders: str
                 lastModified: '',
                 pageVersion: 1,
                 mode: 'unlocked',
+                greeting: '',
+                firstRunGreeting: '',
             });
         }
     }
@@ -165,6 +200,7 @@ export async function listPages(config: SynthOSConfig, fallbackPagesFolders: str
             pageMap.set(name, {
                 name,
                 title: metadata?.title ?? '',
+                description: metadata?.description ?? '',
                 categories: metadata?.categories ?? ['System'],
                 pinned: metadata?.pinned ?? true,
                 showInAll: metadata?.showInAll ?? true,
@@ -172,6 +208,8 @@ export async function listPages(config: SynthOSConfig, fallbackPagesFolders: str
                 lastModified: metadata?.lastModified ?? '',
                 pageVersion: metadata?.pageVersion ?? 0,
                 mode: metadata?.mode ?? 'unlocked',
+                greeting: metadata?.greeting ?? '',
+                firstRunGreeting: metadata?.firstRunGreeting ?? '',
             });
         }
     }
@@ -187,11 +225,14 @@ export async function loadPageState(config: SynthOSConfig, name: string): Promis
     const pagesFolder = config.pagesFolder;
     const sp = config.storageProvider;
 
-    // Check for working-state version files first
-    const latestVersion = await getLatestVersion(config, name);
-    if (latestVersion > 0) {
-        const versionHtml = await loadPageVersion(config, name, latestVersion);
-        if (versionHtml) return versionHtml;
+    // Migrate any legacy v-scheme files on first read, then look for the
+    // highest-numbered page.c<N>.html as the active working state.
+    await migrateLegacyChangeFiles(config, name);
+
+    const latestChange = await getLatestChangeHtmlNumber(config, name);
+    if (latestChange > 0) {
+        const html = await loadChangeHtml(config, name, latestChange);
+        if (html) return html;
     }
 
     // Fall back to saved baseline
@@ -225,6 +266,7 @@ export async function savePageState(config: SynthOSConfig, name: string, content
         const now = new Date().toISOString();
         const metadata: PageMetadata = {
             title: title ?? '',
+            description: '',
             categories: categories ?? [],
             pinned: false,
             showInAll: true,
@@ -232,6 +274,8 @@ export async function savePageState(config: SynthOSConfig, name: string, content
             lastModified: now,
             pageVersion: PAGE_VERSION,
             mode: 'unlocked',
+            greeting: '',
+            firstRunGreeting: '',
         };
         await sp.saveFile(metadataPath, JSON.stringify(metadata, null, 4));
     }
@@ -256,61 +300,250 @@ export async function deletePage(config: SynthOSConfig, name: string): Promise<v
 }
 
 // ---------------------------------------------------------------------------
-// Page versioning — per-edit version snapshots for undo support
+// Per-change journal — durable HTML + JSON pairs per user turn
 // ---------------------------------------------------------------------------
+//
+// Every user message creates a new page.c<N>.json (user msg first, assistant
+// reply or error appended). On a successful transform, page.c<N>.html is also
+// written. Errors only append to the current JSON — no HTML is written — so
+// the HTML and JSON sequence numbers may diverge (gaps allowed).
+//
+// Active page = highest N where page.c<N>.html exists (else baseline).
+// Save collapses the chain back to page.html and deletes all c-files.
+
+export interface ChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+
+const CHANGE_HTML_RE = /^page\.c(\d+)\.html$/;
+const CHANGE_JSON_RE = /^page\.c(\d+)\.json$/;
+
+function pageFolderPath(config: SynthOSConfig, name: string): string {
+    return path.join(config.pagesFolder, 'pages', name);
+}
 
 /**
- * Save a version snapshot: <pagesFolder>/pages/<name>/page.v<version>.html
+ * Save the HTML produced by change <n>: page.c<n>.html
  */
-export async function savePageVersion(config: SynthOSConfig, name: string, version: number, html: string): Promise<void> {
+export async function saveChangeHtml(config: SynthOSConfig, name: string, n: number, html: string): Promise<void> {
     const sp = config.storageProvider;
-    const pageFolder = path.join(config.pagesFolder, 'pages', name);
-    await sp.ensureFolderExists(pageFolder);
-    await sp.saveFile(path.join(pageFolder, `page.v${version}.html`), html);
+    const folder = pageFolderPath(config, name);
+    await sp.ensureFolderExists(folder);
+    await sp.saveFile(path.join(folder, `page.c${n}.html`), html);
 }
 
 /**
- * Load a version snapshot (returns undefined if the file doesn't exist).
+ * Load the HTML produced by change <n> (undefined if missing).
  */
-export async function loadPageVersion(config: SynthOSConfig, name: string, version: number): Promise<string | undefined> {
+export async function loadChangeHtml(config: SynthOSConfig, name: string, n: number): Promise<string | undefined> {
     const sp = config.storageProvider;
-    const filePath = path.join(config.pagesFolder, 'pages', name, `page.v${version}.html`);
-    if (!await sp.checkIfExists(filePath)) return undefined;
-    return sp.loadFile(filePath);
+    const file = path.join(pageFolderPath(config, name), `page.c${n}.html`);
+    if (!await sp.checkIfExists(file)) return undefined;
+    return sp.loadFile(file);
 }
 
 /**
- * Scan page.v*.html files and return the highest version number (0 if none).
+ * Highest N such that page.c<N>.html exists (0 if none).
  */
-export async function getLatestVersion(config: SynthOSConfig, name: string): Promise<number> {
+export async function getLatestChangeHtmlNumber(config: SynthOSConfig, name: string): Promise<number> {
+    const nums = await listChangeNumbers(config, name, CHANGE_HTML_RE);
+    return nums.length > 0 ? nums[nums.length - 1] : 0;
+}
+
+/**
+ * Highest N across both .html and .json files (0 if none) — used when
+ * assigning the next change number so errors (JSON only) still advance.
+ */
+export async function getLatestChangeNumber(config: SynthOSConfig, name: string): Promise<number> {
+    const htmlNums = await listChangeNumbers(config, name, CHANGE_HTML_RE);
+    const jsonNums = await listChangeNumbers(config, name, CHANGE_JSON_RE);
+    const all = [...htmlNums, ...jsonNums];
+    return all.length > 0 ? Math.max(...all) : 0;
+}
+
+/**
+ * List all change numbers matching a pattern, sorted ascending.
+ */
+async function listChangeNumbers(config: SynthOSConfig, name: string, pattern: RegExp): Promise<number[]> {
     const sp = config.storageProvider;
-    const pageFolder = path.join(config.pagesFolder, 'pages', name);
-    if (!await sp.checkIfExists(pageFolder)) return 0;
-    const files = await sp.listFiles(pageFolder);
-    let max = 0;
+    const folder = pageFolderPath(config, name);
+    if (!await sp.checkIfExists(folder)) return [];
+    const files = await sp.listFiles(folder);
+    const nums: number[] = [];
     for (const file of files) {
-        const match = file.match(/^page\.v(\d+)\.html$/);
-        if (match) {
-            const v = parseInt(match[1], 10);
-            if (v > max) max = v;
+        const match = file.match(pattern);
+        if (match) nums.push(parseInt(match[1], 10));
+    }
+    nums.sort((a, b) => a - b);
+    return nums;
+}
+
+/**
+ * Save the messages list for change <n>: page.c<n>.json
+ */
+export async function saveChangeMessages(config: SynthOSConfig, name: string, n: number, messages: ChatMessage[]): Promise<void> {
+    const sp = config.storageProvider;
+    const folder = pageFolderPath(config, name);
+    await sp.ensureFolderExists(folder);
+    await sp.saveFile(path.join(folder, `page.c${n}.json`), JSON.stringify({ messages }, null, 2));
+}
+
+/**
+ * Load the messages list for change <n>. Returns [] if the file doesn't
+ * exist or is corrupted.
+ */
+export async function loadChangeMessages(config: SynthOSConfig, name: string, n: number): Promise<ChatMessage[]> {
+    const sp = config.storageProvider;
+    const file = path.join(pageFolderPath(config, name), `page.c${n}.json`);
+    if (!await sp.checkIfExists(file)) return [];
+    try {
+        const raw = await sp.loadFile(file);
+        const parsed = JSON.parse(raw);
+        if (parsed && Array.isArray(parsed.messages)) return parsed.messages;
+        // Legacy shape: top-level array
+        if (Array.isArray(parsed)) return parsed;
+    } catch {
+        // corrupted — fall through
+    }
+    return [];
+}
+
+/**
+ * Append a single message to the current page.c<n>.json (creating it if
+ * missing). Used for errors — always targets the highest existing N, or
+ * creates c1 if none exist.
+ */
+export async function appendMessageToCurrentChange(config: SynthOSConfig, name: string, message: ChatMessage): Promise<number> {
+    let n = await getLatestChangeNumber(config, name);
+    if (n === 0) n = 1;
+    const existing = await loadChangeMessages(config, name, n);
+    existing.push(message);
+    await saveChangeMessages(config, name, n, existing);
+    return n;
+}
+
+/**
+ * Flat concat of all page.c<n>.json messages in numeric order.
+ */
+export async function loadAllChangeMessages(config: SynthOSConfig, name: string): Promise<ChatMessage[]> {
+    const nums = await listChangeNumbers(config, name, CHANGE_JSON_RE);
+    const out: ChatMessage[] = [];
+    for (const n of nums) {
+        const msgs = await loadChangeMessages(config, name, n);
+        out.push(...msgs);
+    }
+    return out;
+}
+
+/**
+ * Delete a single change's html + json pair (either may be missing).
+ */
+export async function deleteChange(config: SynthOSConfig, name: string, n: number): Promise<void> {
+    const sp = config.storageProvider;
+    const folder = pageFolderPath(config, name);
+    const html = path.join(folder, `page.c${n}.html`);
+    const json = path.join(folder, `page.c${n}.json`);
+    if (await sp.checkIfExists(html)) await sp.deleteFile(html);
+    if (await sp.checkIfExists(json)) await sp.deleteFile(json);
+}
+
+/**
+ * Delete all page.c*.html and page.c*.json files for a page.
+ */
+export async function clearChanges(config: SynthOSConfig, name: string): Promise<void> {
+    const sp = config.storageProvider;
+    const folder = pageFolderPath(config, name);
+    if (!await sp.checkIfExists(folder)) return;
+    const files = await sp.listFiles(folder);
+    for (const file of files) {
+        if (CHANGE_HTML_RE.test(file) || CHANGE_JSON_RE.test(file)) {
+            await sp.deleteFile(path.join(folder, file));
         }
     }
-    return max;
 }
 
 /**
- * Delete all page.v*.html version files for a page.
+ * One-shot lazy migration: on first touch of a page, rename any
+ * legacy page.v<N>.html to page.c<N>.html and split any legacy
+ * chat-history.json into page.c<N>.json files grouped by user turn.
+ * Idempotent — does nothing if no legacy files remain.
  */
-export async function clearVersions(config: SynthOSConfig, name: string): Promise<void> {
+export async function migrateLegacyChangeFiles(config: SynthOSConfig, name: string): Promise<void> {
     const sp = config.storageProvider;
-    const pageFolder = path.join(config.pagesFolder, 'pages', name);
-    if (!await sp.checkIfExists(pageFolder)) return;
-    const files = await sp.listFiles(pageFolder);
+    const folder = pageFolderPath(config, name);
+    if (!await sp.checkIfExists(folder)) return;
+
+    const files = await sp.listFiles(folder);
+
+    // 1. Rename page.v<N>.html → page.c<N>.html if target doesn't already exist.
     for (const file of files) {
-        if (/^page\.v\d+\.html$/.test(file)) {
-            await sp.deleteFile(path.join(pageFolder, file));
+        const match = file.match(/^page\.v(\d+)\.html$/);
+        if (!match) continue;
+        const n = match[1];
+        const src = path.join(folder, file);
+        const dst = path.join(folder, `page.c${n}.html`);
+        if (await sp.checkIfExists(dst)) {
+            // c-file already present — drop the legacy v copy to avoid dual state
+            await sp.deleteFile(src);
+            continue;
         }
+        const html = await sp.loadFile(src);
+        await sp.saveFile(dst, html);
+        await sp.deleteFile(src);
     }
+
+    // 2. Split legacy chat-history.json into per-turn page.c<N>.json files,
+    //    but only if no page.c*.json files already exist (avoid clobbering).
+    const chatHistoryPath = path.join(folder, 'chat-history.json');
+    if (!await sp.checkIfExists(chatHistoryPath)) return;
+
+    const existingJson = files.some(f => CHANGE_JSON_RE.test(f));
+    if (existingJson) {
+        // Already migrated or mid-flight — drop the legacy file to converge.
+        await sp.deleteFile(chatHistoryPath);
+        return;
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(await sp.loadFile(chatHistoryPath));
+    } catch {
+        await sp.deleteFile(chatHistoryPath);
+        return;
+    }
+    if (!Array.isArray(parsed)) {
+        await sp.deleteFile(chatHistoryPath);
+        return;
+    }
+
+    // Group messages by user turn. The legacy file starts with a greeting
+    // (assistant) followed by user/assistant pairs. Drop the leading greeting
+    // (shell rebuilds it from metadata), then chunk on every user message.
+    const msgs = parsed as ChatMessage[];
+    const groups: ChatMessage[][] = [];
+    let current: ChatMessage[] = [];
+    let sawFirstUser = false;
+    for (const m of msgs) {
+        if (!m || typeof m.role !== 'string' || typeof m.content !== 'string') continue;
+        if (m.role === 'user') {
+            if (current.length > 0) groups.push(current);
+            current = [m];
+            sawFirstUser = true;
+        } else if (sawFirstUser) {
+            current.push(m);
+        }
+        // assistant messages before the first user msg (greeting) are skipped
+    }
+    if (current.length > 0) groups.push(current);
+
+    for (let i = 0; i < groups.length; i++) {
+        const n = i + 1;
+        const target = path.join(folder, `page.c${n}.json`);
+        await sp.saveFile(target, JSON.stringify({ messages: groups[i] }, null, 2));
+    }
+
+    await sp.deleteFile(chatHistoryPath);
 }
 
 export interface CopyPageOptions {
@@ -375,6 +608,7 @@ export async function copyPage(
     const now = new Date().toISOString();
     const metadata: PageMetadata = {
         title,
+        description: '',
         categories,
         pinned: false,
         showInAll: true,
@@ -382,6 +616,8 @@ export async function copyPage(
         lastModified: now,
         pageVersion: PAGE_VERSION,
         mode: 'unlocked',
+        greeting: '',
+        firstRunGreeting: '',
     };
     await savePageMetadata(config, targetName, metadata);
 

package/src/service/createCompletePrompt.ts

@@ -8,6 +8,12 @@ export async function createCompletePrompt(config: SynthOSConfig, use: 'builder'
     const settings = await loadSettings(config);
     const entry = getModelEntry(settings, use);
 
+    // ClaudeCode provider uses its own CLI subprocess — no API key or completePrompt needed.
+    // Return a no-op stub; the ClaudeCode builder ignores it entirely.
+    if (entry.provider === 'ClaudeCode') {
+        return async () => ({ completed: false, error: new Error('ClaudeCode provider does not use completePrompt') });
+    }
+
     if (!entry.configuration.apiKey) {
         throw new Error('API key not configured');
     }

package/src/service/mediaCache.ts

@@ -0,0 +1,206 @@
+import { createHash } from 'crypto';
+import path from 'path';
+import { StorageProvider } from '../storage/StorageProvider';
+
+export interface MediaCacheOptions {
+    storage: StorageProvider;
+    cacheRoot: string;
+}
+
+export interface CacheEntry {
+    hit: true;
+    buffer: Buffer;
+    contentType: string;
+}
+
+export interface CacheMiss {
+    hit: false;
+}
+
+export type CacheLookup = CacheEntry | CacheMiss;
+
+export interface CacheStats {
+    images: { count: number; totalBytes: number };
+    audio: { count: number; totalBytes: number };
+}
+
+function hashKey(key: string): string {
+    return createHash('sha256').update(key).digest('hex');
+}
+
+const MAX_ENTRIES = 500;
+const CATEGORIES = ['images', 'audio'] as const;
+
+export function createMediaCache(options: MediaCacheOptions) {
+    const { storage, cacheRoot } = options;
+
+    function categoryDir(category: string): string {
+        return path.join(cacheRoot, category);
+    }
+
+    async function ensureCategory(category: string): Promise<void> {
+        await storage.ensureFolderExists(categoryDir(category));
+    }
+
+    async function get(category: string, key: string): Promise<CacheLookup> {
+        const hash = hashKey(key);
+        const dir = categoryDir(category);
+        const metaPath = path.join(dir, `${hash}.meta.json`);
+
+        if (!(await storage.checkIfExists(metaPath))) {
+            return { hit: false };
+        }
+
+        const meta = JSON.parse(await storage.loadFile(metaPath));
+        const dataPath = path.join(dir, `${hash}${meta.extension}`);
+        try {
+            const buffer = await storage.loadBuffer(dataPath);
+
+            // Update last access time for eviction tracking
+            meta.lastAccessedAt = new Date().toISOString();
+            await storage.saveFile(metaPath, JSON.stringify(meta, null, 2));
+
+            return { hit: true, buffer, contentType: meta.contentType };
+        } catch {
+            return { hit: false };
+        }
+    }
+
+    async function put(
+        category: string,
+        key: string,
+        data: Buffer,
+        contentType: string,
+        meta: Record<string, unknown>
+    ): Promise<void> {
+        await ensureCategory(category);
+        const hash = hashKey(key);
+        const dir = categoryDir(category);
+        const extension = extensionForContentType(contentType);
+        const dataPath = path.join(dir, `${hash}${extension}`);
+        const metaPath = path.join(dir, `${hash}.meta.json`);
+
+        const now = new Date().toISOString();
+        await storage.saveBuffer(dataPath, data);
+        await storage.saveFile(metaPath, JSON.stringify({
+            ...meta,
+            contentType,
+            extension,
+            createdAt: now,
+            lastAccessedAt: now,
+        }, null, 2));
+
+        // Run eviction after writing the new entry
+        await evict();
+    }
+
+    async function evict(): Promise<void> {
+        // Collect all entries across categories
+        const entries: { category: string; hash: string; lastAccessedAt: string; size: number; metaPath: string; extension: string }[] = [];
+
+        for (const category of CATEGORIES) {
+            const dir = categoryDir(category);
+            if (!(await storage.checkIfExists(dir))) continue;
+
+            const files = await storage.listFiles(dir);
+            for (const file of files) {
+                if (!file.endsWith('.meta.json')) continue;
+                const metaPath = path.join(dir, file);
+                try {
+                    const meta = JSON.parse(await storage.loadFile(metaPath));
+                    const hash = file.replace('.meta.json', '');
+                    const dataPath = path.join(dir, `${hash}${meta.extension}`);
+                    let size = 0;
+                    try {
+                        const info = await storage.stat(dataPath);
+                        size = info.size;
+                    } catch { /* data file missing, size stays 0 */ }
+                    entries.push({
+                        category,
+                        hash,
+                        lastAccessedAt: meta.lastAccessedAt || meta.createdAt || '1970-01-01T00:00:00.000Z',
+                        size,
+                        metaPath,
+                        extension: meta.extension,
+                    });
+                } catch { /* skip unreadable meta */ }
+            }
+        }
+
+        if (entries.length <= MAX_ENTRIES) return;
+
+        // Sort by lastAccessedAt descending — most recent first
+        entries.sort((a, b) => b.lastAccessedAt.localeCompare(a.lastAccessedAt));
+
+        // Evict everything beyond the first 500
+        const toEvict = entries.slice(MAX_ENTRIES);
+        for (const entry of toEvict) {
+            const dir = categoryDir(entry.category);
+            const dataPath = path.join(dir, `${entry.hash}${entry.extension}`);
+            try { await storage.deleteFile(dataPath); } catch { /* ignore */ }
+            try { await storage.deleteFile(entry.metaPath); } catch { /* ignore */ }
+        }
+    }
+
+    async function invalidate(category: string, key: string): Promise<void> {
+        const hash = hashKey(key);
+        const dir = categoryDir(category);
+        const metaPath = path.join(dir, `${hash}.meta.json`);
+
+        if (await storage.checkIfExists(metaPath)) {
+            const meta = JSON.parse(await storage.loadFile(metaPath));
+            const dataPath = path.join(dir, `${hash}${meta.extension}`);
+            try { await storage.deleteFile(dataPath); } catch { /* ignore */ }
+            try { await storage.deleteFile(metaPath); } catch { /* ignore */ }
+        }
+    }
+
+    async function clearCategory(category: string): Promise<void> {
+        const dir = categoryDir(category);
+        if (await storage.checkIfExists(dir)) {
+            await storage.deleteFolder(dir);
+        }
+    }
+
+    async function clearAll(): Promise<void> {
+        await clearCategory('images');
+        await clearCategory('audio');
+    }
+
+    async function stats(): Promise<CacheStats> {
+        const result: CacheStats = {
+            images: { count: 0, totalBytes: 0 },
+            audio: { count: 0, totalBytes: 0 },
+        };
+
+        for (const category of CATEGORIES) {
+            const dir = categoryDir(category);
+            if (!(await storage.checkIfExists(dir))) continue;
+            const files = await storage.listFiles(dir);
+            for (const file of files) {
+                if (file.endsWith('.meta.json')) continue;
+                try {
+                    const info = await storage.stat(path.join(dir, file));
+                    result[category].count++;
+                    result[category].totalBytes += info.size;
+                } catch { /* skip missing */ }
+            }
+        }
+
+        return result;
+    }
+
+    return { get, put, invalidate, clearCategory, clearAll, stats, evict };
+}
+
+function extensionForContentType(contentType: string): string {
+    if (contentType.includes('png')) return '.png';
+    if (contentType.includes('jpeg') || contentType.includes('jpg')) return '.jpg';
+    if (contentType.includes('webp')) return '.webp';
+    if (contentType.includes('mpeg') || contentType.includes('mp3')) return '.mp3';
+    if (contentType.includes('wav')) return '.wav';
+    if (contentType.includes('ogg')) return '.ogg';
+    return '.bin';
+}
+
+export type MediaCache = ReturnType<typeof createMediaCache>;