File System Access API

The File System Access API is a core architectural component of OpenHWP used for handling document persistence. By leveraging the Chromium-based CEF (Chromium Embedded Framework) backend and serving the application via localhost (a secure context), OpenHWP utilizes standard web-based file APIs to interact with the local file system. This approach eliminates the need for native Deno-side file pickers, simplifying the desktop shell.

The API is primarily responsible for opening .hwp and .hwpx documents, converting them into byte arrays for processing by the rhwp engine, and providing a mechanism to save changes back to the disk. It facilitates a seamless bridge between the web-based UI and the local storage of the host operating system.

Sources: README.en.md:14-16, README.en.md:27-30, README.md:14-16, README.md:27-30

Architecture and Integration

OpenHWP maintains a strict separation between the "document engine" (rhwp) and the "platform shell" (Deno desktop). The File System Access API operates within the webview environment provided by the CEF backend.

Component Relationship

The following diagram illustrates how the File System Access API interacts with other system components to process a document.

The application runs in a secure context at localhost, which enables the use of window.showOpenFilePicker. This allows the application to remain a "thin shell," delegating complex native file operations to the browser engine.

Sources: README.en.md:14-18, README.en.md:27-30, README.md:27-30

Implementation Details

Opening Documents

The API implementation restricts file selection specifically to Korean document formats. Once a user selects a file, the application retrieves a file handle and converts the content into a Uint8Array for the engine.

// Open — restrict the picker to .hwp / .hwpx.
const [handle] = await window.showOpenFilePicker({
  types: [{ accept: { "application/octet-stream": [".hwp", ".hwpx"] } }],
});
const file = await handle.getFile();
const bytes = new Uint8Array(await file.arrayBuffer());

Sources: README.en.md:32-37, README.md:32-37

Saving Documents

Persistence is handled by creating a writable stream from the existing FileSystemFileHandle. Reusing the handle from the initial "Open" operation allows the application to write data back to the disk without prompting the user for a location again.

// Save — reuse the handle from Open to write back without prompting again.
const writable = await handle.createWritable();
await writable.write(bytes);
await writable.close();

Sources: README.en.md:39-42, README.md:39-42

API Workflow

The interaction between the user, the browser-based API, and the document engine follows a specific sequence for document lifecycle management.

Technical Requirements and Roadmap

The File System Access API is central to the project's roadmap, transitioning from a viewer-only implementation to a full editor.

Sources: README.en.md:52-55, README.md:52-55

Dependency and Tooling

While the File System Access API runs in the webview, the overall project lifecycle is managed by the Deno toolchain.

• Runtime: Deno ≥ 2.9.0 (required for deno desktop).
• Backend: CEF (Chromium) must be specified in deno.json via "backend": "cef" to ensure the API is available and consistent across platforms.
• Development: deno task dev is used to run the environment where these APIs are tested.

Sources: CONTRIBUTING.md:12-16, README.en.md:16-17, orca.yaml:14-19

The File System Access API allows OpenHWP to function as a cross-platform desktop application while maintaining the simplicity of a web application. By bypassing the need for native Deno file picker bindings, the project leverages the mature file handling capabilities of the Chromium engine to manage HWP and HWPX documents across macOS, Windows, and Linux.

Sources: README.en.md:6-10, README.en.md:27-30