@statewalker/webrun-files-composite 0.8.0 → 0.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 statewalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cjs/index.cjs

@@ -22,6 +22,25 @@ function normalizePath(filePath) {
 function joinPath(...segments) {
 	return normalizePath(segments.join("/"));
 }
+/**
+* Returns the directory portion of a path.
+*/
+function dirname(path) {
+	const normalized = normalizePath(path);
+	const lastSlash = normalized.lastIndexOf("/");
+	if (lastSlash <= 0) return "/";
+	return normalized.substring(0, lastSlash);
+}
+/**
+* Returns the filename portion of a path.
+*/
+function basename(path, ext) {
+	const normalized = normalizePath(path);
+	const lastSlash = normalized.lastIndexOf("/");
+	const name = lastSlash === -1 ? normalized : normalized.substring(lastSlash + 1);
+	if (ext && name.endsWith(ext)) return name.substring(0, name.length - ext.length);
+	return name;
+}
 //#endregion
 //#region src/composite-files-api.ts
 /**
@@ -258,6 +277,177 @@ var CompositeFilesApi = class {
 	}
 };
 //#endregion
+//#region src/cow-files-api.ts
+/**
+* Copy-on-write view: a writable layer over a read-only `base`. The `base`
+* is **never** mutated — every change (write, delete, move) is recorded in
+* the `writable` layer, using marker files to record deletions.
+*
+* Resolution precedence for any path:
+* 1. a covering whiteout / opaque marker ⇒ the path is absent;
+* 2. otherwise the `writable` layer, if it has the path;
+* 3. otherwise fall through to `base`.
+*
+* Deletions are persisted as marker files inside the writable layer, so they
+* survive across process restarts and work over any `FilesApi` backend.
+* Markers are hidden from `read` / `list` / `stats` / `exists`.
+*
+* Use {@link cow} to construct one.
+*/
+var CowFilesApi = class {
+	base;
+	writable;
+	whiteoutPrefix;
+	opaqueName;
+	constructor(base, writable, opts) {
+		this.base = base;
+		this.writable = writable;
+		this.whiteoutPrefix = opts?.whiteoutPrefix ?? ".wh.";
+		this.opaqueName = opts?.opaqueName ?? ".wh..opq";
+	}
+	whiteoutPath(path) {
+		const p = normalizePath(path);
+		return joinPath(dirname(p), `${this.whiteoutPrefix}${basename(p)}`);
+	}
+	opaquePath(dir) {
+		return joinPath(normalizePath(dir), this.opaqueName);
+	}
+	isMarker(name) {
+		return name.startsWith(this.whiteoutPrefix) || name === this.opaqueName;
+	}
+	*ancestorsInclusive(dir) {
+		let cur = normalizePath(dir);
+		yield cur;
+		while (cur !== "/") {
+			cur = dirname(cur);
+			yield cur;
+		}
+	}
+	async hasDirectWhiteout(path) {
+		return this.writable.exists(this.whiteoutPath(path));
+	}
+	/** True when an opaque marker on `dir` or any ancestor hides base content. */
+	async isBaseContentHidden(dir) {
+		for (const ancestor of this.ancestorsInclusive(dir)) if (await this.writable.exists(this.opaquePath(ancestor))) return true;
+		return false;
+	}
+	/** True when the base version of `path` is hidden by a marker. */
+	async isBaseHidden(path) {
+		if (await this.hasDirectWhiteout(path)) return true;
+		return this.isBaseContentHidden(dirname(normalizePath(path)));
+	}
+	async resolveLayer(path) {
+		if (await this.writable.exists(path)) return "writable";
+		if (await this.isBaseHidden(path)) return "absent";
+		if (await this.base.exists(path)) return "base";
+		return "absent";
+	}
+	/** Removes a covering whiteout marker so a write/mkdir resurrects the path. */
+	async clearWhiteout(path) {
+		const marker = this.whiteoutPath(path);
+		if (await this.writable.exists(marker)) await this.writable.remove(marker);
+	}
+	async *read(path, options) {
+		const layer = await this.resolveLayer(path);
+		if (layer === "writable") yield* this.writable.read(path, options);
+		else if (layer === "base") yield* this.base.read(path, options);
+	}
+	async write(path, content) {
+		await this.clearWhiteout(path);
+		await this.writable.write(path, content);
+	}
+	async mkdir(path) {
+		await this.clearWhiteout(path);
+		await this.writable.mkdir(path);
+	}
+	async stats(path) {
+		const layer = await this.resolveLayer(path);
+		if (layer === "writable") return this.writable.stats(path);
+		if (layer === "base") return this.base.stats(path);
+	}
+	async exists(path) {
+		return await this.resolveLayer(path) !== "absent";
+	}
+	async *list(path, options) {
+		yield* this.listDir(normalizePath(path), options?.recursive ?? false);
+	}
+	async *listDir(dir, recursive) {
+		if ((await this.stats(dir))?.kind !== "directory") return;
+		for (const entry of await this.mergeChildren(dir)) {
+			yield entry;
+			if (recursive && entry.kind === "directory") yield* this.listDir(entry.path, true);
+		}
+	}
+	/** Direct children of `dir`: writable entries win, base entries fill in. */
+	async mergeChildren(dir) {
+		const merged = /* @__PURE__ */ new Map();
+		if ((await this.writable.stats(dir))?.kind === "directory") for await (const entry of this.writable.list(dir)) {
+			if (this.isMarker(entry.name)) continue;
+			merged.set(entry.name, entry);
+		}
+		if (!await this.isBaseContentHidden(dir) && (await this.base.stats(dir))?.kind === "directory") for await (const entry of this.base.list(dir)) {
+			if (merged.has(entry.name)) continue;
+			if (await this.hasDirectWhiteout(entry.path)) continue;
+			merged.set(entry.name, entry);
+		}
+		return [...merged.values()];
+	}
+	async remove(path) {
+		if (await this.resolveLayer(path) === "absent") return false;
+		if (await this.writable.exists(path)) await this.writable.remove(path);
+		const baseStats = await this.base.stats(path);
+		if (baseStats) {
+			const marker = baseStats.kind === "directory" ? this.opaquePath(path) : this.whiteoutPath(path);
+			await this.writable.write(marker, []);
+		}
+		return true;
+	}
+	async move(source, target) {
+		const stats = await this.stats(source);
+		if (!stats) return false;
+		await this.copyInto(source, target, stats);
+		await this.remove(source);
+		return true;
+	}
+	async copy(source, target) {
+		const stats = await this.stats(source);
+		if (!stats) return false;
+		await this.copyInto(source, target, stats);
+		return true;
+	}
+	/** Copies the composite view of `src` into the writable layer at `tgt`. */
+	async copyInto(src, tgt, stats) {
+		if (stats.kind === "file") {
+			await this.write(tgt, this.read(src));
+			return;
+		}
+		await this.mkdir(tgt);
+		for await (const entry of this.list(src)) await this.copyInto(entry.path, joinPath(tgt, entry.name), entry);
+	}
+};
+/**
+* Builds a copy-on-write `FilesApi`: a `writable` layer over a read-only
+* `base`. Reads fall through to `base`; every write goes to `writable`;
+* `base` is never mutated. Deletions are persisted as marker files in
+* `writable` (a per-path whiteout for files, one opaque marker for a deleted
+* base directory), so they survive over any backend and across restarts.
+*
+* @param base The read-only lower layer. Never mutated.
+* @param writable The upper layer that captures all changes and markers.
+* @param opts Marker naming overrides (see {@link CowOptions}).
+* @returns A read/write `FilesApi` composing the two layers.
+*
+* @example
+* ```ts
+* const fs = cow(releaseFiles, new MemFilesApi());
+* await fs.write("/a.txt", data); // captured in the writable layer
+* await fs.remove("/base-only");  // whiteout marker; base untouched
+* ```
+*/
+function cow(base, writable, opts) {
+	return new CowFilesApi(base, writable, opts);
+}
+//#endregion
 //#region src/glob-to-regexp.ts
 /**
 * Compiles a glob pattern into a `RegExp`.
@@ -656,10 +846,136 @@ var GuardedFilesApi = class {
 	}
 };
 //#endregion
+//#region src/overlay-files-api.ts
+/**
+* Read-only union of several `FilesApi` layers. A path is resolved
+* **top → bottom**: the first layer that has it wins for
+* `read` / `stats` / `exists`, and its entry (including `kind`) wins any
+* name clash in `list`. Listings merge and dedupe across every layer.
+*
+* The union never writes — every mutating call throws. Use
+* {@link overlay} to construct one.
+*/
+var OverlayFilesApi = class {
+	layers;
+	constructor(layers) {
+		this.layers = layers;
+	}
+	deny(op, path) {
+		throw new Error(`overlay is read-only (${op}): ${normalizePath(path)}`);
+	}
+	async *read(path, options) {
+		for (const layer of this.layers) if (await layer.exists(path)) {
+			yield* layer.read(path, options);
+			return;
+		}
+	}
+	async stats(path) {
+		for (const layer of this.layers) {
+			const stats = await layer.stats(path);
+			if (stats) return stats;
+		}
+	}
+	async exists(path) {
+		for (const layer of this.layers) if (await layer.exists(path)) return true;
+		return false;
+	}
+	async *list(path, options) {
+		yield* this.listDir(normalizePath(path), options?.recursive ?? false);
+	}
+	async *listDir(dir, recursive) {
+		if ((await this.stats(dir))?.kind !== "directory") return;
+		for (const entry of await this.mergeChildren(dir)) {
+			yield entry;
+			if (recursive && entry.kind === "directory") yield* this.listDir(entry.path, true);
+		}
+	}
+	/** Direct children of `dir`, deduped by name with the topmost layer winning. */
+	async mergeChildren(dir) {
+		const merged = /* @__PURE__ */ new Map();
+		for (const layer of this.layers) {
+			if ((await layer.stats(dir))?.kind !== "directory") continue;
+			for await (const entry of layer.list(dir)) if (!merged.has(entry.name)) merged.set(entry.name, entry);
+		}
+		return [...merged.values()];
+	}
+	async write(path) {
+		this.deny("write", path);
+	}
+	async mkdir(path) {
+		this.deny("mkdir", path);
+	}
+	async remove(path) {
+		return this.deny("remove", path);
+	}
+	async move(source) {
+		return this.deny("move", source);
+	}
+	async copy(source) {
+		return this.deny("copy", source);
+	}
+};
+/**
+* Builds a **read-only** union view over `top` and any number of `lower`
+* layers. Reads resolve top → bottom (first layer that has the path wins);
+* `list` merges and dedupes across all layers with `top` winning a clash
+* (including a file-vs-directory `kind` clash). Every write is denied.
+*
+* @param top The highest-priority layer; its entries shadow the rest.
+* @param lower Additional layers, consulted in order after `top`.
+* @returns A read-only `FilesApi` union.
+*
+* @example
+* ```ts
+* const view = overlay(userFiles, defaultFiles);
+* await view.read("/config.json"); // userFiles if present, else defaultFiles
+* await view.write("/x", data);    // throws (read-only)
+* ```
+*/
+function overlay(top, ...lower) {
+	return new OverlayFilesApi([top, ...lower]);
+}
+//#endregion
+//#region src/read-only-files-api.ts
+/**
+* Wraps a `FilesApi` in a read-only view: every mutating operation
+* (`write`, `mkdir`, `remove`, `move`, `copy`) throws, while reads
+* (`read`, `list`, `stats`, `exists`) pass straight through to `api`.
+*
+* Implemented as a {@link GuardedFilesApi} with a single deny-all guard on
+* the mutating operations, so `move`/`copy` are blocked on either endpoint.
+*
+* @param api The underlying `FilesApi` to expose read-only.
+* @returns A `FilesApi` that never mutates `api`.
+*
+* @example
+* ```ts
+* const ro = readOnly(sourceFiles);
+* await ro.read("/a.txt");          // ok
+* await ro.write("/a.txt", data);   // throws "read-only: /a.txt"
+* ```
+*/
+function readOnly(api) {
+	return new GuardedFilesApi(api, [{
+		operations: [
+			"write",
+			"mkdir",
+			"remove",
+			"move",
+			"copy"
+		],
+		check: () => false,
+		message: "read-only"
+	}]);
+}
+//#endregion
 exports.CompositeFilesApi = CompositeFilesApi;
 exports.FilteredFilesApi = FilteredFilesApi;
 exports.GuardedFilesApi = GuardedFilesApi;
+exports.cow = cow;
 exports.globToRegExp = globToRegExp;
 exports.newGlobPathFilter = newGlobPathFilter;
 exports.newPathFilter = newPathFilter;
 exports.newRegexpPathFilter = newRegexpPathFilter;
+exports.overlay = overlay;
+exports.readOnly = readOnly;

package/dist/composite-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite-files-api.d.ts","sourceRoot":"","sources":["../src/composite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AASnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,OAAO,CAAC,MAAM,CAAe;IAE7B;;;;;;;;OAQG;gBACS,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM;IAI7C;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAazD,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,YAAY;IAKpB,yEAAyE;IACzE,OAAO,CAAC,kBAAkB;IAkB1B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC;IAK9D,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC;IAKV,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;IA8CnE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IASnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAStC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAStC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAe5D,OAAO,CAAC,aAAa;YAOP,SAAS;IA4BvB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,iBAAiB;CAQ1B"}
+{"version":3,"file":"composite-files-api.d.ts","sourceRoot":"","sources":["../src/composite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AASnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,OAAO,CAAC,MAAM,CAAe;IAE7B;;;;;;;;OAQG;IACH,YAAY,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,EAE5C;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CASxD;IAID,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,YAAY;IAKpB,yEAAyE;IACzE,OAAO,CAAC,kBAAkB;IAkB1B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAGnE;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAGf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CA4CxE;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAOxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAe3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAW3D;IAID,OAAO,CAAC,aAAa;YAOP,SAAS;IA4BvB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,iBAAiB;CAQ1B"}

package/dist/cow-files-api.d.ts

@@ -0,0 +1,36 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+/** Options for {@link cow}. */
+export interface CowOptions {
+    /**
+     * Filename prefix for per-path whiteout markers, stored in the writable
+     * layer. A whiteout for `/dir/name` lives at `/dir/<prefix>name`.
+     * Defaults to `".wh."`.
+     */
+    whiteoutPrefix?: string;
+    /**
+     * Filename for the opaque-directory marker, stored as a child of a
+     * directory whose base subtree has been deleted. Defaults to `".wh..opq"`.
+     */
+    opaqueName?: string;
+}
+/**
+ * Builds a copy-on-write `FilesApi`: a `writable` layer over a read-only
+ * `base`. Reads fall through to `base`; every write goes to `writable`;
+ * `base` is never mutated. Deletions are persisted as marker files in
+ * `writable` (a per-path whiteout for files, one opaque marker for a deleted
+ * base directory), so they survive over any backend and across restarts.
+ *
+ * @param base The read-only lower layer. Never mutated.
+ * @param writable The upper layer that captures all changes and markers.
+ * @param opts Marker naming overrides (see {@link CowOptions}).
+ * @returns A read/write `FilesApi` composing the two layers.
+ *
+ * @example
+ * ```ts
+ * const fs = cow(releaseFiles, new MemFilesApi());
+ * await fs.write("/a.txt", data); // captured in the writable layer
+ * await fs.remove("/base-only");  // whiteout marker; base untouched
+ * ```
+ */
+export declare function cow(base: FilesApi, writable: FilesApi, opts?: CowOptions): FilesApi;
+//# sourceMappingURL=cow-files-api.d.ts.map

package/dist/cow-files-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cow-files-api.d.ts","sourceRoot":"","sources":["../src/cow-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,QAAQ,EAGT,MAAM,2BAA2B,CAAC;AAGnC,+BAA+B;AAC/B,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAwMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,QAAQ,CAEnF"}

package/dist/esm/index.js

@@ -21,6 +21,25 @@ function normalizePath(filePath) {
 function joinPath(...segments) {
 	return normalizePath(segments.join("/"));
 }
+/**
+* Returns the directory portion of a path.
+*/
+function dirname(path) {
+	const normalized = normalizePath(path);
+	const lastSlash = normalized.lastIndexOf("/");
+	if (lastSlash <= 0) return "/";
+	return normalized.substring(0, lastSlash);
+}
+/**
+* Returns the filename portion of a path.
+*/
+function basename(path, ext) {
+	const normalized = normalizePath(path);
+	const lastSlash = normalized.lastIndexOf("/");
+	const name = lastSlash === -1 ? normalized : normalized.substring(lastSlash + 1);
+	if (ext && name.endsWith(ext)) return name.substring(0, name.length - ext.length);
+	return name;
+}
 //#endregion
 //#region src/composite-files-api.ts
 /**
@@ -257,6 +276,177 @@ var CompositeFilesApi = class {
 	}
 };
 //#endregion
+//#region src/cow-files-api.ts
+/**
+* Copy-on-write view: a writable layer over a read-only `base`. The `base`
+* is **never** mutated — every change (write, delete, move) is recorded in
+* the `writable` layer, using marker files to record deletions.
+*
+* Resolution precedence for any path:
+* 1. a covering whiteout / opaque marker ⇒ the path is absent;
+* 2. otherwise the `writable` layer, if it has the path;
+* 3. otherwise fall through to `base`.
+*
+* Deletions are persisted as marker files inside the writable layer, so they
+* survive across process restarts and work over any `FilesApi` backend.
+* Markers are hidden from `read` / `list` / `stats` / `exists`.
+*
+* Use {@link cow} to construct one.
+*/
+var CowFilesApi = class {
+	base;
+	writable;
+	whiteoutPrefix;
+	opaqueName;
+	constructor(base, writable, opts) {
+		this.base = base;
+		this.writable = writable;
+		this.whiteoutPrefix = opts?.whiteoutPrefix ?? ".wh.";
+		this.opaqueName = opts?.opaqueName ?? ".wh..opq";
+	}
+	whiteoutPath(path) {
+		const p = normalizePath(path);
+		return joinPath(dirname(p), `${this.whiteoutPrefix}${basename(p)}`);
+	}
+	opaquePath(dir) {
+		return joinPath(normalizePath(dir), this.opaqueName);
+	}
+	isMarker(name) {
+		return name.startsWith(this.whiteoutPrefix) || name === this.opaqueName;
+	}
+	*ancestorsInclusive(dir) {
+		let cur = normalizePath(dir);
+		yield cur;
+		while (cur !== "/") {
+			cur = dirname(cur);
+			yield cur;
+		}
+	}
+	async hasDirectWhiteout(path) {
+		return this.writable.exists(this.whiteoutPath(path));
+	}
+	/** True when an opaque marker on `dir` or any ancestor hides base content. */
+	async isBaseContentHidden(dir) {
+		for (const ancestor of this.ancestorsInclusive(dir)) if (await this.writable.exists(this.opaquePath(ancestor))) return true;
+		return false;
+	}
+	/** True when the base version of `path` is hidden by a marker. */
+	async isBaseHidden(path) {
+		if (await this.hasDirectWhiteout(path)) return true;
+		return this.isBaseContentHidden(dirname(normalizePath(path)));
+	}
+	async resolveLayer(path) {
+		if (await this.writable.exists(path)) return "writable";
+		if (await this.isBaseHidden(path)) return "absent";
+		if (await this.base.exists(path)) return "base";
+		return "absent";
+	}
+	/** Removes a covering whiteout marker so a write/mkdir resurrects the path. */
+	async clearWhiteout(path) {
+		const marker = this.whiteoutPath(path);
+		if (await this.writable.exists(marker)) await this.writable.remove(marker);
+	}
+	async *read(path, options) {
+		const layer = await this.resolveLayer(path);
+		if (layer === "writable") yield* this.writable.read(path, options);
+		else if (layer === "base") yield* this.base.read(path, options);
+	}
+	async write(path, content) {
+		await this.clearWhiteout(path);
+		await this.writable.write(path, content);
+	}
+	async mkdir(path) {
+		await this.clearWhiteout(path);
+		await this.writable.mkdir(path);
+	}
+	async stats(path) {
+		const layer = await this.resolveLayer(path);
+		if (layer === "writable") return this.writable.stats(path);
+		if (layer === "base") return this.base.stats(path);
+	}
+	async exists(path) {
+		return await this.resolveLayer(path) !== "absent";
+	}
+	async *list(path, options) {
+		yield* this.listDir(normalizePath(path), options?.recursive ?? false);
+	}
+	async *listDir(dir, recursive) {
+		if ((await this.stats(dir))?.kind !== "directory") return;
+		for (const entry of await this.mergeChildren(dir)) {
+			yield entry;
+			if (recursive && entry.kind === "directory") yield* this.listDir(entry.path, true);
+		}
+	}
+	/** Direct children of `dir`: writable entries win, base entries fill in. */
+	async mergeChildren(dir) {
+		const merged = /* @__PURE__ */ new Map();
+		if ((await this.writable.stats(dir))?.kind === "directory") for await (const entry of this.writable.list(dir)) {
+			if (this.isMarker(entry.name)) continue;
+			merged.set(entry.name, entry);
+		}
+		if (!await this.isBaseContentHidden(dir) && (await this.base.stats(dir))?.kind === "directory") for await (const entry of this.base.list(dir)) {
+			if (merged.has(entry.name)) continue;
+			if (await this.hasDirectWhiteout(entry.path)) continue;
+			merged.set(entry.name, entry);
+		}
+		return [...merged.values()];
+	}
+	async remove(path) {
+		if (await this.resolveLayer(path) === "absent") return false;
+		if (await this.writable.exists(path)) await this.writable.remove(path);
+		const baseStats = await this.base.stats(path);
+		if (baseStats) {
+			const marker = baseStats.kind === "directory" ? this.opaquePath(path) : this.whiteoutPath(path);
+			await this.writable.write(marker, []);
+		}
+		return true;
+	}
+	async move(source, target) {
+		const stats = await this.stats(source);
+		if (!stats) return false;
+		await this.copyInto(source, target, stats);
+		await this.remove(source);
+		return true;
+	}
+	async copy(source, target) {
+		const stats = await this.stats(source);
+		if (!stats) return false;
+		await this.copyInto(source, target, stats);
+		return true;
+	}
+	/** Copies the composite view of `src` into the writable layer at `tgt`. */
+	async copyInto(src, tgt, stats) {
+		if (stats.kind === "file") {
+			await this.write(tgt, this.read(src));
+			return;
+		}
+		await this.mkdir(tgt);
+		for await (const entry of this.list(src)) await this.copyInto(entry.path, joinPath(tgt, entry.name), entry);
+	}
+};
+/**
+* Builds a copy-on-write `FilesApi`: a `writable` layer over a read-only
+* `base`. Reads fall through to `base`; every write goes to `writable`;
+* `base` is never mutated. Deletions are persisted as marker files in
+* `writable` (a per-path whiteout for files, one opaque marker for a deleted
+* base directory), so they survive over any backend and across restarts.
+*
+* @param base The read-only lower layer. Never mutated.
+* @param writable The upper layer that captures all changes and markers.
+* @param opts Marker naming overrides (see {@link CowOptions}).
+* @returns A read/write `FilesApi` composing the two layers.
+*
+* @example
+* ```ts
+* const fs = cow(releaseFiles, new MemFilesApi());
+* await fs.write("/a.txt", data); // captured in the writable layer
+* await fs.remove("/base-only");  // whiteout marker; base untouched
+* ```
+*/
+function cow(base, writable, opts) {
+	return new CowFilesApi(base, writable, opts);
+}
+//#endregion
 //#region src/glob-to-regexp.ts
 /**
 * Compiles a glob pattern into a `RegExp`.
@@ -655,4 +845,127 @@ var GuardedFilesApi = class {
 	}
 };
 //#endregion
-export { CompositeFilesApi, FilteredFilesApi, GuardedFilesApi, globToRegExp, newGlobPathFilter, newPathFilter, newRegexpPathFilter };
+//#region src/overlay-files-api.ts
+/**
+* Read-only union of several `FilesApi` layers. A path is resolved
+* **top → bottom**: the first layer that has it wins for
+* `read` / `stats` / `exists`, and its entry (including `kind`) wins any
+* name clash in `list`. Listings merge and dedupe across every layer.
+*
+* The union never writes — every mutating call throws. Use
+* {@link overlay} to construct one.
+*/
+var OverlayFilesApi = class {
+	layers;
+	constructor(layers) {
+		this.layers = layers;
+	}
+	deny(op, path) {
+		throw new Error(`overlay is read-only (${op}): ${normalizePath(path)}`);
+	}
+	async *read(path, options) {
+		for (const layer of this.layers) if (await layer.exists(path)) {
+			yield* layer.read(path, options);
+			return;
+		}
+	}
+	async stats(path) {
+		for (const layer of this.layers) {
+			const stats = await layer.stats(path);
+			if (stats) return stats;
+		}
+	}
+	async exists(path) {
+		for (const layer of this.layers) if (await layer.exists(path)) return true;
+		return false;
+	}
+	async *list(path, options) {
+		yield* this.listDir(normalizePath(path), options?.recursive ?? false);
+	}
+	async *listDir(dir, recursive) {
+		if ((await this.stats(dir))?.kind !== "directory") return;
+		for (const entry of await this.mergeChildren(dir)) {
+			yield entry;
+			if (recursive && entry.kind === "directory") yield* this.listDir(entry.path, true);
+		}
+	}
+	/** Direct children of `dir`, deduped by name with the topmost layer winning. */
+	async mergeChildren(dir) {
+		const merged = /* @__PURE__ */ new Map();
+		for (const layer of this.layers) {
+			if ((await layer.stats(dir))?.kind !== "directory") continue;
+			for await (const entry of layer.list(dir)) if (!merged.has(entry.name)) merged.set(entry.name, entry);
+		}
+		return [...merged.values()];
+	}
+	async write(path) {
+		this.deny("write", path);
+	}
+	async mkdir(path) {
+		this.deny("mkdir", path);
+	}
+	async remove(path) {
+		return this.deny("remove", path);
+	}
+	async move(source) {
+		return this.deny("move", source);
+	}
+	async copy(source) {
+		return this.deny("copy", source);
+	}
+};
+/**
+* Builds a **read-only** union view over `top` and any number of `lower`
+* layers. Reads resolve top → bottom (first layer that has the path wins);
+* `list` merges and dedupes across all layers with `top` winning a clash
+* (including a file-vs-directory `kind` clash). Every write is denied.
+*
+* @param top The highest-priority layer; its entries shadow the rest.
+* @param lower Additional layers, consulted in order after `top`.
+* @returns A read-only `FilesApi` union.
+*
+* @example
+* ```ts
+* const view = overlay(userFiles, defaultFiles);
+* await view.read("/config.json"); // userFiles if present, else defaultFiles
+* await view.write("/x", data);    // throws (read-only)
+* ```
+*/
+function overlay(top, ...lower) {
+	return new OverlayFilesApi([top, ...lower]);
+}
+//#endregion
+//#region src/read-only-files-api.ts
+/**
+* Wraps a `FilesApi` in a read-only view: every mutating operation
+* (`write`, `mkdir`, `remove`, `move`, `copy`) throws, while reads
+* (`read`, `list`, `stats`, `exists`) pass straight through to `api`.
+*
+* Implemented as a {@link GuardedFilesApi} with a single deny-all guard on
+* the mutating operations, so `move`/`copy` are blocked on either endpoint.
+*
+* @param api The underlying `FilesApi` to expose read-only.
+* @returns A `FilesApi` that never mutates `api`.
+*
+* @example
+* ```ts
+* const ro = readOnly(sourceFiles);
+* await ro.read("/a.txt");          // ok
+* await ro.write("/a.txt", data);   // throws "read-only: /a.txt"
+* ```
+*/
+function readOnly(api) {
+	return new GuardedFilesApi(api, [{
+		operations: [
+			"write",
+			"mkdir",
+			"remove",
+			"move",
+			"copy"
+		],
+		check: () => false,
+		message: "read-only"
+	}]);
+}
+//#endregion
+export { CompositeFilesApi, FilteredFilesApi, GuardedFilesApi, cow, globToRegExp, newGlobPathFilter, newPathFilter, newRegexpPathFilter, overlay, readOnly };

package/dist/filtered-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filtered-files-api.d.ts","sourceRoot":"","sources":["../src/filtered-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAInC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,GAAG,YAAY,EAAE,MAAM,EAAE,GAAG,UAAU,CAUnE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,UAAU,CAQxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,GAAG,UAAU,CAGpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC;;;;;;OAMG;gBACS,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU;cAKpC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIjD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC;IAKrE,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC;IAOV,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;IAQnE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAKnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAM7D"}
+{"version":3,"file":"filtered-files-api.d.ts","sourceRoot":"","sources":["../src/filtered-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAInC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,GAAG,YAAY,EAAE,MAAM,EAAE,GAAG,UAAU,CAUnE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,UAAU,CAQxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,GAAG,UAAU,CAGpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC;;;;;;OAMG;IACH,YAAY,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAGnD;IAED,UAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEvD;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAG1E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAKf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvC;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAMxE;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAGxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK3D;CACF"}

package/dist/guarded-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guarded-files-api.d.ts","sourceRoot":"","sources":["../src/guarded-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC;;;;;;OAMG;gBACS,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE;IAKjD,OAAO,CAAC,UAAU;IAWlB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC;IAK9D,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC;IAKV,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;IAUzE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAKnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKhC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAK7D"}
+{"version":3,"file":"guarded-files-api.d.ts","sourceRoot":"","sources":["../src/guarded-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC;;;;;;OAMG;IACH,YAAY,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,EAGhD;IAED,OAAO,CAAC,UAAU;IAWlB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAGnE;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAGf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAQxE;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAGlD;IAED,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGrC;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3D;CACF"}

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 export { CompositeFilesApi } from "./composite-files-api.js";
+export type { CowOptions } from "./cow-files-api.js";
+export { cow } from "./cow-files-api.js";
 export type { PathFilter } from "./filtered-files-api.js";
 export { FilteredFilesApi, newGlobPathFilter, newPathFilter, newRegexpPathFilter, } from "./filtered-files-api.js";
 export type { GlobToRegExpOptions } from "./glob-to-regexp.js";
 export { globToRegExp } from "./glob-to-regexp.js";
 export { GuardedFilesApi } from "./guarded-files-api.js";
+export { overlay } from "./overlay-files-api.js";
+export { readOnly } from "./read-only-files-api.js";
 export type { FileGuard, FileOperation } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/overlay-files-api.d.ts

@@ -0,0 +1,20 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+/**
+ * Builds a **read-only** union view over `top` and any number of `lower`
+ * layers. Reads resolve top → bottom (first layer that has the path wins);
+ * `list` merges and dedupes across all layers with `top` winning a clash
+ * (including a file-vs-directory `kind` clash). Every write is denied.
+ *
+ * @param top The highest-priority layer; its entries shadow the rest.
+ * @param lower Additional layers, consulted in order after `top`.
+ * @returns A read-only `FilesApi` union.
+ *
+ * @example
+ * ```ts
+ * const view = overlay(userFiles, defaultFiles);
+ * await view.read("/config.json"); // userFiles if present, else defaultFiles
+ * await view.write("/x", data);    // throws (read-only)
+ * ```
+ */
+export declare function overlay(top: FilesApi, ...lower: FilesApi[]): FilesApi;
+//# sourceMappingURL=overlay-files-api.d.ts.map

package/dist/overlay-files-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-files-api.d.ts","sourceRoot":"","sources":["../src/overlay-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,QAAQ,EAGT,MAAM,2BAA2B,CAAC;AA+FnC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAErE"}

package/dist/read-only-files-api.d.ts

@@ -0,0 +1,21 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+/**
+ * Wraps a `FilesApi` in a read-only view: every mutating operation
+ * (`write`, `mkdir`, `remove`, `move`, `copy`) throws, while reads
+ * (`read`, `list`, `stats`, `exists`) pass straight through to `api`.
+ *
+ * Implemented as a {@link GuardedFilesApi} with a single deny-all guard on
+ * the mutating operations, so `move`/`copy` are blocked on either endpoint.
+ *
+ * @param api The underlying `FilesApi` to expose read-only.
+ * @returns A `FilesApi` that never mutates `api`.
+ *
+ * @example
+ * ```ts
+ * const ro = readOnly(sourceFiles);
+ * await ro.read("/a.txt");          // ok
+ * await ro.write("/a.txt", data);   // throws "read-only: /a.txt"
+ * ```
+ */
+export declare function readOnly(api: FilesApi): FilesApi;
+//# sourceMappingURL=read-only-files-api.d.ts.map

package/dist/read-only-files-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-only-files-api.d.ts","sourceRoot":"","sources":["../src/read-only-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAG1D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAQhD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-composite",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "private": false,
   "type": "module",
   "description": "Composite FilesApi with mount points and access guards",
@@ -28,25 +28,25 @@
     "dist",
     "src"
   ],
-  "scripts": {
-    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
-    "test": "vitest run",
-    "lint": "biome lint src tests"
-  },
   "dependencies": {
-    "@statewalker/webrun-files": "workspace:*"
+    "@statewalker/webrun-files": "0.7.0"
   },
   "devDependencies": {
-    "@statewalker/webrun-files-tests": "workspace:*",
-    "@statewalker/webrun-files-mem": "workspace:*",
-    "@types/node": "catalog:",
-    "rimraf": "catalog:",
-    "rolldown": "catalog:",
-    "typescript": "catalog:",
-    "vitest": "catalog:"
+    "@types/node": "^26.2.0",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@statewalker/webrun-files-mem": "0.7.2",
+    "@statewalker/webrun-files-tests": "1.0.0"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome lint src tests"
   }
-}
+}

package/src/cow-files-api.ts

@@ -0,0 +1,244 @@
+import type {
+  FileInfo,
+  FileStats,
+  FilesApi,
+  ListOptions,
+  ReadOptions,
+} from "@statewalker/webrun-files";
+import { basename, dirname, joinPath, normalizePath } from "@statewalker/webrun-files";
+
+/** Options for {@link cow}. */
+export interface CowOptions {
+  /**
+   * Filename prefix for per-path whiteout markers, stored in the writable
+   * layer. A whiteout for `/dir/name` lives at `/dir/<prefix>name`.
+   * Defaults to `".wh."`.
+   */
+  whiteoutPrefix?: string;
+  /**
+   * Filename for the opaque-directory marker, stored as a child of a
+   * directory whose base subtree has been deleted. Defaults to `".wh..opq"`.
+   */
+  opaqueName?: string;
+}
+
+type Layer = "writable" | "base" | "absent";
+
+/**
+ * Copy-on-write view: a writable layer over a read-only `base`. The `base`
+ * is **never** mutated — every change (write, delete, move) is recorded in
+ * the `writable` layer, using marker files to record deletions.
+ *
+ * Resolution precedence for any path:
+ * 1. a covering whiteout / opaque marker ⇒ the path is absent;
+ * 2. otherwise the `writable` layer, if it has the path;
+ * 3. otherwise fall through to `base`.
+ *
+ * Deletions are persisted as marker files inside the writable layer, so they
+ * survive across process restarts and work over any `FilesApi` backend.
+ * Markers are hidden from `read` / `list` / `stats` / `exists`.
+ *
+ * Use {@link cow} to construct one.
+ */
+class CowFilesApi implements FilesApi {
+  private readonly base: FilesApi;
+  private readonly writable: FilesApi;
+  private readonly whiteoutPrefix: string;
+  private readonly opaqueName: string;
+
+  constructor(base: FilesApi, writable: FilesApi, opts?: CowOptions) {
+    this.base = base;
+    this.writable = writable;
+    this.whiteoutPrefix = opts?.whiteoutPrefix ?? ".wh.";
+    this.opaqueName = opts?.opaqueName ?? ".wh..opq";
+  }
+
+  // --- marker helpers ---
+
+  private whiteoutPath(path: string): string {
+    const p = normalizePath(path);
+    return joinPath(dirname(p), `${this.whiteoutPrefix}${basename(p)}`);
+  }
+
+  private opaquePath(dir: string): string {
+    return joinPath(normalizePath(dir), this.opaqueName);
+  }
+
+  private isMarker(name: string): boolean {
+    return name.startsWith(this.whiteoutPrefix) || name === this.opaqueName;
+  }
+
+  private *ancestorsInclusive(dir: string): Iterable<string> {
+    let cur = normalizePath(dir);
+    yield cur;
+    while (cur !== "/") {
+      cur = dirname(cur);
+      yield cur;
+    }
+  }
+
+  private async hasDirectWhiteout(path: string): Promise<boolean> {
+    return this.writable.exists(this.whiteoutPath(path));
+  }
+
+  /** True when an opaque marker on `dir` or any ancestor hides base content. */
+  private async isBaseContentHidden(dir: string): Promise<boolean> {
+    for (const ancestor of this.ancestorsInclusive(dir)) {
+      if (await this.writable.exists(this.opaquePath(ancestor))) return true;
+    }
+    return false;
+  }
+
+  /** True when the base version of `path` is hidden by a marker. */
+  private async isBaseHidden(path: string): Promise<boolean> {
+    if (await this.hasDirectWhiteout(path)) return true;
+    return this.isBaseContentHidden(dirname(normalizePath(path)));
+  }
+
+  private async resolveLayer(path: string): Promise<Layer> {
+    if (await this.writable.exists(path)) return "writable";
+    if (await this.isBaseHidden(path)) return "absent";
+    if (await this.base.exists(path)) return "base";
+    return "absent";
+  }
+
+  /** Removes a covering whiteout marker so a write/mkdir resurrects the path. */
+  private async clearWhiteout(path: string): Promise<void> {
+    const marker = this.whiteoutPath(path);
+    if (await this.writable.exists(marker)) {
+      await this.writable.remove(marker);
+    }
+  }
+
+  // --- FilesApi ---
+
+  async *read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array> {
+    const layer = await this.resolveLayer(path);
+    if (layer === "writable") yield* this.writable.read(path, options);
+    else if (layer === "base") yield* this.base.read(path, options);
+  }
+
+  async write(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<void> {
+    await this.clearWhiteout(path);
+    await this.writable.write(path, content);
+  }
+
+  async mkdir(path: string): Promise<void> {
+    await this.clearWhiteout(path);
+    await this.writable.mkdir(path);
+  }
+
+  async stats(path: string): Promise<FileStats | undefined> {
+    const layer = await this.resolveLayer(path);
+    if (layer === "writable") return this.writable.stats(path);
+    if (layer === "base") return this.base.stats(path);
+    return undefined;
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return (await this.resolveLayer(path)) !== "absent";
+  }
+
+  async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
+    yield* this.listDir(normalizePath(path), options?.recursive ?? false);
+  }
+
+  private async *listDir(dir: string, recursive: boolean): AsyncIterable<FileInfo> {
+    const stats = await this.stats(dir);
+    if (stats?.kind !== "directory") return;
+    for (const entry of await this.mergeChildren(dir)) {
+      yield entry;
+      if (recursive && entry.kind === "directory") {
+        yield* this.listDir(entry.path, true);
+      }
+    }
+  }
+
+  /** Direct children of `dir`: writable entries win, base entries fill in. */
+  private async mergeChildren(dir: string): Promise<FileInfo[]> {
+    const merged = new Map<string, FileInfo>();
+    if ((await this.writable.stats(dir))?.kind === "directory") {
+      for await (const entry of this.writable.list(dir)) {
+        if (this.isMarker(entry.name)) continue;
+        merged.set(entry.name, entry);
+      }
+    }
+    const baseHidden = await this.isBaseContentHidden(dir);
+    if (!baseHidden && (await this.base.stats(dir))?.kind === "directory") {
+      for await (const entry of this.base.list(dir)) {
+        if (merged.has(entry.name)) continue;
+        if (await this.hasDirectWhiteout(entry.path)) continue;
+        merged.set(entry.name, entry);
+      }
+    }
+    return [...merged.values()];
+  }
+
+  async remove(path: string): Promise<boolean> {
+    if ((await this.resolveLayer(path)) === "absent") return false;
+    if (await this.writable.exists(path)) {
+      await this.writable.remove(path);
+    }
+    // Record a whiteout only when the base still carries the path.
+    const baseStats = await this.base.stats(path);
+    if (baseStats) {
+      const marker =
+        baseStats.kind === "directory" ? this.opaquePath(path) : this.whiteoutPath(path);
+      await this.writable.write(marker, []);
+    }
+    return true;
+  }
+
+  async move(source: string, target: string): Promise<boolean> {
+    const stats = await this.stats(source);
+    if (!stats) return false;
+    await this.copyInto(source, target, stats);
+    await this.remove(source);
+    return true;
+  }
+
+  async copy(source: string, target: string): Promise<boolean> {
+    const stats = await this.stats(source);
+    if (!stats) return false;
+    await this.copyInto(source, target, stats);
+    return true;
+  }
+
+  /** Copies the composite view of `src` into the writable layer at `tgt`. */
+  private async copyInto(src: string, tgt: string, stats: FileStats): Promise<void> {
+    if (stats.kind === "file") {
+      await this.write(tgt, this.read(src));
+      return;
+    }
+    await this.mkdir(tgt);
+    for await (const entry of this.list(src)) {
+      await this.copyInto(entry.path, joinPath(tgt, entry.name), entry);
+    }
+  }
+}
+
+/**
+ * Builds a copy-on-write `FilesApi`: a `writable` layer over a read-only
+ * `base`. Reads fall through to `base`; every write goes to `writable`;
+ * `base` is never mutated. Deletions are persisted as marker files in
+ * `writable` (a per-path whiteout for files, one opaque marker for a deleted
+ * base directory), so they survive over any backend and across restarts.
+ *
+ * @param base The read-only lower layer. Never mutated.
+ * @param writable The upper layer that captures all changes and markers.
+ * @param opts Marker naming overrides (see {@link CowOptions}).
+ * @returns A read/write `FilesApi` composing the two layers.
+ *
+ * @example
+ * ```ts
+ * const fs = cow(releaseFiles, new MemFilesApi());
+ * await fs.write("/a.txt", data); // captured in the writable layer
+ * await fs.remove("/base-only");  // whiteout marker; base untouched
+ * ```
+ */
+export function cow(base: FilesApi, writable: FilesApi, opts?: CowOptions): FilesApi {
+  return new CowFilesApi(base, writable, opts);
+}

package/src/index.ts

@@ -1,4 +1,6 @@
 export { CompositeFilesApi } from "./composite-files-api.js";
+export type { CowOptions } from "./cow-files-api.js";
+export { cow } from "./cow-files-api.js";
 export type { PathFilter } from "./filtered-files-api.js";
 export {
   FilteredFilesApi,
@@ -9,4 +11,6 @@ export {
 export type { GlobToRegExpOptions } from "./glob-to-regexp.js";
 export { globToRegExp } from "./glob-to-regexp.js";
 export { GuardedFilesApi } from "./guarded-files-api.js";
+export { overlay } from "./overlay-files-api.js";
+export { readOnly } from "./read-only-files-api.js";
 export type { FileGuard, FileOperation } from "./types.js";

package/src/overlay-files-api.ts

@@ -0,0 +1,121 @@
+import type {
+  FileInfo,
+  FileStats,
+  FilesApi,
+  ListOptions,
+  ReadOptions,
+} from "@statewalker/webrun-files";
+import { normalizePath } from "@statewalker/webrun-files";
+
+/**
+ * Read-only union of several `FilesApi` layers. A path is resolved
+ * **top → bottom**: the first layer that has it wins for
+ * `read` / `stats` / `exists`, and its entry (including `kind`) wins any
+ * name clash in `list`. Listings merge and dedupe across every layer.
+ *
+ * The union never writes — every mutating call throws. Use
+ * {@link overlay} to construct one.
+ */
+class OverlayFilesApi implements FilesApi {
+  private readonly layers: FilesApi[];
+
+  constructor(layers: FilesApi[]) {
+    this.layers = layers;
+  }
+
+  private deny(op: string, path: string): never {
+    throw new Error(`overlay is read-only (${op}): ${normalizePath(path)}`);
+  }
+
+  async *read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array> {
+    for (const layer of this.layers) {
+      if (await layer.exists(path)) {
+        yield* layer.read(path, options);
+        return;
+      }
+    }
+  }
+
+  async stats(path: string): Promise<FileStats | undefined> {
+    for (const layer of this.layers) {
+      const stats = await layer.stats(path);
+      if (stats) return stats;
+    }
+    return undefined;
+  }
+
+  async exists(path: string): Promise<boolean> {
+    for (const layer of this.layers) {
+      if (await layer.exists(path)) return true;
+    }
+    return false;
+  }
+
+  async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
+    yield* this.listDir(normalizePath(path), options?.recursive ?? false);
+  }
+
+  private async *listDir(dir: string, recursive: boolean): AsyncIterable<FileInfo> {
+    const stats = await this.stats(dir);
+    if (stats?.kind !== "directory") return;
+    for (const entry of await this.mergeChildren(dir)) {
+      yield entry;
+      if (recursive && entry.kind === "directory") {
+        yield* this.listDir(entry.path, true);
+      }
+    }
+  }
+
+  /** Direct children of `dir`, deduped by name with the topmost layer winning. */
+  private async mergeChildren(dir: string): Promise<FileInfo[]> {
+    const merged = new Map<string, FileInfo>();
+    for (const layer of this.layers) {
+      if ((await layer.stats(dir))?.kind !== "directory") continue;
+      for await (const entry of layer.list(dir)) {
+        if (!merged.has(entry.name)) merged.set(entry.name, entry);
+      }
+    }
+    return [...merged.values()];
+  }
+
+  async write(path: string): Promise<void> {
+    this.deny("write", path);
+  }
+
+  async mkdir(path: string): Promise<void> {
+    this.deny("mkdir", path);
+  }
+
+  async remove(path: string): Promise<boolean> {
+    return this.deny("remove", path);
+  }
+
+  async move(source: string): Promise<boolean> {
+    return this.deny("move", source);
+  }
+
+  async copy(source: string): Promise<boolean> {
+    return this.deny("copy", source);
+  }
+}
+
+/**
+ * Builds a **read-only** union view over `top` and any number of `lower`
+ * layers. Reads resolve top → bottom (first layer that has the path wins);
+ * `list` merges and dedupes across all layers with `top` winning a clash
+ * (including a file-vs-directory `kind` clash). Every write is denied.
+ *
+ * @param top The highest-priority layer; its entries shadow the rest.
+ * @param lower Additional layers, consulted in order after `top`.
+ * @returns A read-only `FilesApi` union.
+ *
+ * @example
+ * ```ts
+ * const view = overlay(userFiles, defaultFiles);
+ * await view.read("/config.json"); // userFiles if present, else defaultFiles
+ * await view.write("/x", data);    // throws (read-only)
+ * ```
+ */
+export function overlay(top: FilesApi, ...lower: FilesApi[]): FilesApi {
+  return new OverlayFilesApi([top, ...lower]);
+}

package/src/read-only-files-api.ts

@@ -0,0 +1,30 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+import { GuardedFilesApi } from "./guarded-files-api.js";
+
+/**
+ * Wraps a `FilesApi` in a read-only view: every mutating operation
+ * (`write`, `mkdir`, `remove`, `move`, `copy`) throws, while reads
+ * (`read`, `list`, `stats`, `exists`) pass straight through to `api`.
+ *
+ * Implemented as a {@link GuardedFilesApi} with a single deny-all guard on
+ * the mutating operations, so `move`/`copy` are blocked on either endpoint.
+ *
+ * @param api The underlying `FilesApi` to expose read-only.
+ * @returns A `FilesApi` that never mutates `api`.
+ *
+ * @example
+ * ```ts
+ * const ro = readOnly(sourceFiles);
+ * await ro.read("/a.txt");          // ok
+ * await ro.write("/a.txt", data);   // throws "read-only: /a.txt"
+ * ```
+ */
+export function readOnly(api: FilesApi): FilesApi {
+  return new GuardedFilesApi(api, [
+    {
+      operations: ["write", "mkdir", "remove", "move", "copy"],
+      check: () => false,
+      message: "read-only",
+    },
+  ]);
+}