feat: add comprehensive FileSystem observer API types with full MDN spec compliance

[Copilot]

Added complete TypeScript type definitions for the File System Access API observer interfaces to src/fsa/types.ts, implementing the full MDN specification.

New Types Added

FileSystemChangeRecord

Represents a file system change event with comprehensive properties:

• changedHandle: IFileSystemHandle | IFileSystemSyncAccessHandle | null - The changed file system handle (null for "disappeared", "errored", or "unknown" types)
• relativePathComponents: string[] - Path components from the observed directory to the changed handle
• relativePathMovedFrom: string[] | null - Former location path for "moved" type events
• root: IFileSystemHandle | IFileSystemSyncAccessHandle - Reference to the root handle passed to observe()
• type: 'appeared' | 'disappeared' | 'modified' | 'moved' | 'errored' | 'unknown' - Complete set of change types

IFileSystemObserver

Observer interface with constructor signature and methods:

• Constructor with callback function (records, observer) => void
• observe(handle, options?) - Start observing changes to a directory handle
• unobserve(handle) - Stop observing changes to a specific directory handle
• disconnect() - Disconnect and stop all observations

FileSystemObserverObserveOptions

Options interface for the observe method:

• recursive?: boolean - Whether to observe changes recursively in subdirectories

Implementation Details

• Full compliance with MDN File System Access API specification
• Support for both user-observable file system and Origin Private File System (OPFS) with IFileSystemSyncAccessHandle
• Proper nullable types for handles based on event types
• Complete JSDoc documentation with MDN references
• Constructor typing enables proper instantiation: new FileSystemObserver(callback)

These types enable future implementation of file system watching functionality for the watchFile, unwatchFile, and watch methods in FsaNodeFs.

Fixes #1170.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[streamich]

Prefix it with I

Suggested change

	export interface FileSystemObserver {
	export interface IFileSystemObserver {

The observer also needs its constructor to be typed:

js

Copy
const observer = new FileSystemObserver(callback);
The [callback function](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemObserver/FileSystemObserver#callback) body can be specified to return and process file change observations in any way you want:

js

Copy
const callback = (records, observer) => {
  for (const record of records) {
    console.log("Change detected:", record);
    const reportContent = `Change observed to ${record.changedHandle.kind} ${record.changedHandle.name}. Type: ${record.type}.`;
    sendReport(reportContent); // Some kind of user-defined reporting function
  }

  observer.disconnect();
};

[Copilot]

Updated interface name to IFileSystemObserver and added constructor signature with callback function as specified in the MDN documentation. Changes implemented in commit 38e2f13.

[streamich]

This interface is lacking types, see docs:

[Instance properties](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#instance_properties)
[changedHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#changedhandle)
A reference to the file system handle that the change was observed on.

For the user-observable file system, this can be a [FileSystemFileHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle) or a [FileSystemDirectoryHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle).
For the [Origin Private File System](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS), it can be a [FileSystemFileHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle), a [FileSystemDirectoryHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle), or a [FileSystemSyncAccessHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemSyncAccessHandle).
This property will be null for records with a "disappeared", "errored", or "unknown" type.

[relativePathComponents](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#relativepathcomponents)
An array containing the path components that make up the relative file path from the root to the changedHandle, including the changedHandle filename.

[relativePathMovedFrom](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#relativepathmovedfrom)
An array containing the path components that make up the relative file path from the root to the changedHandle's former location, in the case of observations with a "moved" type. If the type is not "moved", this property will be null.

[root](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#root)
A reference to the root file system handle, that is, the one passed to the observe() call that started the observation. Again, this can be a [FileSystemFileHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle), [FileSystemDirectoryHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle), or [FileSystemSyncAccessHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemSyncAccessHandle).

[type](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#type)
A string representing the type of change that was observed. Possible values are:

[appeared](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#appeared)
The file or directory was created or moved into the root file structure.

[disappeared](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#disappeared)
The file or directory was deleted or moved out of the root file structure. To find out which file or directory disappeared, you can query the relativePathComponents property.

[errored](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#errored)
An error state occurred in the observed directory. This can result when:

The observation is no longer valid. This can occur when the observed handle (that is, the root of the observation) is deleted or moved. In this case, a "disappeared" observation will be recorded, followed by an "errored" observation. In such cases, you may wish to stop observing the file system using [FileSystemObserver.disconnect()](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemObserver/disconnect).
The maximum limit of per-origin observations is reached. This limit is dependent on the operating system and not known beforehand. If this happens, the site may decide to retry, though there's no guarantee that the operating system will have freed up enough resources.
Permission to access the directory or file handle is removed.
[modified](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#modified)
The file or directory was modified.

[moved](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#moved)
The file or directory was moved within the root file structure.

Note: On Windows, "moved" observations aren't supported between directories. They are reported as a "disappeared" observation in the source directory and an "appeared" observation in the destination directory.

[unknown](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#unknown)
Indicates that some observations were missed. If you wish to find out information on what changed in the missed observations, you could fall back to polling the observed directory.

[Copilot]

Added all missing properties from the MDN spec: relativePathMovedFrom, root, nullable changedHandle, and complete type values including "errored", "moved", and "unknown". Also added support for IFileSystemSyncAccessHandle for OPFS compatibility. Changes implemented in commit 38e2f13.

[streamich]

@copilot pls