@mariozechner/pi-web-ui 0.5.44 → 0.5.45

package/src/index.ts

@@ -1,15 +1,33 @@
 // Main chat interface
-export { ChatPanel } from "./ChatPanel.js";
 
+export type { AgentState, ThinkingLevel } from "./agent/agent.js";
+// State management
+export { Agent } from "./agent/agent.js";
+// Transports
+export { AppTransport } from "./agent/transports/AppTransport.js";
+export { ProviderTransport } from "./agent/transports/ProviderTransport.js";
+export type { ProxyAssistantMessageEvent } from "./agent/transports/proxy-types.js";
+export type { AgentRunConfig, AgentTransport } from "./agent/transports/types.js";
+export { ChatPanel } from "./ChatPanel.js";
 // Components
 export { AgentInterface } from "./components/AgentInterface.js";
 export { AttachmentTile } from "./components/AttachmentTile.js";
 export { ConsoleBlock } from "./components/ConsoleBlock.js";
+export { ExpandableSection } from "./components/ExpandableSection.js";
 export { Input } from "./components/Input.js";
 export { MessageEditor } from "./components/MessageEditor.js";
 export { MessageList } from "./components/MessageList.js";
 // Message components
+export type { AppMessage, CustomMessages, UserMessageWithAttachments } from "./components/Messages.js";
 export { AssistantMessage, ToolMessage, UserMessage } from "./components/Messages.js";
+// Message renderer registry
+export {
+	getMessageRenderer,
+	type MessageRenderer,
+	type MessageRole,
+	registerMessageRenderer,
+	renderMessage,
+} from "./components/message-renderer-registry.js";
 export {
 	type SandboxFile,
 	SandboxIframe,
@@ -17,47 +35,70 @@ export {
 	type SandboxUrlProvider,
 } from "./components/SandboxedIframe.js";
 export { StreamingMessageContainer } from "./components/StreamingMessageContainer.js";
+// Sandbox Runtime Providers
+export { ArtifactsRuntimeProvider } from "./components/sandbox/ArtifactsRuntimeProvider.js";
+export { AttachmentsRuntimeProvider } from "./components/sandbox/AttachmentsRuntimeProvider.js";
+export { type ConsoleLog, ConsoleRuntimeProvider } from "./components/sandbox/ConsoleRuntimeProvider.js";
+export {
+	type DownloadableFile,
+	FileDownloadRuntimeProvider,
+} from "./components/sandbox/FileDownloadRuntimeProvider.js";
+export { RuntimeMessageBridge } from "./components/sandbox/RuntimeMessageBridge.js";
+export { RUNTIME_MESSAGE_ROUTER } from "./components/sandbox/RuntimeMessageRouter.js";
+export type { SandboxRuntimeProvider } from "./components/sandbox/SandboxRuntimeProvider.js";
 export { ApiKeyPromptDialog } from "./dialogs/ApiKeyPromptDialog.js";
 export { AttachmentOverlay } from "./dialogs/AttachmentOverlay.js";
 // Dialogs
 export { ModelSelector } from "./dialogs/ModelSelector.js";
+export { PersistentStorageDialog } from "./dialogs/PersistentStorageDialog.js";
+export { SessionListDialog } from "./dialogs/SessionListDialog.js";
 export { ApiKeysTab, ProxyTab, SettingsDialog, SettingsTab } from "./dialogs/SettingsDialog.js";
-export type { AgentSessionState, ThinkingLevel } from "./state/agent-session.js";
-// State management
-export { AgentSession } from "./state/agent-session.js";
-
-// Transports
-export { AppTransport } from "./state/transports/AppTransport.js";
-export { ProviderTransport } from "./state/transports/ProviderTransport.js";
-export type { ProxyAssistantMessageEvent } from "./state/transports/proxy-types.js";
-export type { AgentRunConfig, AgentTransport } from "./state/transports/types.js";
+// Prompts
+export {
+	ARTIFACTS_RUNTIME_PROVIDER_DESCRIPTION_RO,
+	ARTIFACTS_RUNTIME_PROVIDER_DESCRIPTION_RW,
+	ATTACHMENTS_RUNTIME_DESCRIPTION,
+} from "./prompts/prompts.js";
 // Storage
-export { AppStorage, getAppStorage, initAppStorage, setAppStorage } from "./storage/app-storage.js";
-export { ChromeStorageBackend } from "./storage/backends/chrome-storage-backend.js";
-export { IndexedDBBackend } from "./storage/backends/indexeddb-backend.js";
-export { LocalStorageBackend } from "./storage/backends/local-storage-backend.js";
-export { ProviderKeysRepository } from "./storage/repositories/provider-keys-repository.js";
-export { SettingsRepository } from "./storage/repositories/settings-repository.js";
-export type { AppStorageConfig, StorageBackend } from "./storage/types.js";
+export { AppStorage, getAppStorage, setAppStorage } from "./storage/app-storage.js";
+export { IndexedDBStorageBackend } from "./storage/backends/indexeddb-storage-backend.js";
+export { Store } from "./storage/store.js";
+export { ProviderKeysStore } from "./storage/stores/provider-keys-store.js";
+export { SessionsStore } from "./storage/stores/sessions-store.js";
+export { SettingsStore } from "./storage/stores/settings-store.js";
+export type {
+	IndexConfig,
+	IndexedDBConfig,
+	SessionData,
+	SessionMetadata,
+	StorageBackend,
+	StorageTransaction,
+	StoreConfig,
+} from "./storage/types.js";
 // Artifacts
 export { ArtifactElement } from "./tools/artifacts/ArtifactElement.js";
+export { ArtifactPill } from "./tools/artifacts/ArtifactPill.js";
 export { type Artifact, ArtifactsPanel, type ArtifactsParams } from "./tools/artifacts/artifacts.js";
+export { ArtifactsToolRenderer } from "./tools/artifacts/artifacts-tool-renderer.js";
 export { HtmlArtifact } from "./tools/artifacts/HtmlArtifact.js";
+export { ImageArtifact } from "./tools/artifacts/ImageArtifact.js";
 export { MarkdownArtifact } from "./tools/artifacts/MarkdownArtifact.js";
 export { SvgArtifact } from "./tools/artifacts/SvgArtifact.js";
 export { TextArtifact } from "./tools/artifacts/TextArtifact.js";
+export { createExtractDocumentTool, extractDocumentTool } from "./tools/extract-document.js";
 // Tools
-export { getToolRenderer, registerToolRenderer, renderToolParams, renderToolResult } from "./tools/index.js";
+export { getToolRenderer, registerToolRenderer, renderTool, setShowJsonMode } from "./tools/index.js";
 export { createJavaScriptReplTool, javascriptReplTool } from "./tools/javascript-repl.js";
+export { renderCollapsibleHeader, renderHeader } from "./tools/renderer-registry.js";
 export { BashRenderer } from "./tools/renderers/BashRenderer.js";
 export { CalculateRenderer } from "./tools/renderers/CalculateRenderer.js";
 // Tool renderers
 export { DefaultRenderer } from "./tools/renderers/DefaultRenderer.js";
 export { GetCurrentTimeRenderer } from "./tools/renderers/GetCurrentTimeRenderer.js";
-export type { ToolRenderer } from "./tools/types.js";
+export type { ToolRenderer, ToolRenderResult } from "./tools/types.js";
 export type { Attachment } from "./utils/attachment-utils.js";
 // Utils
 export { loadAttachment } from "./utils/attachment-utils.js";
 export { clearAuthToken, getAuthToken } from "./utils/auth-token.js";
 export { formatCost, formatModelCost, formatTokenCount, formatUsage } from "./utils/format.js";
-export { i18n, setLanguage } from "./utils/i18n.js";
+export { i18n, setLanguage, translations } from "./utils/i18n.js";

package/src/prompts/prompts.ts

@@ -0,0 +1,282 @@
+/**
+ * Centralized tool prompts/descriptions.
+ * Each prompt is either a string constant or a template function.
+ */
+
+// ============================================================================
+// JavaScript REPL Tool
+// ============================================================================
+
+export const JAVASCRIPT_REPL_TOOL_DESCRIPTION = (runtimeProviderDescriptions: string[]) => `# JavaScript REPL
+
+## Purpose
+Execute JavaScript code in a sandboxed browser environment with full Web APIs.
+
+## When to Use
+- Quick calculations or data transformations
+- Testing JavaScript code snippets in isolation
+- Processing data with libraries (XLSX, CSV, etc.)
+- Creating artifacts from data
+
+## Environment
+- ES2023+ JavaScript (async/await, optional chaining, nullish coalescing, etc.)
+- All browser APIs: DOM, Canvas, WebGL, Fetch, Web Workers, WebSockets, Crypto, etc.
+- Import any npm package: await import('https://esm.run/package-name')
+
+## Common Libraries
+- XLSX: const XLSX = await import('https://esm.run/xlsx');
+- CSV: const Papa = (await import('https://esm.run/papaparse')).default;
+- Chart.js: const Chart = (await import('https://esm.run/chart.js/auto')).default;
+- Three.js: const THREE = await import('https://esm.run/three');
+
+## Persistence between tool calls
+- Objects stored on global scope do not persist between calls.
+- Use artifacts as a key-value JSON object store:
+  - Use createOrUpdateArtifact(filename, content) to persist data between calls. JSON objects are auto-stringified.
+  - Use listArtifacts() and getArtifact(filename) to read persisted data. JSON files are auto-parsed to objects.
+  - Prefer to use a single artifact throughout the session to store intermediate data (e.g. 'data.json').
+
+## Input
+- You have access to the user's attachments via listAttachments(), readTextAttachment(id), and readBinaryAttachment(id)
+- You have access to previously created artifacts via listArtifacts() and getArtifact(filename)
+
+## Output
+- All console.log() calls are captured for you to inspect. The user does not see these logs.
+- Create artifacts for file results (images, JSON, CSV, etc.) which persiste throughout the
+  session and are accessible to you and the user.
+
+## Example
+const data = [10, 20, 15, 25];
+const sum = data.reduce((a, b) => a + b, 0);
+const avg = sum / data.length;
+console.log('Sum:', sum, 'Average:', avg);
+
+## Important Notes
+- Graphics: Use fixed dimensions (800x600), NOT window.innerWidth/Height
+- Chart.js: Set options: { responsive: false, animation: false }
+- Three.js: renderer.setSize(800, 600) with matching aspect ratio
+
+## Helper Functions (Automatically Available)
+
+These functions are injected into the execution environment and available globally:
+
+${runtimeProviderDescriptions.join("\n\n")}
+`;
+
+// ============================================================================
+// Artifacts Tool
+// ============================================================================
+
+export const ARTIFACTS_TOOL_DESCRIPTION = (runtimeProviderDescriptions: string[]) => `# Artifacts
+
+Create and manage persistent files that live alongside the conversation.
+
+## When to Use - Artifacts Tool vs REPL
+
+**Use artifacts tool when YOU are the author:**
+- Writing research summaries, analysis, ideas, documentation
+- Creating markdown notes for user to read
+- Building HTML applications/visualizations that present data
+- Creating HTML artifacts that render charts from programmatically generated data
+
+**Use repl + artifact storage functions when CODE processes data:**
+- Scraping workflows that extract and store data
+- Processing CSV/Excel files programmatically
+- Data transformation pipelines
+- Binary file generation requiring libraries (PDF, DOCX)
+
+**Pattern: REPL generates data → Artifacts tool creates HTML that visualizes it**
+Example: repl scrapes products → stores products.json → you author dashboard.html that reads products.json and renders Chart.js visualizations
+
+## Input
+- { action: "create", filename: "notes.md", content: "..." } - Create new file
+- { action: "update", filename: "notes.md", old_str: "...", new_str: "..." } - Update part of file (PREFERRED)
+- { action: "rewrite", filename: "notes.md", content: "..." } - Replace entire file (LAST RESORT)
+- { action: "get", filename: "data.json" } - Retrieve file content
+- { action: "delete", filename: "old.csv" } - Delete file
+- { action: "htmlArtifactLogs", filename: "app.html" } - Get console logs from HTML artifact
+
+## Returns
+Depends on action:
+- create/update/rewrite/delete: Success status or error
+- get: File content
+- htmlArtifactLogs: Console logs and errors
+
+## Supported File Types
+✅ Text-based files you author: .md, .txt, .html, .js, .css, .json, .csv, .svg
+❌ Binary files requiring libraries (use repl): .pdf, .docx
+
+## Critical - Prefer Update Over Rewrite
+❌ NEVER: get entire file + rewrite to change small sections
+✅ ALWAYS: update for targeted edits (token efficient)
+✅ Ask: Can I describe the change as old_str → new_str? Use update.
+
+---
+
+## HTML Artifacts
+
+Interactive HTML applications that can visualize data from other artifacts.
+
+### Data Access
+- Can read artifacts created by repl and user attachments
+- Use to build dashboards, visualizations, interactive tools
+- See Helper Functions section below for available functions
+
+### Requirements
+- Self-contained single file
+- Import ES modules from esm.sh: <script type="module">import X from 'https://esm.sh/pkg';</script>
+- Use Tailwind CDN: <script src="https://cdn.tailwindcss.com"></script>
+- Can embed images from any domain: <img src="https://example.com/image.jpg">
+- MUST set background color explicitly (avoid transparent)
+- Inline CSS or Tailwind utility classes
+- No localStorage/sessionStorage
+
+### Styling
+- Use Tailwind utility classes for clean, functional designs
+- Ensure responsive layout (iframe may be resized)
+- Avoid purple gradients, AI aesthetic clichés, and emojis
+
+### Helper Functions (Automatically Available)
+
+These functions are injected into HTML artifact sandbox:
+
+${runtimeProviderDescriptions.join("\n\n")}
+`;
+
+// ============================================================================
+// Artifacts Runtime Provider
+// ============================================================================
+
+export const ARTIFACTS_RUNTIME_PROVIDER_DESCRIPTION_RW = `
+### Artifacts Storage
+
+Create, read, update, and delete files in artifacts storage.
+
+#### When to Use
+- Store intermediate results between tool calls
+- Save generated files (images, CSVs, processed data) for user to view and download
+
+#### Do NOT Use For
+- Content you author directly, like summaries of content you read (use artifacts tool instead)
+
+#### Functions
+- listArtifacts() - List all artifact filenames, returns Promise<string[]>
+- getArtifact(filename) - Read artifact content, returns Promise<string | object>. JSON files auto-parse to objects, binary files return base64 string
+- createOrUpdateArtifact(filename, content, mimeType?) - Create or update artifact, returns Promise<void>. JSON files auto-stringify objects, binary requires base64 string with mimeType
+- deleteArtifact(filename) - Delete artifact, returns Promise<void>
+
+#### Example
+JSON workflow:
+\`\`\`javascript
+// Fetch and save
+const response = await fetch('https://api.example.com/products');
+const products = await response.json();
+await createOrUpdateArtifact('products.json', products);
+
+// Later: read and filter
+const all = await getArtifact('products.json');
+const cheap = all.filter(p => p.price < 100);
+await createOrUpdateArtifact('cheap.json', cheap);
+\`\`\`
+
+Binary file (image):
+\`\`\`javascript
+const canvas = document.createElement('canvas');
+canvas.width = 800; canvas.height = 600;
+const ctx = canvas.getContext('2d');
+ctx.fillStyle = 'blue';
+ctx.fillRect(0, 0, 800, 600);
+// Remove data:image/png;base64, prefix
+const base64 = canvas.toDataURL().split(',')[1];
+await createOrUpdateArtifact('chart.png', base64, 'image/png');
+\`\`\`
+`;
+
+export const ARTIFACTS_RUNTIME_PROVIDER_DESCRIPTION_RO = `
+### Artifacts Storage
+
+Read files from artifacts storage.
+
+#### When to Use
+- Read artifacts created by REPL or artifacts tool
+- Access data from other HTML artifacts
+- Load configuration or data files
+
+#### Do NOT Use For
+- Creating new artifacts (not available in HTML artifacts)
+- Modifying artifacts (read-only access)
+
+#### Functions
+- listArtifacts() - List all artifact filenames, returns Promise<string[]>
+- getArtifact(filename) - Read artifact content, returns Promise<string | object>. JSON files auto-parse to objects, binary files return base64 string
+
+#### Example
+JSON data:
+\`\`\`javascript
+const products = await getArtifact('products.json');
+const html = products.map(p => \`<div>\${p.name}: $\${p.price}</div>\`).join('');
+document.body.innerHTML = html;
+\`\`\`
+
+Binary image:
+\`\`\`javascript
+const base64 = await getArtifact('chart.png');
+const img = document.createElement('img');
+img.src = 'data:image/png;base64,' + base64;
+document.body.appendChild(img);
+\`\`\`
+`;
+
+// ============================================================================
+// Attachments Runtime Provider
+// ============================================================================
+
+export const ATTACHMENTS_RUNTIME_DESCRIPTION = `
+### User Attachments
+
+Read files the user uploaded to the conversation.
+
+#### When to Use
+- Process user-uploaded files (CSV, JSON, Excel, images, PDFs)
+
+#### Functions
+- listAttachments() - List all attachments, returns array of {id, fileName, mimeType, size}
+- readTextAttachment(id) - Read attachment as text, returns string
+- readBinaryAttachment(id) - Read attachment as binary data, returns Uint8Array
+
+#### Example
+CSV file:
+\`\`\`javascript
+const files = listAttachments();
+const csvFile = files.find(f => f.fileName.endsWith('.csv'));
+const csvData = readTextAttachment(csvFile.id);
+const rows = csvData.split('\\n').map(row => row.split(','));
+\`\`\`
+
+Excel file:
+\`\`\`javascript
+const XLSX = await import('https://esm.run/xlsx');
+const files = listAttachments();
+const xlsxFile = files.find(f => f.fileName.endsWith('.xlsx'));
+const bytes = readBinaryAttachment(xlsxFile.id);
+const workbook = XLSX.read(bytes);
+const data = XLSX.utils.sheet_to_json(workbook.Sheets[workbook.SheetNames[0]]);
+\`\`\`
+`;
+
+// ============================================================================
+// Extract Document Tool
+// ============================================================================
+
+export const EXTRACT_DOCUMENT_DESCRIPTION = `# Extract Document
+
+Extract plain text from documents on the web (PDF, DOCX, XLSX, PPTX).
+
+## When to Use
+User wants you to read a document at a URL.
+
+## Input
+- { url: "https://example.com/document.pdf" } - URL to PDF, DOCX, XLSX, or PPTX
+
+## Returns
+Structured plain text with page/sheet/slide delimiters.`;

package/src/storage/app-storage.ts

@@ -1,23 +1,36 @@
-import { LocalStorageBackend } from "./backends/local-storage-backend.js";
-import { ProviderKeysRepository } from "./repositories/provider-keys-repository.js";
-import { SettingsRepository } from "./repositories/settings-repository.js";
-import type { AppStorageConfig } from "./types.js";
+import type { ProviderKeysStore } from "./stores/provider-keys-store.js";
+import type { SessionsStore } from "./stores/sessions-store.js";
+import type { SettingsStore } from "./stores/settings-store.js";
+import type { StorageBackend } from "./types.js";
 
 /**
- * High-level storage API aggregating all repositories.
- * Apps configure backends and use repositories through this interface.
+ * High-level storage API providing access to all storage operations.
+ * Subclasses can extend this to add domain-specific stores.
  */
 export class AppStorage {
-	readonly settings: SettingsRepository;
-	readonly providerKeys: ProviderKeysRepository;
+	readonly backend: StorageBackend;
+	readonly settings: SettingsStore;
+	readonly providerKeys: ProviderKeysStore;
+	readonly sessions: SessionsStore;
 
-	constructor(config: AppStorageConfig = {}) {
-		// Use LocalStorage with prefixes as defaults
-		const settingsBackend = config.settings ?? new LocalStorageBackend("settings");
-		const providerKeysBackend = config.providerKeys ?? new LocalStorageBackend("providerKeys");
+	constructor(
+		settings: SettingsStore,
+		providerKeys: ProviderKeysStore,
+		sessions: SessionsStore,
+		backend: StorageBackend,
+	) {
+		this.settings = settings;
+		this.providerKeys = providerKeys;
+		this.sessions = sessions;
+		this.backend = backend;
+	}
+
+	async getQuotaInfo(): Promise<{ usage: number; quota: number; percent: number }> {
+		return this.backend.getQuotaInfo();
+	}
 
-		this.settings = new SettingsRepository(settingsBackend);
-		this.providerKeys = new ProviderKeysRepository(providerKeysBackend);
+	async requestPersistence(): Promise<boolean> {
+		return this.backend.requestPersistence();
 	}
 }
 
@@ -41,13 +54,3 @@ export function getAppStorage(): AppStorage {
 export function setAppStorage(storage: AppStorage): void {
 	globalAppStorage = storage;
 }
-
-/**
- * Initialize AppStorage with default configuration if not already set.
- */
-export function initAppStorage(config: AppStorageConfig = {}): AppStorage {
-	if (!globalAppStorage) {
-		globalAppStorage = new AppStorage(config);
-	}
-	return globalAppStorage;
-}

package/src/storage/backends/indexeddb-storage-backend.ts

@@ -0,0 +1,193 @@
+import type { IndexedDBConfig, StorageBackend, StorageTransaction } from "../types.js";
+
+/**
+ * IndexedDB implementation of StorageBackend.
+ * Provides multi-store key-value storage with transactions and quota management.
+ */
+export class IndexedDBStorageBackend implements StorageBackend {
+	private dbPromise: Promise<IDBDatabase> | null = null;
+
+	constructor(private config: IndexedDBConfig) {}
+
+	private async getDB(): Promise<IDBDatabase> {
+		if (!this.dbPromise) {
+			this.dbPromise = new Promise((resolve, reject) => {
+				const request = indexedDB.open(this.config.dbName, this.config.version);
+
+				request.onerror = () => reject(request.error);
+				request.onsuccess = () => resolve(request.result);
+
+				request.onupgradeneeded = (_event) => {
+					const db = request.result;
+
+					// Create object stores from config
+					for (const storeConfig of this.config.stores) {
+						if (!db.objectStoreNames.contains(storeConfig.name)) {
+							const store = db.createObjectStore(storeConfig.name, {
+								keyPath: storeConfig.keyPath,
+								autoIncrement: storeConfig.autoIncrement,
+							});
+
+							// Create indices
+							if (storeConfig.indices) {
+								for (const indexConfig of storeConfig.indices) {
+									store.createIndex(indexConfig.name, indexConfig.keyPath, {
+										unique: indexConfig.unique,
+									});
+								}
+							}
+						}
+					}
+				};
+			});
+		}
+
+		return this.dbPromise;
+	}
+
+	private promisifyRequest<T>(request: IDBRequest<T>): Promise<T> {
+		return new Promise((resolve, reject) => {
+			request.onsuccess = () => resolve(request.result);
+			request.onerror = () => reject(request.error);
+		});
+	}
+
+	async get<T = unknown>(storeName: string, key: string): Promise<T | null> {
+		const db = await this.getDB();
+		const tx = db.transaction(storeName, "readonly");
+		const store = tx.objectStore(storeName);
+		const result = await this.promisifyRequest(store.get(key));
+		return result ?? null;
+	}
+
+	async set<T = unknown>(storeName: string, key: string, value: T): Promise<void> {
+		const db = await this.getDB();
+		const tx = db.transaction(storeName, "readwrite");
+		const store = tx.objectStore(storeName);
+		// If store has keyPath, only pass value (in-line key)
+		// Otherwise pass both value and key (out-of-line key)
+		if (store.keyPath) {
+			await this.promisifyRequest(store.put(value));
+		} else {
+			await this.promisifyRequest(store.put(value, key));
+		}
+	}
+
+	async delete(storeName: string, key: string): Promise<void> {
+		const db = await this.getDB();
+		const tx = db.transaction(storeName, "readwrite");
+		const store = tx.objectStore(storeName);
+		await this.promisifyRequest(store.delete(key));
+	}
+
+	async keys(storeName: string, prefix?: string): Promise<string[]> {
+		const db = await this.getDB();
+		const tx = db.transaction(storeName, "readonly");
+		const store = tx.objectStore(storeName);
+
+		if (prefix) {
+			// Use IDBKeyRange for efficient prefix filtering
+			const range = IDBKeyRange.bound(prefix, prefix + "\uffff", false, false);
+			const keys = await this.promisifyRequest(store.getAllKeys(range));
+			return keys.map((k) => String(k));
+		} else {
+			const keys = await this.promisifyRequest(store.getAllKeys());
+			return keys.map((k) => String(k));
+		}
+	}
+
+	async getAllFromIndex<T = unknown>(
+		storeName: string,
+		indexName: string,
+		direction: "asc" | "desc" = "asc",
+	): Promise<T[]> {
+		const db = await this.getDB();
+		const tx = db.transaction(storeName, "readonly");
+		const store = tx.objectStore(storeName);
+		const index = store.index(indexName);
+
+		return new Promise((resolve, reject) => {
+			const results: T[] = [];
+			const request = index.openCursor(null, direction === "desc" ? "prev" : "next");
+
+			request.onsuccess = () => {
+				const cursor = request.result;
+				if (cursor) {
+					results.push(cursor.value as T);
+					cursor.continue();
+				} else {
+					resolve(results);
+				}
+			};
+
+			request.onerror = () => reject(request.error);
+		});
+	}
+
+	async clear(storeName: string): Promise<void> {
+		const db = await this.getDB();
+		const tx = db.transaction(storeName, "readwrite");
+		const store = tx.objectStore(storeName);
+		await this.promisifyRequest(store.clear());
+	}
+
+	async has(storeName: string, key: string): Promise<boolean> {
+		const db = await this.getDB();
+		const tx = db.transaction(storeName, "readonly");
+		const store = tx.objectStore(storeName);
+		const result = await this.promisifyRequest(store.getKey(key));
+		return result !== undefined;
+	}
+
+	async transaction<T>(
+		storeNames: string[],
+		mode: "readonly" | "readwrite",
+		operation: (tx: StorageTransaction) => Promise<T>,
+	): Promise<T> {
+		const db = await this.getDB();
+		const idbTx = db.transaction(storeNames, mode);
+
+		const storageTx: StorageTransaction = {
+			get: async <T>(storeName: string, key: string) => {
+				const store = idbTx.objectStore(storeName);
+				const result = await this.promisifyRequest(store.get(key));
+				return (result ?? null) as T | null;
+			},
+			set: async <T>(storeName: string, key: string, value: T) => {
+				const store = idbTx.objectStore(storeName);
+				// If store has keyPath, only pass value (in-line key)
+				// Otherwise pass both value and key (out-of-line key)
+				if (store.keyPath) {
+					await this.promisifyRequest(store.put(value));
+				} else {
+					await this.promisifyRequest(store.put(value, key));
+				}
+			},
+			delete: async (storeName: string, key: string) => {
+				const store = idbTx.objectStore(storeName);
+				await this.promisifyRequest(store.delete(key));
+			},
+		};
+
+		return operation(storageTx);
+	}
+
+	async getQuotaInfo(): Promise<{ usage: number; quota: number; percent: number }> {
+		if (navigator.storage?.estimate) {
+			const estimate = await navigator.storage.estimate();
+			return {
+				usage: estimate.usage || 0,
+				quota: estimate.quota || 0,
+				percent: estimate.quota ? ((estimate.usage || 0) / estimate.quota) * 100 : 0,
+			};
+		}
+		return { usage: 0, quota: 0, percent: 0 };
+	}
+
+	async requestPersistence(): Promise<boolean> {
+		if (navigator.storage?.persist) {
+			return await navigator.storage.persist();
+		}
+		return false;
+	}
+}