vfs: address code review feedback

- Revert unintended whitespace change in lib/fs.js
- Use JSON.stringify() in documentation examples for consistency
- Add comment in streams.js explaining #openFile error handling
- Document path encoding behavior in overlay mode

Author: mcollina

doc/api/vfs.md

@@ -390,7 +390,17 @@ including `string`, `Buffer`, `TypedArray`, and `DataView` where applicable.
 #### Overlay mode behavior
 
 When overlay mode is enabled, the following behavior applies to `fs` operations
-on mounted paths:
+on mounted paths.
+
+**Path encoding:** The VFS uses UTF-8 encoding for file and directory names
+internally. In overlay mode, path matching is performed using the VFS's UTF-8
+encoding. When falling through to the real file system, paths are passed to
+the native file system APIs which handle encoding according to platform
+conventions (UTF-8 on most Unix systems, UTF-16 on Windows). This means the
+VFS inherits the underlying file system's encoding behavior for paths that
+fall through, while VFS-internal paths always use UTF-8.
+
+**Operation routing:**
 
 * **Read operations** (`readFile`, `readdir`, `stat`, `lstat`, `access`,
   `exists`, `realpath`, `readlink`): Check VFS first. If the path doesn't exist
@@ -768,7 +778,7 @@ const vfs = require('node:vfs');
 
 const myVfs = vfs.create();
 myVfs.mkdirSync('/data');
-myVfs.writeFileSync('/data/config.json', '{}');
+myVfs.writeFileSync('/data/config.json', JSON.stringify({}));
 
 // This works - symlink within VFS
 myVfs.symlinkSync('/data/config.json', '/config');
@@ -797,7 +807,7 @@ const fs = require('node:fs');
 
 const myVfs = vfs.create({ overlay: true });
 myVfs.mkdirSync('/data');
-myVfs.writeFileSync('/data/config.json', '{"source": "vfs"}');
+myVfs.writeFileSync('/data/config.json', JSON.stringify({ source: 'vfs' }));
 myVfs.symlinkSync('/data/config.json', '/data/link');
 myVfs.mount('/app');
 

lib/fs.js

@@ -3207,6 +3207,7 @@ function globSync(pattern, options) {
   return new Glob(pattern, options).globSync();
 }
 
+
 module.exports = fs = {
   appendFile,
   appendFileSync,

lib/internal/vfs/streams.js

@@ -48,7 +48,8 @@ class VirtualReadStream extends Readable {
     this.#pos = start;
     this.#autoClose = options.autoClose !== false;
 
-    // Open the file on next tick so listeners can be attached
+    // Open the file on next tick so listeners can be attached.
+    // Note: #openFile will not throw - if it fails, the stream is destroyed.
     process.nextTick(() => this.#openFile());
   }