# UnifiedControl File I/O Policy / dev-0.3.3

UnifiedControl Designer is now treated as a single-file processing tool for `ContentControl.content`.
The Designer edits a visual component tree and saves it as a native, re-editable content work file.

## Scope

- `ContentControl.content` is the editable main file content.
- The native work file extension is `.uctlx`.
- Native work files are handled by **Save / Save As**, not Export.
- Export is reserved for external-use output such as JSON snapshots.
- Storage destinations are not hard-coded in UnifiedControl. Host code supplies `OpenFile` and `SaveFile` callbacks.

## File menu commands

| Command | Meaning |
|---|---|
| `newContent` | Create an empty content file and reset file context. |
| `openContent` | Request a file through `OpenFile` and replace the current content. |
| `saveContentFile` | Save to the current file context. If no handle exists, delegates to Save As. |
| `saveContentAs` | Choose a destination through `SaveFile`, infer format by extension, then write. |
| `importContent` | Import another content file into the current content without changing file context. |
| `exportContentJson` | Export the current ControlContent as JSON without changing file context. |
| `showContentProperties` | Show file context and content summary in a dialog. |

## Callback contract

UnifiedControl calls Host callbacks in the same style as other single-file iToolkits tools.

```javascript
OpenFile({
  operation: 'open',
  role: 'main',
  accept: ['.uctlx', '.json'],
  mimeTypes: ['application/vnd.itoolkits.unified-control.content+zip', 'application/json'],
  multiple: false,
  context: {}
}, fileContext);
```

```javascript
SaveFile({
  operation: 'saveAs',
  phase: 'choose',
  format: 'auto',
  suggestedName: 'Untitled.uctlx',
  writableFormats: []
}, fileContext);

SaveFile({
  operation: 'saveAs',
  phase: 'write',
  format: 'uctlx',
  extension: '.uctlx',
  mimeType: 'application/vnd.itoolkits.unified-control.content+zip',
  fileName: 'Screen.uctlx',
  blob: nativePackageBlob,
  handle: optionalHostHandle
}, fileContext);
```

## Native file structure

The native `.uctlx` work file is a ZIP package. dev-0.3.3 writes store-only ZIP entries so it does not require JSZip at runtime.

```text
manifest.json
content/control-content.json
scripts/handlers.json
```

`manifest.json` contains package metadata, content version and event-code security policy.
`content/control-content.json` contains the serialized `ControlContent`.
`scripts/handlers.json` extracts component event handler definitions for review and future runtime binding.

## Dirty and file context

`fileContext` is stored in `StateStore` and exposed by `getFileContext()`.
Successful Open / Save / Save As clears `dirty`.
Import and Canvas edits set `dirty=true`.
Export does not clear dirty and does not replace the current file context.


## dev-0.4.0 .uctlx packageVersion 1.0

The native work file remains Save / Save As only. It now includes event handler source definitions:

- `manifest.json`
- `content/control-content.json`
- `scripts/handlers.json`
- `scripts/handlers.js`

`scripts/handlers.js` is included for source inspection and future runtime tooling. The designer does not insert it into the page and does not execute it.

## dev-0.4.1 Save As extension handling

UnifiedControl Designer now supports these Save As extensions:

- `.uctlx`: native UnifiedControl content package.
- `.json`: editable ControlContent JSON.

Export JSON remains available as an external-output operation and does not change the main file context.


## dev-0.4.5 Additions

- `.uctlx` package manifest is now generated as packageVersion 1.1.
- `ContentPackageService.inspectPackage()` reports packageVersion, contentVersion, componentCount, handlerCount, metadata and security policy.
- `exportContentHtml` writes a safe standalone HTML preview and does not change the native file context or dirty state.
- Save As remains extension-based. Native `.uctlx` and editable `.json` are Save / Save As formats; `.html` remains Export.