devframe 0.9.0-beta.4 → 0.9.0-beta.5

package/dist/storage-BVuipbGS.mjs

@@ -0,0 +1,137 @@
+import { t as diagnostics } from "./diagnostics-DEuH3P5O.mjs";
+import { createSharedState } from "devframe/utils/shared-state";
+import fs from "node:fs";
+import { dirname } from "pathe";
+import process from "node:process";
+//#region ../../node_modules/.pnpm/perfect-debounce@2.1.0/node_modules/perfect-debounce/dist/index.mjs
+const DEBOUNCE_DEFAULTS = { trailing: true };
+/**
+Debounce functions
+@param fn - Promise-returning/async function to debounce.
+@param wait - Milliseconds to wait before calling `fn`. Default value is 25ms
+@returns A function that delays calling `fn` until after `wait` milliseconds have elapsed since the last time it was called.
+@example
+```
+import { debounce } from 'perfect-debounce';
+const expensiveCall = async input => input;
+const debouncedFn = debounce(expensiveCall, 200);
+for (const number of [1, 2, 3]) {
+console.log(await debouncedFn(number));
+}
+//=> 1
+//=> 2
+//=> 3
+```
+*/
+function debounce(fn, wait = 25, options = {}) {
+	options = {
+		...DEBOUNCE_DEFAULTS,
+		...options
+	};
+	if (!Number.isFinite(wait)) throw new TypeError("Expected `wait` to be a finite number");
+	let leadingValue;
+	let timeout;
+	let resolveList = [];
+	let currentPromise;
+	let trailingArgs;
+	const applyFn = (_this, args) => {
+		currentPromise = _applyPromised(fn, _this, args);
+		currentPromise.finally(() => {
+			currentPromise = null;
+			if (options.trailing && trailingArgs && !timeout) {
+				const promise = applyFn(_this, trailingArgs);
+				trailingArgs = null;
+				return promise;
+			}
+		});
+		return currentPromise;
+	};
+	const debounced = function(...args) {
+		if (options.trailing) trailingArgs = args;
+		if (currentPromise) return currentPromise;
+		return new Promise((resolve) => {
+			const shouldCallNow = !timeout && options.leading;
+			clearTimeout(timeout);
+			timeout = setTimeout(() => {
+				timeout = null;
+				const promise = options.leading ? leadingValue : applyFn(this, args);
+				trailingArgs = null;
+				for (const _resolve of resolveList) _resolve(promise);
+				resolveList = [];
+			}, wait);
+			if (shouldCallNow) {
+				leadingValue = applyFn(this, args);
+				resolve(leadingValue);
+			} else resolveList.push(resolve);
+		});
+	};
+	const _clearTimeout = (timer) => {
+		if (timer) {
+			clearTimeout(timer);
+			timeout = null;
+		}
+	};
+	debounced.isPending = () => !!timeout;
+	debounced.cancel = () => {
+		_clearTimeout(timeout);
+		resolveList = [];
+		trailingArgs = null;
+	};
+	debounced.flush = () => {
+		_clearTimeout(timeout);
+		if (!trailingArgs || currentPromise) return;
+		const args = trailingArgs;
+		trailingArgs = null;
+		return applyFn(this, args);
+	};
+	return debounced;
+}
+async function _applyPromised(fn, _this, args) {
+	return await fn.apply(_this, args);
+}
+//#endregion
+//#region src/node/storage.ts
+function safeJsonParse(text) {
+	return JSON.parse(text, (key, value) => {
+		if (key === "__proto__" || key === "constructor" && value && typeof value === "object" && "prototype" in value) return void 0;
+		return value;
+	});
+}
+function createStorage(options) {
+	const { mergeInitialValue = (initialValue, savedValue) => ({
+		...initialValue,
+		...savedValue
+	}), debounce: debounceTime = 100 } = options;
+	let initialValue = options.initialValue;
+	if (fs.existsSync(options.filepath)) try {
+		const savedValue = safeJsonParse(fs.readFileSync(options.filepath, "utf-8"));
+		initialValue = mergeInitialValue ? mergeInitialValue(options.initialValue, savedValue) : savedValue;
+	} catch (error) {
+		diagnostics.DF0012({
+			filepath: options.filepath,
+			cause: error
+		}, { method: "warn" });
+		initialValue = options.initialValue;
+	}
+	const state = createSharedState({
+		initialValue,
+		enablePatches: false
+	});
+	state.on("updated", debounce((newState) => {
+		try {
+			const dir = dirname(options.filepath);
+			fs.mkdirSync(dir, { recursive: true });
+			const tmp = `${options.filepath}.${process.pid}.tmp`;
+			fs.writeFileSync(tmp, `${JSON.stringify(newState, null, 2)}\n`);
+			fs.renameSync(tmp, options.filepath);
+		} catch (error) {
+			diagnostics.DF0035({
+				filepath: options.filepath,
+				cause: error
+			}, { method: "error" });
+		}
+	}, debounceTime));
+	return state;
+}
+//#endregion
+export { createStorage as t };

package/dist/types/index.d.mts

@@ -1,4 +1,5 @@
-import { $ as RpcStreamingHost, A as DevframeSettings, At as AgentToolProviderHandle, B as DevframeHost, C as DevframeServiceId, Ct as AgentManifest, D as DevframeScopedNodeContext, Dt as AgentTool, E as DevframeServicesRegistry, Et as AgentResourceInput, F as ScopedRpcFn, Ft as EventsMap, G as DevframeDiagnosticsLogger, H as DevframeDefineDiagnosticsOptions, I as ScopedServerFunctions, J as RpcFunctionsHost, K as DevframeNodeRpcSession, L as ScopedSharedStates, M as DevframeSettingsStore, Mt as DevframeAgentHostEvents, N as ScopedBroadcastOptions, Nt as EventEmitter, O as DevframeScopedNodeRpc, Ot as AgentToolInput, P as ScopedClientFunctions, Pt as EventUnsubscribe, Q as RpcStreamingChannelOptions, R as SettingsForNamespace, S as DevframeNodeContext, St as AgentHandle, T as DevframeServicesHost, Tt as AgentResourceContent, U as DevframeDiagnosticsDefinition, V as DevframeStorageScope, W as DevframeDiagnosticsHost, X as RpcSharedStateHost, Y as RpcSharedStateGetOptions, Z as RpcStreamingChannel, _ as ConnectionMeta, a as DevframeDockDefaults, b as DevframeCapabilities, c as DevframeSetupInfo, d as DevframeWsOptions, et as DevframeRpcClientFunctions, f as McpRouteOptions, g as Thenable, h as PartialWithoutId, i as DevframeDeploymentKind, j as DevframeSettingsRegistry, jt as DevframeAgentHost, k as DevframeScopedStreamingHost, kt as AgentToolProvider, l as DevframeSpaOptions, m as EntriesToObject, n as DevframeCliOptions, nt as DevframeRpcSharedStates, o as DevframeDuplicationStrategy, q as RpcBroadcastOptions, r as DevframeDefinition, s as DevframeRuntime, t as DevframeBrowserContext, tt as DevframeRpcServerFunctions, u as DevframeSseOptions, v as ConnectionMetaSse, w as DevframeServiceOf, wt as AgentResource, x as DevframeConnectionConfigsRegistry, y as ConnectionMetaWebsocket, z as DevframeViewHost } from "../devframe-5oblos7I.mjs";
+import { A as ScopedServerFunctions, B as RpcBroadcastOptions, C as DevframeScopedStreamingHost, Ct as AgentToolProviderHandle, D as ScopedBroadcastOptions, Dt as EventUnsubscribe, E as DevframeSettingsStore, Et as EventEmitter, F as DevframeStorageScope, G as RpcStreamingChannelOptions, H as RpcSharedStateGetOptions, I as DevframeDefineDiagnosticsOptions, J as DevframeRpcServerFunctions, K as RpcStreamingHost, L as DevframeDiagnosticsHost, M as SettingsForNamespace, N as DevframeViewHost, O as ScopedClientFunctions, Ot as EventsMap, P as DevframeHost, R as DevframeDiagnosticsLogger, S as DevframeScopedNodeRpc, St as AgentToolProvider, T as DevframeSettingsRegistry, Tt as DevframeAgentHostEvents, U as RpcSharedStateHost, V as RpcFunctionsHost, W as RpcStreamingChannel, Y as DevframeRpcSharedStates, _ as DevframeServiceId, _t as AgentResource, a as DevframeDuplicationStrategy, b as DevframeServicesRegistry, bt as AgentTool, c as DevframeWsOptions, d as ConnectionMeta, f as ConnectionMetaSse, g as DevframeNodeContext, gt as AgentManifest, h as DevframeConnectionConfigsRegistry, ht as AgentHandle, i as DevframeDockDefaults, j as ScopedSharedStates, k as ScopedRpcFn, l as McpRouteOptions, m as DevframeCapabilities, n as DevframeDefinition, o as DevframeSetupInfo, p as ConnectionMetaWebsocket, q as DevframeRpcClientFunctions, r as DevframeDeploymentKind, s as DevframeSseOptions, t as DevframeCliOptions, v as DevframeServiceOf, vt as AgentResourceContent, w as DevframeSettings, wt as DevframeAgentHost, x as DevframeScopedNodeContext, xt as AgentToolInput, y as DevframeServicesHost, yt as AgentResourceInput, z as DevframeNodeRpcSession } from "../devframe-Cfx6doi4.mjs";
 import { g as RpcFunctionAgentOptions } from "../types-Djq7CBXh.mjs";
 import { d as DevframeRpcConnection, f as DevframeRpcConnectionRequest, p as DevframeRpcTransportKind, u as DevframeNodeRpcSessionMeta } from "../ws-server-D1d3QM9f.mjs";
-export { AgentHandle, AgentManifest, AgentResource, AgentResourceContent, AgentResourceInput, AgentTool, AgentToolInput, AgentToolProvider, AgentToolProviderHandle, ConnectionMeta, ConnectionMetaSse, ConnectionMetaWebsocket, DevframeAgentHost, DevframeAgentHostEvents, DevframeBrowserContext, DevframeCapabilities, DevframeCliOptions, DevframeConnectionConfigsRegistry, DevframeDefineDiagnosticsOptions, DevframeDefinition, DevframeDeploymentKind, DevframeDiagnosticsDefinition, DevframeDiagnosticsHost, DevframeDiagnosticsLogger, DevframeDockDefaults, DevframeDuplicationStrategy, DevframeHost, DevframeNodeContext, DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, DevframeRpcClientFunctions, type DevframeRpcConnection, type DevframeRpcConnectionRequest, DevframeRpcServerFunctions, DevframeRpcSharedStates, type DevframeRpcTransportKind, DevframeRuntime, DevframeScopedNodeContext, DevframeScopedNodeRpc, DevframeScopedStreamingHost, DevframeServiceId, DevframeServiceOf, DevframeServicesHost, DevframeServicesRegistry, DevframeSettings, DevframeSettingsRegistry, DevframeSettingsStore, DevframeSetupInfo, DevframeSpaOptions, DevframeSseOptions, DevframeStorageScope, DevframeViewHost, DevframeWsOptions, EntriesToObject, EventEmitter, EventUnsubscribe, EventsMap, McpRouteOptions, PartialWithoutId, RpcBroadcastOptions, type RpcFunctionAgentOptions, RpcFunctionsHost, RpcSharedStateGetOptions, RpcSharedStateHost, RpcStreamingChannel, RpcStreamingChannelOptions, RpcStreamingHost, ScopedBroadcastOptions, ScopedClientFunctions, ScopedRpcFn, ScopedServerFunctions, ScopedSharedStates, SettingsForNamespace, Thenable };
+import { a as StaticAssetsSource, i as RemoteAssetsStore, n as RemoteAssetsProvider, r as RemoteAssetsProviderCustom, t as RemoteAssets } from "../remote-assets-DclsYyoL.mjs";
+export { AgentHandle, AgentManifest, AgentResource, AgentResourceContent, AgentResourceInput, AgentTool, AgentToolInput, AgentToolProvider, AgentToolProviderHandle, ConnectionMeta, ConnectionMetaSse, ConnectionMetaWebsocket, DevframeAgentHost, DevframeAgentHostEvents, DevframeCapabilities, DevframeCliOptions, DevframeConnectionConfigsRegistry, DevframeDefineDiagnosticsOptions, DevframeDefinition, DevframeDeploymentKind, DevframeDiagnosticsHost, DevframeDiagnosticsLogger, DevframeDockDefaults, DevframeDuplicationStrategy, DevframeHost, DevframeNodeContext, DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, DevframeRpcClientFunctions, type DevframeRpcConnection, type DevframeRpcConnectionRequest, DevframeRpcServerFunctions, DevframeRpcSharedStates, type DevframeRpcTransportKind, DevframeScopedNodeContext, DevframeScopedNodeRpc, DevframeScopedStreamingHost, DevframeServiceId, DevframeServiceOf, DevframeServicesHost, DevframeServicesRegistry, DevframeSettings, DevframeSettingsRegistry, DevframeSettingsStore, DevframeSetupInfo, DevframeSseOptions, DevframeStorageScope, DevframeViewHost, DevframeWsOptions, EventEmitter, EventUnsubscribe, EventsMap, McpRouteOptions, RemoteAssets, RemoteAssetsProvider, RemoteAssetsProviderCustom, RemoteAssetsStore, RpcBroadcastOptions, type RpcFunctionAgentOptions, RpcFunctionsHost, RpcSharedStateGetOptions, RpcSharedStateHost, RpcStreamingChannel, RpcStreamingChannelOptions, RpcStreamingHost, ScopedBroadcastOptions, ScopedClientFunctions, ScopedRpcFn, ScopedServerFunctions, ScopedSharedStates, SettingsForNamespace, StaticAssetsSource };

package/dist/utils/events.d.mts

@@ -1,4 +1,4 @@
-import { Ft as EventsMap, Nt as EventEmitter } from "../devframe-5oblos7I.mjs";
+import { Et as EventEmitter, Ot as EventsMap } from "../devframe-Cfx6doi4.mjs";
 //#region src/utils/events.d.ts
 /**
  * Create event emitter.

package/dist/utils/open.d.mts

@@ -1,16 +1,8 @@
 //#region src/utils/open.d.ts
-interface OpenOptions {
-  /**
-   * Resolve only after the launched app exits.
-   *
-   * @default false
-   */
-  wait?: boolean;
-}
 /**
  * Open a URL, file, or other target in its default OS handler
  * (browser for URLs, Finder/Explorer for paths, etc.).
  */
-declare function open(target: string, options?: OpenOptions): Promise<void>;
+declare function open(target: string): Promise<void>;
 //#endregion
-export { OpenOptions, open };
+export { open };

package/dist/utils/open.mjs

@@ -1,2 +1,57 @@
-import { t as open } from "../open-Dz4V4irZ.mjs";
+import fs from "node:fs";
+import process from "node:process";
+import { spawn } from "node:child_process";
+//#region src/utils/open.ts
+/**
+* Launches `command` detached from the current process and resolves once
+* the OS has accepted the spawn (not once the launched app exits) — the
+* same "fire and forget" behavior `open`'s default (`wait: false`) gave us.
+*/
+function spawnDetached(command, args) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			detached: true,
+			stdio: "ignore",
+			windowsHide: true
+		});
+		child.once("error", reject);
+		child.once("spawn", () => {
+			child.unref();
+			resolve();
+		});
+	});
+}
+function isWsl() {
+	if (process.platform !== "linux") return false;
+	try {
+		return fs.readFileSync("/proc/version", "utf-8").toLowerCase().includes("microsoft");
+	} catch {
+		return false;
+	}
+}
+/**
+* Open a URL, file, or other target in its default OS handler
+* (browser for URLs, Finder/Explorer for paths, etc.).
+*/
+async function open(target) {
+	if (process.platform === "darwin") return spawnDetached("open", [target]);
+	if (process.platform === "win32") return spawnDetached("cmd", [
+		"/c",
+		"start",
+		"\"\"",
+		target
+	]);
+	if (isWsl()) try {
+		return await spawnDetached("wslview", [target]);
+	} catch {
+		return spawnDetached("cmd.exe", [
+			"/c",
+			"start",
+			"\"\"",
+			target
+		]);
+	}
+	return spawnDetached("xdg-open", [target]);
+}
+//#endregion
 export { open };

package/dist/utils/remote-assets.d.mts

@@ -0,0 +1,15 @@
+import { a as StaticAssetsSource, i as RemoteAssetsStore } from "../remote-assets-DclsYyoL.mjs";
+//#region src/utils/remote-assets.d.ts
+/**
+ * Normalize a {@link StaticAssetsSource} into something servable: a local
+ * directory (strings pass through; a remote source short-circuits to a
+ * locally installed copy of its package when present) or a caching
+ * {@link RemoteAssetsStore} back-proxy. Remote caches live under
+ * `<projectStorageDir>/.remote-assets/<package>@<version>/`.
+ *
+ * A remote source's `package`/`version` are validated first (`DF0065`) — both
+ * are interpolated into CDN URLs and the cache path.
+ */
+declare function resolveStaticAssetsSource(source: StaticAssetsSource, projectStorageDir: string): string | RemoteAssetsStore;
+//#endregion
+export { resolveStaticAssetsSource };

package/dist/utils/remote-assets.mjs

@@ -0,0 +1,309 @@
+import { t as diagnostics } from "../diagnostics-DEuH3P5O.mjs";
+import { createRequire } from "node:module";
+import { createReadStream, existsSync } from "node:fs";
+import { Buffer } from "node:buffer";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { lookup } from "mrmime";
+import { dirname, extname, join, normalize, sep } from "pathe";
+//#region src/utils/remote-assets.ts
+const MANIFEST_FILENAME = ".manifest.json";
+/** Flatten a jsDelivr (`name`/`files`) or unpkg (`path`/`files`) file tree. */
+function flattenTree(nodes, style) {
+	const out = [];
+	const walk = (list, prefix) => {
+		for (const node of list) if (style === "path") if (node.type === "file") out.push((node.path ?? "").replace(/^\//, ""));
+		else walk(node.files ?? [], "");
+		else if (node.type === "file") out.push(prefix + (node.name ?? ""));
+		else if (node.files) walk(node.files, `${prefix}${node.name}/`);
+	};
+	walk(nodes, "");
+	return out;
+}
+const providers = {
+	jsdelivr: {
+		fileUrl: (pkg, version, filePath) => `https://cdn.jsdelivr.net/npm/${pkg}@${version}/${filePath}`,
+		listFiles: async (pkg, version, fetchImpl) => {
+			const res = await fetchImpl(`https://data.jsdelivr.com/v1/packages/npm/${pkg}@${version}`);
+			if (!res.ok) throw new Error(`HTTP ${res.status} from data.jsdelivr.com`);
+			return flattenTree((await res.json()).files ?? [], "name");
+		}
+	},
+	unpkg: {
+		fileUrl: (pkg, version, filePath) => `https://unpkg.com/${pkg}@${version}/${filePath}`,
+		listFiles: async (pkg, version, fetchImpl) => {
+			const res = await fetchImpl(`https://unpkg.com/${pkg}@${version}/?meta`);
+			if (!res.ok) throw new Error(`HTTP ${res.status} from unpkg.com`);
+			return flattenTree([await res.json()], "path");
+		}
+	}
+};
+function resolveProvider(assets) {
+	const p = assets.provider ?? "jsdelivr";
+	return typeof p === "string" ? {
+		provider: providers[p],
+		name: p
+	} : {
+		provider: p,
+		name: "custom"
+	};
+}
+/**
+* Resolve a locally installed copy of `assets.package` from
+* `assets.resolveFrom`'s dependency graph and return its assets directory,
+* or `undefined` when the package (or directory) is absent. A different
+* installed version warns (`DF0062`); a different major throws (`DF0061`).
+*/
+function resolveInstalled(assets) {
+	if (!assets.resolveFrom) return void 0;
+	let pkgJsonPath;
+	let installed;
+	try {
+		const requireFrom = createRequire(assets.resolveFrom);
+		pkgJsonPath = requireFrom.resolve(`${assets.package}/package.json`);
+		installed = requireFrom(`${assets.package}/package.json`).version;
+	} catch {
+		return;
+	}
+	if (typeof installed !== "string") return void 0;
+	if (installed !== assets.version) {
+		const major = (v) => v.trim().split(".")[0] ?? v;
+		if (major(installed) !== major(assets.version)) throw diagnostics.DF0061({
+			package: assets.package,
+			required: assets.version,
+			installed
+		});
+		diagnostics.DF0062({
+			package: assets.package,
+			required: assets.version,
+			installed
+		});
+	}
+	const dir = join(dirname(pkgJsonPath), assets.path ?? "dist");
+	return existsSync(dir) ? dir : void 0;
+}
+function contentTypeFor(filePath) {
+	const type = lookup(filePath);
+	if (!type) return "application/octet-stream";
+	return type === "text/html" ? "text/html; charset=utf-8" : type;
+}
+/** Clean a request path into a safe package-relative POSIX path, or `null` if it escapes root. */
+function cleanRequestPath(urlPath) {
+	let cleaned;
+	try {
+		cleaned = decodeURIComponent(urlPath || "/");
+	} catch {
+		return null;
+	}
+	cleaned = cleaned.replace(/[?#].*$/, "").replace(/^\/+|\/+$/g, "");
+	const normalized = normalize(cleaned);
+	if (normalized === ".." || normalized.startsWith(`..${sep}`) || normalized.startsWith("/")) return null;
+	return normalized === "." ? "" : normalized;
+}
+/** Candidate files for a request, in order: direct hit, index, `.html`, SPA fallback. */
+function candidatePaths(prefix, cleaned) {
+	const candidates = [];
+	if (cleaned) candidates.push(prefix + cleaned);
+	candidates.push(`${prefix}${cleaned ? `${cleaned}/` : ""}index.html`);
+	if (cleaned && !extname(cleaned)) candidates.push(`${prefix + cleaned}.html`);
+	if (!/\.[a-z0-9]+$/i.test(cleaned) && !candidates.includes(`${prefix}index.html`)) candidates.push(`${prefix}index.html`);
+	return candidates;
+}
+function createStore(assets, cacheDir) {
+	const normalized = {
+		...assets,
+		path: assets.path ?? "dist"
+	};
+	const { provider, name: providerName } = resolveProvider(assets);
+	const fetchImpl = assets.fetch ?? globalThis.fetch;
+	const prefix = `${normalized.path}/`;
+	let manifestPromise;
+	let manifestReported = false;
+	async function loadManifest() {
+		const manifestFile = join(cacheDir, MANIFEST_FILENAME);
+		try {
+			return new Set(JSON.parse(await readFile(manifestFile, "utf8")));
+		} catch {}
+		if (assets.offline || !provider.listFiles) return null;
+		try {
+			const files = await provider.listFiles(normalized.package, normalized.version, fetchImpl);
+			await mkdir(cacheDir, { recursive: true });
+			await writeFile(manifestFile, JSON.stringify(files), "utf8").catch(() => {});
+			return new Set(files);
+		} catch (error) {
+			if (!manifestReported) {
+				manifestReported = true;
+				diagnostics.DF0059({
+					package: normalized.package,
+					version: normalized.version,
+					provider: providerName,
+					reason: errText(error),
+					cause: error
+				});
+			}
+			return null;
+		}
+	}
+	async function serveCached(filePath) {
+		const abs = join(cacheDir, filePath);
+		let size;
+		try {
+			const s = await stat(abs);
+			if (!s.isFile()) return null;
+			size = s.size;
+		} catch {
+			return null;
+		}
+		return new Response(Readable.toWeb(createReadStream(abs)), { headers: {
+			"Content-Type": contentTypeFor(filePath),
+			"Content-Length": String(size),
+			"Cache-Control": "no-store"
+		} });
+	}
+	/** Persist `body` to the cache at `filePath` (tmp + rename); failures warn (`DF0063`). */
+	async function persist(filePath, body) {
+		const target = join(cacheDir, filePath);
+		const tmp = `${target}.${Math.random().toString(36).slice(2)}.tmp`;
+		try {
+			await mkdir(dirname(target), { recursive: true });
+			await writeFile(tmp, Buffer.from(await new Response(body).arrayBuffer()));
+			await rename(tmp, target);
+		} catch (error) {
+			await rm(tmp, { force: true }).catch(() => {});
+			diagnostics.DF0063({
+				filepath: target,
+				reason: errText(error),
+				cause: error
+			});
+		}
+	}
+	/** Fetch `filePath` through the provider: `null` on 404, a `Response` on 200, throws (`DF0060`) otherwise. */
+	async function serveRemote(filePath) {
+		const url = provider.fileUrl(normalized.package, normalized.version, filePath);
+		let res;
+		try {
+			res = await fetchImpl(url);
+		} catch (error) {
+			throw diagnostics.DF0060({
+				url,
+				package: normalized.package,
+				reason: errText(error),
+				cause: error
+			});
+		}
+		if (res.status === 404) {
+			await res.body?.cancel().catch(() => {});
+			return null;
+		}
+		if (!res.ok || !res.body) {
+			await res.body?.cancel().catch(() => {});
+			throw diagnostics.DF0060({
+				url,
+				package: normalized.package,
+				reason: `HTTP ${res.status}`
+			});
+		}
+		const [toClient, toCache] = res.body.tee();
+		persist(filePath, toCache);
+		const length = res.headers.get("content-length");
+		return new Response(toClient, { headers: {
+			"Content-Type": contentTypeFor(filePath),
+			"Cache-Control": "no-store",
+			...length ? { "Content-Length": length } : {}
+		} });
+	}
+	async function serve(urlPath) {
+		const cleaned = cleanRequestPath(urlPath);
+		if (cleaned === null) return null;
+		const candidates = candidatePaths(prefix, cleaned);
+		manifestPromise ??= loadManifest();
+		const manifest = await manifestPromise;
+		if (manifest) {
+			const filePath = candidates.find((c) => manifest.has(c));
+			if (!filePath) return null;
+			return await serveCached(filePath) ?? (assets.offline ? Promise.reject(diagnostics.DF0060({
+				url: filePath,
+				package: normalized.package,
+				reason: "offline: true and the file is not in the cache"
+			})) : serveRemote(filePath));
+		}
+		for (const candidate of candidates) {
+			const cached = await serveCached(candidate);
+			if (cached) return cached;
+		}
+		if (assets.offline) return null;
+		for (const candidate of candidates) {
+			const remote = await serveRemote(candidate);
+			if (remote) return remote;
+		}
+		return null;
+	}
+	async function materialize(targetDir) {
+		const fail = (reason, cause) => {
+			throw diagnostics.DF0064({
+				package: normalized.package,
+				version: normalized.version,
+				reason,
+				cause
+			});
+		};
+		if (!provider.listFiles) fail("the configured provider has no file listing (`listFiles`)");
+		let files;
+		try {
+			files = await provider.listFiles(normalized.package, normalized.version, fetchImpl);
+		} catch (error) {
+			return fail(errText(error), error);
+		}
+		for (const filePath of files.filter((f) => f.startsWith(prefix))) {
+			const target = join(targetDir, filePath.slice(prefix.length));
+			const url = provider.fileUrl(normalized.package, normalized.version, filePath);
+			let res;
+			try {
+				res = await fetchImpl(url);
+				if (!res.ok) throw new Error(`HTTP ${res.status}`);
+			} catch (error) {
+				return fail(`failed to download ${filePath}: ${errText(error)}`, error);
+			}
+			await mkdir(dirname(target), { recursive: true });
+			await writeFile(target, Buffer.from(await res.arrayBuffer()));
+		}
+	}
+	return {
+		assets: normalized,
+		serve,
+		materialize
+	};
+}
+function errText(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+const PACKAGE_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[a-z0-9-]+(?:\.[a-z0-9-]+)*)?(?:\+[a-z0-9-]+(?:\.[a-z0-9-]+)*)?$/i;
+/** Reject a {@link RemoteAssets} with an unsafe package name or version (`DF0065`). */
+function assertValidRemoteAssets(assets) {
+	if (assets.package.length > 214 || !PACKAGE_NAME_RE.test(assets.package)) throw diagnostics.DF0065({
+		field: "package",
+		value: assets.package
+	});
+	if (!VERSION_RE.test(assets.version)) throw diagnostics.DF0065({
+		field: "version",
+		value: assets.version
+	});
+}
+/**
+* Normalize a {@link StaticAssetsSource} into something servable: a local
+* directory (strings pass through; a remote source short-circuits to a
+* locally installed copy of its package when present) or a caching
+* {@link RemoteAssetsStore} back-proxy. Remote caches live under
+* `<projectStorageDir>/.remote-assets/<package>@<version>/`.
+*
+* A remote source's `package`/`version` are validated first (`DF0065`) — both
+* are interpolated into CDN URLs and the cache path.
+*/
+function resolveStaticAssetsSource(source, projectStorageDir) {
+	if (typeof source === "string") return source;
+	assertValidRemoteAssets(source);
+	return resolveInstalled(source) ?? createStore(source, join(projectStorageDir, ".remote-assets", `${source.package.replace(/\//g, "+")}@${source.version}`));
+}
+//#endregion
+export { resolveStaticAssetsSource };

package/dist/utils/serve-static.d.mts

@@ -1,6 +1,12 @@
+import { i as RemoteAssetsStore } from "../remote-assets-DclsYyoL.mjs";
 import { IncomingMessage, ServerResponse } from "node:http";
 import { EventHandler, H3 } from "h3";
 //#region src/utils/serve-static.d.ts
+/**
+ * What the static-serving engine accepts: a local directory, or a resolved
+ * {@link RemoteAssetsStore} back-proxy (from `devframe/utils/remote-assets`).
+ */
+type ServableAssets = string | RemoteAssetsStore;
 interface ServeStaticOptions {
   /** Default: `['index.html']`. */
   indexNames?: string[];
@@ -8,7 +14,9 @@ interface ServeStaticOptions {
   single?: boolean;
 }
 /**
- * h3 event handler that serves files from `dir` with SPA fallback.
+ * h3 event handler that serves files from `source` with SPA fallback — a
+ * local directory, or a {@link RemoteAssetsStore} whose files stream through
+ * the CDN back-proxy into the local cache.
  *
  * Drop-in replacement for `fromNodeMiddleware(sirv(dir, { dev: true, single: true }))`
  * when the surrounding server is an h3 app — no `Cache-Control` beyond
@@ -16,7 +24,7 @@ interface ServeStaticOptions {
  * file extension falls back to `<dir>/index.html` so client-side routing
  * works.
  */
-declare function serveStaticHandler(dir: string, options?: ServeStaticOptions): EventHandler;
+declare function serveStaticHandler(source: ServableAssets, options?: ServeStaticOptions): EventHandler;
 /**
  * Mount {@link serveStaticHandler} on an h3 app at `base`.
  *
@@ -24,7 +32,7 @@ declare function serveStaticHandler(dir: string, options?: ServeStaticOptions):
  * from `event.url.pathname`, so the file resolver sees paths relative to
  * `dir`.
  */
-declare function mountStaticHandler(app: H3, base: string, dir: string, options?: ServeStaticOptions): void;
+declare function mountStaticHandler(app: H3, base: string, source: ServableAssets, options?: ServeStaticOptions): void;
 /**
  * Connect/Express-style Node middleware variant of {@link serveStaticHandler}.
  *
@@ -32,6 +40,6 @@ declare function mountStaticHandler(app: H3, base: string, dir: string, options?
  * Connect stack — avoids forcing the host package to depend on h3 just to
  * adapt an event handler back into Node middleware.
  */
-declare function serveStaticNodeMiddleware(dir: string, options?: ServeStaticOptions): (req: IncomingMessage, res: ServerResponse, next?: (err?: Error) => void) => void;
+declare function serveStaticNodeMiddleware(source: ServableAssets, options?: ServeStaticOptions): (req: IncomingMessage, res: ServerResponse, next?: (err?: Error) => void) => void;
 //#endregion
-export { ServeStaticOptions, mountStaticHandler, serveStaticHandler, serveStaticNodeMiddleware };
+export { ServableAssets, ServeStaticOptions, mountStaticHandler, serveStaticHandler, serveStaticNodeMiddleware };