Cydog File System Bridge Development Guide

Best practices for optimizing memory consumption, managing handle lifecycles, and streaming files via the Cydog File System Access Bridge.

1. Memory Management & Lazy Handle Indexing

When bridging native operating system files to the Cydog Browser file system, never read full file contents into memory during the selection phase. Always decouple path indexing from data reading.

// CORRECT: Store lightweight handle metadata only
const queue = Array.from(input.files).map(file => ({
    path: file.webkitRelativePath || file.name,
    ref: file // Keeps pointer, leaves raw bytes on disk
}));

// INCORRECT: Pre-loading contents into memory crashes the browser on large sets
const dangerousQueue = await Promise.all(
    Array.from(input.files).map(async f => ({ path: f.name, data: await f.text() }))
);

2. Asynchronous Thread Yielding

Sequential loops operating on filesystem promises can block the main JavaScript UI thread and prevent browser Garbage Collection. Yield control back to the event loop on every write iteration.

Rule of Thumb: Always insert an asynchronous macro-task yield (e.g., await new Promise(r => setTimeout(r, 0))) at the end of each item write block to prevent thread lock and out-of-memory browser crashes. 
for (let i = 0; i < queue.length; i++) {
    const item = queue[i];

    // Read single file into memory scope
    const content = await item.ref.text();

    // Perform bridge write
    await writeToCydogBridge(item.path, content);

    // Yield control to allow Garbage Collector & UI DOM updates
    await new Promise(resolve => setTimeout(resolve, 0));
}

3. Cydog Bridge Request Standardization

Ensure your application safely normalizes interaction with window.__CydogBridge and fallback Native File System Access handles (FileSystemDirectoryHandle).

// Safe bridge invocation wrapper
async function writeToCydogBridge(targetPath, fileContent) {
    const domain = window.location.hostname || window.location.protocol || 'local_app';

    if (window.__CydogBridge && typeof window.__CydogBridge.request === 'function') {
        // Native Cydog Bridge implementation
        return await window.__CydogBridge.request('writeFile', {
            path: targetPath,
            text: fileContent,
            domain: domain
        });
    } else {
        throw new Error("Cydog File System Bridge interface unavailable.");
    }
}

4. Nested Directory Traversal & Handle Safety

When working with directory handles returned from window.showDirectoryPicker(), recursively build subdirectories using `{ create: true }` to guarantee path integrity without asking users to type directory strings.

async function resolveDirectoryTree(rootHandle, relativePath) {
    const pathParts = relativePath.split('/');
    const fileName = pathParts.pop();
    let currentDir = rootHandle;

    // Skip root prefix match if directory name matches root
    let startIndex = (pathParts.length > 0 && pathParts[0] === rootHandle.name) ? 1 : 0;

    for (let i = startIndex; i < pathParts.length; i++) {
        currentDir = await currentDir.getDirectoryHandle(pathParts[i], { create: true });
    }

    return await currentDir.getFileHandle(fileName, { create: true });
}

5. Error Resilience & Granular Progress Tracking

Protect bulk file bridge transfers from failing completely due to isolated file permission or parsing errors.