@dimina-kit/devtools 0.3.2-dev.20260524104239 → 0.3.2-dev.20260525152421

package/dist/main/services/simulator-temp-files/disk.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Main-process disk reader/writer backing `difile://_store/*` and
+ * `difile://<usr-rel>` URLs.
+ *
+ * Spec: `packages/devtools/docs/file-system.md` §6 P1-1 / P1-3.
+ *
+ *   - `readDiskFile(realPath, opts?)`: read a (possibly ranged) slice of a
+ *     file inside the USER_DATA_PATH sandbox. Returns `bytes` plus the
+ *     content metadata callers need to assemble an HTTP response without a
+ *     second `fs.stat` round-trip (`mime`, `etag`, `totalSize`).
+ *   - `writeDiskFile(realPath, bytes)`: write bytes into the sandbox,
+ *     creating parent directories on demand. Accepts both `Buffer` and
+ *     `ArrayBuffer`.
+ *   - `readDiskDir(realPath)`: list immediate children, no '.' / '..'.
+ *   - `statDiskFile(realPath)`: minimal stat surface (size/mtime/mode/flags).
+ *
+ * The caller is responsible for canonicalizing `realPath` through
+ * `resolveVPath` *before* invoking these helpers — disk.ts assumes the
+ * argument is already known to be inside the sandbox base.
+ *
+ * MIME resolution prefers magic-byte sniffing (first ~12 bytes) over file
+ * extension, falling back to `application/octet-stream` for both unknown
+ * extensions and unknown magic.
+ *
+ * ETag shape is `W/"<mtime-ms>-<size>"` — weak validator, both axes folded
+ * into one token so byte-equal rewrites at the same timestamp still match.
+ */
+export interface DiskReadResult {
+    bytes: Buffer;
+    mime: string;
+    /** Weak ETag of the form `W/"<mtime>-<size>"`. */
+    etag: string;
+    /** Full file size in bytes, regardless of whether a Range slice was returned. */
+    totalSize: number;
+}
+export interface DiskReadOptions {
+    /** Inclusive byte range `[start, end]`. Omit to read the whole file. */
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+export interface DiskStat {
+    size: number;
+    /** Unix milliseconds. */
+    mtime: number;
+    mode: number;
+    isFile: boolean;
+    isDirectory: boolean;
+}
+export declare function readDiskFile(realPath: string, opts?: DiskReadOptions): Promise<DiskReadResult>;
+export declare function writeDiskFile(realPath: string, bytes: Buffer | ArrayBuffer): Promise<void>;
+export declare function readDiskDir(realPath: string): Promise<string[]>;
+export declare function statDiskFile(realPath: string): Promise<DiskStat>;
+//# sourceMappingURL=disk.d.ts.map

package/dist/main/services/simulator-temp-files/disk.js

@@ -0,0 +1,215 @@
+/**
+ * Main-process disk reader/writer backing `difile://_store/*` and
+ * `difile://<usr-rel>` URLs.
+ *
+ * Spec: `packages/devtools/docs/file-system.md` §6 P1-1 / P1-3.
+ *
+ *   - `readDiskFile(realPath, opts?)`: read a (possibly ranged) slice of a
+ *     file inside the USER_DATA_PATH sandbox. Returns `bytes` plus the
+ *     content metadata callers need to assemble an HTTP response without a
+ *     second `fs.stat` round-trip (`mime`, `etag`, `totalSize`).
+ *   - `writeDiskFile(realPath, bytes)`: write bytes into the sandbox,
+ *     creating parent directories on demand. Accepts both `Buffer` and
+ *     `ArrayBuffer`.
+ *   - `readDiskDir(realPath)`: list immediate children, no '.' / '..'.
+ *   - `statDiskFile(realPath)`: minimal stat surface (size/mtime/mode/flags).
+ *
+ * The caller is responsible for canonicalizing `realPath` through
+ * `resolveVPath` *before* invoking these helpers — disk.ts assumes the
+ * argument is already known to be inside the sandbox base.
+ *
+ * MIME resolution prefers magic-byte sniffing (first ~12 bytes) over file
+ * extension, falling back to `application/octet-stream` for both unknown
+ * extensions and unknown magic.
+ *
+ * ETag shape is `W/"<mtime-ms>-<size>"` — weak validator, both axes folded
+ * into one token so byte-equal rewrites at the same timestamp still match.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+// -- MIME detection ---------------------------------------------------------
+/**
+ * Extension-based MIME fallback. Kept deliberately small — anything more
+ * exotic should land in the magic-byte sniffer above. Lowercase keys only.
+ */
+const EXT_MIME = {
+    '.txt': 'text/plain',
+    '.log': 'text/plain',
+    '.md': 'text/markdown',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.css': 'text/css',
+    '.csv': 'text/csv',
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.bmp': 'image/bmp',
+    '.ico': 'image/x-icon',
+    '.mp4': 'video/mp4',
+    '.m4v': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.pdf': 'application/pdf',
+    '.zip': 'application/zip',
+};
+function sniffMime(head) {
+    if (head.length >= 8
+        && head[0] === 0x89 && head[1] === 0x50 && head[2] === 0x4e && head[3] === 0x47
+        && head[4] === 0x0d && head[5] === 0x0a && head[6] === 0x1a && head[7] === 0x0a) {
+        return 'image/png';
+    }
+    if (head.length >= 3 && head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    if (head.length >= 6
+        && head[0] === 0x47 && head[1] === 0x49 && head[2] === 0x46
+        && head[3] === 0x38 && (head[4] === 0x37 || head[4] === 0x39) && head[5] === 0x61) {
+        return 'image/gif';
+    }
+    if (head.length >= 12
+        && head[0] === 0x52 && head[1] === 0x49 && head[2] === 0x46 && head[3] === 0x46
+        && head[8] === 0x57 && head[9] === 0x45 && head[10] === 0x42 && head[11] === 0x50) {
+        return 'image/webp';
+    }
+    if (head.length >= 12
+        && head[4] === 0x66 && head[5] === 0x74 && head[6] === 0x79 && head[7] === 0x70) {
+        // MP4 ftyp box: brand bytes vary, treat all as video/mp4 for now.
+        return 'video/mp4';
+    }
+    if (head.length >= 4
+        && head[0] === 0x25 && head[1] === 0x50 && head[2] === 0x44 && head[3] === 0x46) {
+        return 'application/pdf';
+    }
+    if (head.length >= 2 && head[0] === 0x42 && head[1] === 0x4d) {
+        return 'image/bmp';
+    }
+    if (head.length >= 4
+        && head[0] === 0x50 && head[1] === 0x4b && head[2] === 0x03 && head[3] === 0x04) {
+        return 'application/zip';
+    }
+    if (head.length >= 3 && head[0] === 0x49 && head[1] === 0x44 && head[2] === 0x33) {
+        // ID3-tagged MP3.
+        return 'audio/mpeg';
+    }
+    if (head.length >= 4 && head[0] === 0x4f && head[1] === 0x67 && head[2] === 0x67 && head[3] === 0x53) {
+        return 'audio/ogg';
+    }
+    return null;
+}
+function extMime(realPath) {
+    const ext = path.extname(realPath).toLowerCase();
+    if (!ext)
+        return null;
+    return EXT_MIME[ext] ?? null;
+}
+function detectMime(realPath, head) {
+    const sniffed = sniffMime(head);
+    if (sniffed)
+        return sniffed;
+    const byExt = extMime(realPath);
+    if (byExt)
+        return byExt;
+    return 'application/octet-stream';
+}
+// -- ETag -------------------------------------------------------------------
+function etagOf(mtimeMs, size) {
+    return `W/"${Math.floor(mtimeMs)}-${size}"`;
+}
+// -- read -------------------------------------------------------------------
+export async function readDiskFile(realPath, opts) {
+    const handle = await fs.open(realPath, 'r');
+    try {
+        const st = await handle.stat();
+        const totalSize = st.size;
+        const mtimeMs = st.mtimeMs;
+        const range = opts?.range;
+        let sliceStart = 0;
+        let sliceLen = totalSize;
+        if (range) {
+            const { start, end } = range;
+            if (!Number.isFinite(start) || !Number.isFinite(end)) {
+                throw new RangeError(`invalid range: ${start}-${end}`);
+            }
+            if (start < 0)
+                throw new RangeError(`range start out of bounds: ${start}`);
+            if (start > end)
+                throw new RangeError(`range start > end: ${start} > ${end}`);
+            if (start >= totalSize) {
+                throw new RangeError(`range start beyond file size: ${start} >= ${totalSize}`);
+            }
+            const clampedEnd = Math.min(end, totalSize - 1);
+            sliceStart = start;
+            sliceLen = clampedEnd - start + 1;
+        }
+        // Read at most the first 12 bytes for magic sniffing, regardless of
+        // whether the caller asked for a range. We need the head bytes from
+        // position 0 to label Content-Type correctly even on a tail Range
+        // request. For full reads the head is part of the body so we re-use
+        // it without a second read.
+        const head = Buffer.alloc(Math.min(12, totalSize));
+        if (head.length > 0) {
+            await handle.read(head, 0, head.length, 0);
+        }
+        let bytes;
+        if (!range) {
+            bytes = Buffer.alloc(totalSize);
+            if (totalSize > 0) {
+                if (totalSize <= head.length) {
+                    head.copy(bytes, 0, 0, totalSize);
+                }
+                else {
+                    head.copy(bytes, 0, 0, head.length);
+                    await handle.read(bytes, head.length, totalSize - head.length, head.length);
+                }
+            }
+        }
+        else {
+            bytes = Buffer.alloc(sliceLen);
+            if (sliceLen > 0) {
+                await handle.read(bytes, 0, sliceLen, sliceStart);
+            }
+        }
+        return {
+            bytes,
+            mime: detectMime(realPath, head),
+            etag: etagOf(mtimeMs, totalSize),
+            totalSize,
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}
+// -- write ------------------------------------------------------------------
+export async function writeDiskFile(realPath, bytes) {
+    const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(new Uint8Array(bytes));
+    await fs.mkdir(path.dirname(realPath), { recursive: true });
+    await fs.writeFile(realPath, buf);
+}
+// -- dir --------------------------------------------------------------------
+export async function readDiskDir(realPath) {
+    const entries = await fs.readdir(realPath);
+    return entries;
+}
+// -- stat -------------------------------------------------------------------
+export async function statDiskFile(realPath) {
+    const st = await fs.stat(realPath);
+    return {
+        size: st.size,
+        mtime: Math.floor(st.mtimeMs),
+        mode: st.mode,
+        isFile: st.isFile(),
+        isDirectory: st.isDirectory(),
+    };
+}
+//# sourceMappingURL=disk.js.map

package/dist/main/services/simulator-temp-files/fs-channels.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Main-process `simulator:fs:*` IPC channel handlers.
+ *
+ * Spec: `packages/devtools/docs/file-system.md` §4.4, §6 P1-7.
+ *
+ * Each handler is the pure function that backs one IPC channel:
+ *
+ *   simulator:fs:read    → handleFsRead
+ *   simulator:fs:write   → handleFsWrite
+ *   simulator:fs:stat    → handleFsStat
+ *   simulator:fs:readdir → handleFsReaddir
+ *   simulator:fs:unlink  → handleFsUnlink
+ *   simulator:fs:mkdir   → handleFsMkdir
+ *
+ * Every handler MUST defensively re-assert that `realPath` lies inside the
+ * USER_DATA_PATH sandbox base (`DIMINA_HOME`-aware). The IPC boundary cannot
+ * trust the caller — a hostile preload or fuzzed payload could send a path
+ * that points outside the base. The renderer-side `resolveVPath` is one
+ * layer; this is the second.
+ *
+ * MIME / ETag / Range semantics mirror `disk.ts`; see `disk.test.ts` for
+ * the full contract on those axes.
+ */
+import { type DiskStat } from './disk.js';
+export interface FsReadRequest {
+    realPath: string;
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+export interface FsReadResult {
+    bytes: Buffer | ArrayBuffer;
+    mime: string;
+    /** Weak ETag of the form `W/"<mtime>-<size>"`. */
+    etag: string;
+    /** Full file size in bytes, regardless of whether a Range slice was returned. */
+    totalSize: number;
+}
+export interface FsWriteRequest {
+    realPath: string;
+    bytes: Buffer | ArrayBuffer;
+}
+export interface FsStatRequest {
+    realPath: string;
+}
+export interface FsReaddirRequest {
+    realPath: string;
+}
+export interface FsUnlinkRequest {
+    realPath: string;
+}
+export interface FsMkdirRequest {
+    realPath: string;
+    recursive?: boolean;
+}
+export declare function handleFsRead(req: FsReadRequest): Promise<FsReadResult>;
+export declare function handleFsWrite(req: FsWriteRequest): Promise<{
+    ok: true;
+}>;
+export declare function handleFsStat(req: FsStatRequest): Promise<DiskStat>;
+export declare function handleFsReaddir(req: FsReaddirRequest): Promise<string[]>;
+export declare function handleFsUnlink(req: FsUnlinkRequest): Promise<{
+    ok: true;
+}>;
+export declare function handleFsMkdir(req: FsMkdirRequest): Promise<{
+    ok: true;
+}>;
+//# sourceMappingURL=fs-channels.d.ts.map

package/dist/main/services/simulator-temp-files/fs-channels.js

@@ -0,0 +1,108 @@
+/**
+ * Main-process `simulator:fs:*` IPC channel handlers.
+ *
+ * Spec: `packages/devtools/docs/file-system.md` §4.4, §6 P1-7.
+ *
+ * Each handler is the pure function that backs one IPC channel:
+ *
+ *   simulator:fs:read    → handleFsRead
+ *   simulator:fs:write   → handleFsWrite
+ *   simulator:fs:stat    → handleFsStat
+ *   simulator:fs:readdir → handleFsReaddir
+ *   simulator:fs:unlink  → handleFsUnlink
+ *   simulator:fs:mkdir   → handleFsMkdir
+ *
+ * Every handler MUST defensively re-assert that `realPath` lies inside the
+ * USER_DATA_PATH sandbox base (`DIMINA_HOME`-aware). The IPC boundary cannot
+ * trust the caller — a hostile preload or fuzzed payload could send a path
+ * that points outside the base. The renderer-side `resolveVPath` is one
+ * layer; this is the second.
+ *
+ * MIME / ETag / Range semantics mirror `disk.ts`; see `disk.test.ts` for
+ * the full contract on those axes.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { sandboxBase } from '../../../simulator/vpath.js';
+import { readDiskDir, readDiskFile, statDiskFile, writeDiskFile, } from './disk.js';
+/**
+ * Defense-in-depth: a hostile preload could synthesize a `realPath` that
+ * resolveVPath would never produce. Re-canonicalize and re-anchor under the
+ * sandbox base every time, throwing if the result escapes.
+ *
+ * Two-layer check:
+ *  1. Lexical: `path.normalize` then `startsWith(base + sep)`.
+ *  2. Filesystem: `fs.realpath` to follow symlinks and re-assert containment.
+ *
+ * The symlink check is best-effort — if the path does not yet exist (e.g. a
+ * write/mkdir target), `fs.realpath` throws ENOENT and we fall back to
+ * checking the deepest existing ancestor instead. A symlinked ancestor that
+ * points outside the sandbox still gets caught that way.
+ */
+async function enforceSandbox(realPath) {
+    if (typeof realPath !== 'string' || realPath.length === 0) {
+        throw new Error('sandbox: realPath must be a non-empty string');
+    }
+    const base = sandboxBase();
+    const baseReal = await fs.realpath(base).catch(() => base);
+    const normalized = path.normalize(realPath);
+    if (normalized !== base && !normalized.startsWith(base + path.sep)) {
+        throw new Error('sandbox: realPath escapes the user-data base');
+    }
+    // Walk up until we find an existing path, realpath it, and assert the
+    // resolved ancestor stays under the sandbox base. This catches symlinks
+    // anywhere along the chain — both the leaf (read/stat) and the parent
+    // (write/mkdir creating a new file under a symlinked dir).
+    let probe = normalized;
+    while (probe !== path.parse(probe).root) {
+        try {
+            const resolved = await fs.realpath(probe);
+            if (resolved !== baseReal && !resolved.startsWith(baseReal + path.sep)) {
+                throw new Error('sandbox: realPath escapes the user-data base via symlink');
+            }
+            break;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                probe = path.dirname(probe);
+                continue;
+            }
+            throw err;
+        }
+    }
+    return normalized;
+}
+export async function handleFsRead(req) {
+    const safe = await enforceSandbox(req.realPath);
+    const result = await readDiskFile(safe, req.range ? { range: req.range } : undefined);
+    return {
+        bytes: result.bytes,
+        mime: result.mime,
+        etag: result.etag,
+        totalSize: result.totalSize,
+    };
+}
+export async function handleFsWrite(req) {
+    const safe = await enforceSandbox(req.realPath);
+    await writeDiskFile(safe, req.bytes);
+    return { ok: true };
+}
+export async function handleFsStat(req) {
+    const safe = await enforceSandbox(req.realPath);
+    return statDiskFile(safe);
+}
+export async function handleFsReaddir(req) {
+    const safe = await enforceSandbox(req.realPath);
+    return readDiskDir(safe);
+}
+export async function handleFsUnlink(req) {
+    const safe = await enforceSandbox(req.realPath);
+    await fs.unlink(safe);
+    return { ok: true };
+}
+export async function handleFsMkdir(req) {
+    const safe = await enforceSandbox(req.realPath);
+    await fs.mkdir(safe, { recursive: !!req.recursive });
+    return { ok: true };
+}
+//# sourceMappingURL=fs-channels.js.map

package/dist/main/services/simulator-temp-files/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Wires the `difile://_tmp/*` protocol handler on the simulator session
+ * and bridges renderer-side `setTempFileSink` callbacks to the main-process
+ * byte store. Returned disposable clears the store, unregisters the protocol
+ * handler, and tears down its private IPC channels.
+ *
+ * SENDER POLICY: The default workbench sender-policy intentionally rejects
+ * the simulator `<webview>` (see `utils/sender-policy.ts`). The simulator
+ * is the only legitimate writer for these channels, so this module installs
+ * its own narrow policy that accepts a sender only when its WebContents
+ * belongs to the simulator `Session` we were handed. This bypasses the
+ * default policy without widening trust to any other source.
+ *
+ * WRITE-vs-RENDER RACE: `createTempFilePath` is synchronous on the renderer,
+ * but the bytes travel here through `blob.arrayBuffer().then(ipcRenderer.send)`
+ * — async. The simulator can race ahead: in `chooseMedia` the renderer
+ * assigns `img.src = tempFilePath` (via `readImageMetadata`) immediately
+ * after `createTempFilePath` returns, which fires a `difile://` GET before
+ * our IPC write arrives. The protocol handler therefore parks a request on
+ * a per-url waiter for up to PENDING_TIMEOUT_MS; the IPC `write` handler
+ * drains the waiter on arrival.
+ *
+ * QUOTA: A single in-memory store backs all simulator sessions for the
+ * lifetime of the WorkbenchApp instance. We cap it at MAX_STORE_ENTRIES
+ * (FIFO eviction). Project switches do NOT clear the store on their own —
+ * stale entries from a previous project simply age out as new ones land.
+ * This is the same eviction shape WeChat uses for tmp files (LRU under a
+ * size cap), simplified for a dev-tools session scope.
+ */
+import type { Session } from 'electron';
+import { type Disposable } from '../../utils/disposable.js';
+export declare function setupSimulatorTempFiles(simSession: Session): Disposable;
+//# sourceMappingURL=index.d.ts.map

package/dist/main/services/simulator-temp-files/index.js

@@ -0,0 +1,160 @@
+/**
+ * Wires the `difile://_tmp/*` protocol handler on the simulator session
+ * and bridges renderer-side `setTempFileSink` callbacks to the main-process
+ * byte store. Returned disposable clears the store, unregisters the protocol
+ * handler, and tears down its private IPC channels.
+ *
+ * SENDER POLICY: The default workbench sender-policy intentionally rejects
+ * the simulator `<webview>` (see `utils/sender-policy.ts`). The simulator
+ * is the only legitimate writer for these channels, so this module installs
+ * its own narrow policy that accepts a sender only when its WebContents
+ * belongs to the simulator `Session` we were handed. This bypasses the
+ * default policy without widening trust to any other source.
+ *
+ * WRITE-vs-RENDER RACE: `createTempFilePath` is synchronous on the renderer,
+ * but the bytes travel here through `blob.arrayBuffer().then(ipcRenderer.send)`
+ * — async. The simulator can race ahead: in `chooseMedia` the renderer
+ * assigns `img.src = tempFilePath` (via `readImageMetadata`) immediately
+ * after `createTempFilePath` returns, which fires a `difile://` GET before
+ * our IPC write arrives. The protocol handler therefore parks a request on
+ * a per-url waiter for up to PENDING_TIMEOUT_MS; the IPC `write` handler
+ * drains the waiter on arrival.
+ *
+ * QUOTA: A single in-memory store backs all simulator sessions for the
+ * lifetime of the WorkbenchApp instance. We cap it at MAX_STORE_ENTRIES
+ * (FIFO eviction). Project switches do NOT clear the store on their own —
+ * stale entries from a previous project simply age out as new ones land.
+ * This is the same eviction shape WeChat uses for tmp files (LRU under a
+ * size cap), simplified for a dev-tools session scope.
+ */
+import { IpcRegistry } from '../../utils/ipc-registry.js';
+import { toDisposable } from '../../utils/disposable.js';
+import { registerTempFile, revokeTempFile, revokeAllTempFiles } from './store.js';
+import { handleDifileRequest } from './request-handler.js';
+import { handleFsMkdir, handleFsRead, handleFsReaddir, handleFsStat, handleFsUnlink, handleFsWrite, } from './fs-channels.js';
+/** Upper bound for in-memory entries; oldest insertion is evicted (FIFO). */
+const MAX_STORE_ENTRIES = 200;
+/** Max time the protocol handler waits for an in-flight `write` IPC. */
+const PENDING_TIMEOUT_MS = 500;
+function enforceStoreCap(store) {
+    while (store.size > MAX_STORE_ENTRIES) {
+        const next = store.keys().next();
+        if (next.done)
+            break;
+        store.delete(next.value);
+    }
+}
+export function setupSimulatorTempFiles(simSession) {
+    const store = new Map();
+    const pendingWaiters = new Map();
+    let disposed = false;
+    function drainWaiters(path) {
+        const list = pendingWaiters.get(path);
+        if (!list)
+            return;
+        pendingWaiters.delete(path);
+        for (const fn of list)
+            fn();
+    }
+    function drainAllWaiters() {
+        const lists = Array.from(pendingWaiters.values());
+        pendingWaiters.clear();
+        for (const list of lists)
+            for (const fn of list)
+                fn();
+    }
+    const simulatorOnlyPolicy = sender => !sender.isDestroyed() && sender.session === simSession;
+    const registry = new IpcRegistry(simulatorOnlyPolicy);
+    registry.on('simulator:temp-file:write', (_event, payload) => {
+        if (disposed)
+            return;
+        const { path, mime, bytes } = payload;
+        registerTempFile(store, path, mime, bytes);
+        enforceStoreCap(store);
+        drainWaiters(path);
+    });
+    registry.on('simulator:temp-file:revoke', (_event, payload) => {
+        if (disposed)
+            return;
+        const { path } = payload;
+        revokeTempFile(store, path);
+    });
+    registry.on('simulator:temp-file:revoke-all', () => {
+        if (disposed)
+            return;
+        revokeAllTempFiles(store);
+    });
+    // Idempotent: a stale handler from a prior setup (e.g. fast app
+    // re-init in tests) is replaced rather than throwing.
+    try {
+        simSession.protocol.unhandle('difile');
+    }
+    catch {
+        // Not previously registered — fine.
+    }
+    simSession.protocol.handle('difile', async (req) => {
+        const url = req.url;
+        // Forward any HTTP headers Electron parsed (Range / If-None-Match)
+        // to the pure dispatcher so it can do its own conditional / range
+        // shaping.
+        const headers = {};
+        try {
+            req.headers.forEach((v, k) => { headers[k] = v; });
+        }
+        catch {
+            // Older Electron headers shape may not be iterable — best effort.
+        }
+        const ctx = { tempStore: store };
+        let res = await handleDifileRequest(ctx, { url, headers });
+        // Race waiter: the renderer-side `createTempFilePath` is synchronous
+        // but its `bytes` IPC arrives later. If we miss a `_tmp/*` lookup,
+        // park briefly and retry once.
+        if (res.status === 404
+            && !disposed
+            && url.startsWith('difile://_tmp/')) {
+            await new Promise((resolve) => {
+                let timer = null;
+                const notify = () => {
+                    if (timer)
+                        clearTimeout(timer);
+                    resolve();
+                };
+                const list = pendingWaiters.get(url) ?? new Set();
+                list.add(notify);
+                pendingWaiters.set(url, list);
+                timer = setTimeout(() => {
+                    const cur = pendingWaiters.get(url);
+                    if (cur) {
+                        cur.delete(notify);
+                        if (cur.size === 0)
+                            pendingWaiters.delete(url);
+                    }
+                    resolve();
+                }, PENDING_TIMEOUT_MS);
+            });
+            res = await handleDifileRequest(ctx, { url, headers });
+        }
+        return res;
+    });
+    // Phase 1 (P1-7): renderer FSM → main fs operations bridge. The same
+    // simulator-only sender policy applies — registry instance is shared.
+    registry.handle('simulator:fs:read', (_event, payload) => handleFsRead(payload));
+    registry.handle('simulator:fs:write', (_event, payload) => handleFsWrite(payload));
+    registry.handle('simulator:fs:stat', (_event, payload) => handleFsStat(payload));
+    registry.handle('simulator:fs:readdir', (_event, payload) => handleFsReaddir(payload));
+    registry.handle('simulator:fs:unlink', (_event, payload) => handleFsUnlink(payload));
+    registry.handle('simulator:fs:mkdir', (_event, payload) => handleFsMkdir(payload));
+    return toDisposable(async () => {
+        disposed = true;
+        drainAllWaiters();
+        store.clear();
+        try {
+            simSession.protocol.unhandle('difile');
+        }
+        catch {
+            // May already have been unhandled by app shutdown.
+        }
+        await registry.dispose();
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/main/services/simulator-temp-files/request-handler.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure dispatcher for `difile://` URL requests.
+ *
+ * Spec: `packages/devtools/docs/file-system.md` §4.3.
+ *
+ * The shipping implementation in `index.ts` registers a thin
+ * `simSession.protocol.handle('difile')` wrapper that delegates here; the race
+ * waiter on `_tmp/*` lives in `index.ts` because it owns the IPC lifecycle.
+ * For unit tests we assume the bytes are already in the store.
+ *
+ * Response shape:
+ *   - 200: full body, with Content-Type, Cache-Control (immutable), ETag
+ *   - 206: range slice, plus Content-Range
+ *   - 304: empty body when `If-None-Match` matches the on-disk ETag. Per RFC
+ *     9110 §13.1.2 If-None-Match wins over Range.
+ *   - 404: anything `resolveVPath` rejects, plus disk-side ENOENT and any
+ *     other I/O error. The protocol handler in `index.ts` translates this
+ *     into the renderer's network failure surface; we deliberately do not
+ *     leak errno strings.
+ */
+import type { TempFileStore } from './resolver.js';
+export interface HandleDifileContext {
+    tempStore: TempFileStore;
+}
+export interface HandleDifileRequest {
+    url: string;
+    headers?: Record<string, string>;
+}
+export declare function handleDifileRequest(ctx: HandleDifileContext, req: HandleDifileRequest): Promise<Response>;
+//# sourceMappingURL=request-handler.d.ts.map