# UnifiedWriter File I/O Policy

UnifiedWriter follows the single-file processing policy.

## Native work file

- Extension: `.uwpsx`
- MIME: `application/x-uwpsx+zip`
- Internal format: ZIP package using JSZip

## Product responsibility

UnifiedWriter parses, edits and generates document data. It does not require a fixed storage destination in the product API.

## Host callback responsibility

Host systems provide these callbacks:

```js
OpenFile(request, context) -> Promise<OpenFileResponse>
SaveFile(request, context) -> Promise<SaveFileResponse>
```

The Host may route those callbacks to Local Disk, App Storage, Google Drive, Backend API or other storage adapters.

## Runtime menu policy

The File menu must expose provider-neutral commands such as `Open...`, `Save`, and `Save As...`. It must not expose fixed destinations such as `This Device`, `App Storage`, or `Google Drive` as product-level submenu items. Those destinations are Host adapter choices.

## Save As

Save As uses a two-phase callback:

1. `SaveFile({ operation:'saveAs', phase:'choose', format:'auto', writableFormats:[...] })`
2. UnifiedWriter resolves the selected filename extension.
3. `SaveFile({ operation:'saveAs', phase:'write', blob, fileName, format })`

Unsupported extensions are rejected before write.

## Export

Export is for external output only, currently DOCX and PDF. It does not change the native file context.


## Image insertion

Image insertion is also a file-open operation from the Control point of view.
The runtime must not prompt for an arbitrary URL or hard-code Local Disk / Google Drive / Backend choices.
`Insert > Image` and the toolbar image button call the Host `OpenFile` callback with `role: image`; the demo resolves that request with a local `<input type="file">` implementation only as a sample Host adapter.


## v5.67.0 Direction separation

`OpenFile(request, context)` / `SaveFile(payload, context)` are Host callbacks. `EditorControl.openFile/saveFile/saveAsFile/exportFile` are Programable Editing Control methods. WorkbenchControl connects the two directions: File menu user action -> Host callback or EditorControl payload API -> Host save callback.


## v5.67.1 Demo File Save Policy Alignment

Demo SaveFile callbacks now follow the single-file policy v1.3 direction split: Workbench/Command obtains or generates a HostSavePayload/v1 with payload.data, then the Demo Host SaveFile callback writes that data by using a local-device download adapter. Demo code does not mark App Storage as the user-facing save destination and does not save without payload.data. Save As dialogs use the package overlay class `uwriter-floating-ui` so file-save UI remains scoped under the v1.10 CSS/Theme contract.


## dev-5.67.2 Demo Local Disk Save update

Demo pages now implement Host-side Local Disk file selection for OpenFile / SaveFile callbacks.  On browsers with the File System Access API, Open uses `showOpenFilePicker()` and Save / Save As uses `showSaveFilePicker()` plus writable file handles.  `HostSavePayload/v1.payload.data` is the only write source.  FileSaver/download is kept only as an unsupported-browser fallback.