Document State Management

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• README.en.md
• CONTRIBUTING.md
• orca.yaml
• SECURITY.md
• CODE_OF_CONDUCT.md

Document State Management in OpenHWP is centered on a decoupled architecture that separates the platform-specific desktop shell from the core document engine. The system leverages the rhwp engine (built with Rust and WebAssembly) to handle document parsing and rendering, while the desktop shell, built with Deno desktop, manages the lifecycle of document data and user interactions.

The primary goal of this management system is to provide a unified way to handle .hwp and .hwpx files across macOS, Windows, and Linux without requiring native office suites. By utilizing the File System Access API, OpenHWP maintains a bridge between the local file system and the web-based rendering environment within the desktop webview.

Sources: README.en.md:5-13, README.md:5-13

Core Architectural Components

OpenHWP's state management is divided into two distinct layers: the Desktop Shell (platform-specific) and the Document Engine (core logic).

Platform Shell (Deno Desktop)

The shell is responsible for the native environment, including window management, native menus, and file system orchestration. It uses the deno desktop runtime and the Chromium-based CEF (Chromium Embedded Framework) backend to ensure consistent rendering and access to modern web APIs.

Document Engine (rhwp)

The document engine is loaded as WebAssembly through npm packages. It is not compiled directly into the shell, allowing for modular updates and a clean separation of concerns.

• @rhwp/core: Used for viewing, parsing, and rendering document pages to SVG.
• @rhwp/editor: Used for full editor UI capabilities, typically embedded as an iframe.

Sources: README.en.md:15-26, README.md:15-26

The following diagram illustrates the relationship between the Deno desktop shell and the rhwp engine:

Data Persistence and File Handling

OpenHWP utilizes the standard File System Access API to manage document state between the application and the local disk. Because the app is served from a secure context (localhost), it can directly use browser-standard methods to open and save files.

Open and Read Flow

1. Picker Initialization: The window.showOpenFilePicker method is called, restricted to .hwp and .hwpx types.
2. Handle Acquisition: The application receives a FileSystemFileHandle.
3. Data Extraction: The file content is read into a Uint8Array.
4. Engine Initialization: The bytes are passed to the HwpDocument class within the @rhwp/core engine.

Save and Write Flow

The application maintains the FileSystemFileHandle obtained during the "Open" phase. This allows the application to write data back to the same file without prompting the user for a location again, ensuring a seamless "Save" experience.

Sources: README.en.md:41-53, README.md:41-53

Component Roles and Interfaces

Component	Responsibility	Relevant Package/API
Viewer	Page rendering to SVG for display	@rhwp/core
Editor	Full UI for document manipulation	@rhwp/editor
File Picker	OS-native file selection via web standards	File System Access API
Backend	Cross-platform rendering consistency	CEF (Chromium)
Desktop Shell	Native menus, windows, and serving	Deno desktop

Sources: README.en.md:16-40, README.md:16-40

Document Initialization Code Snippet

The following implementation pattern is used to initialize the document state within the viewer:

// Initialization of @rhwp/core viewer
import init, { HwpDocument } from "@rhwp/core";

async function loadDocument(bytes) {
  await init();
  const doc = new HwpDocument(bytes);
  // Render the first page (index 0) to SVG
  document.querySelector("#viewer").innerHTML = doc.renderPageSvg(0);
}

Sources: README.en.md:30-34, README.md:30-34

Development and Lifecycle Management

Document management features are developed through a standardized Deno-based workflow. The project enforces strict linting and testing to ensure the integrity of the document state transitions.

• Toolchain: Single Deno toolchain (version ≥ 2.9.0).
• Workflow: deno lint and deno test are baseline requirements for contributions.
• Automation: Tasks such as dependency caching are managed via deno install and orca.yaml for worktree setups.

Sources: CONTRIBUTING.md:13-28, orca.yaml:14-17

Conclusion

Document State Management in OpenHWP is a hybrid approach that combines the performance of Rust/WASM via the rhwp engine with the accessibility of modern web APIs like File System Access. By isolating document logic from the desktop shell, the project ensures a cross-platform experience that is both modular and maintainable. The transition from a viewer-only state to a full editor state is currently on the project roadmap, utilizing the FileSystemFileHandle for persistent disk synchronization.

Sources: README.en.md:16-17, README.en.md:57-61