# UnifiedControl Framework adoption / v5.66.2

## Purpose

v5.66.2 aligns UnifiedWriter with the iToolkits application development policy v1.9.  Public Host-facing Controls now use UnifiedControl as the common framework dependency.

## Main decisions

- `scripts/controls/editor_control.js` is the formal UnifiedWriter body Control.
- `EditorControl` extends `UnifiedControl.Control`.
- `scripts/controls/workbench_control.js` is the composite Control for standalone or page-embedded workbench use.
- `WorkbenchControl` also inherits `UnifiedControl.Control` through `EditorControl`, but it is a composite surface, not a base class and not a Host app.
- `scripts/controls/legacy_runtime.js` bridges the existing model-first jQuery editor runtime while the internal modules are gradually split into Control / View / Service layers.
- `scripts/main.js` is still the public AMD entry and exports the new classes and factory methods.
- `UnifiedControl` is a required peer package.  It is not copied into the UnifiedWriter ZIP.

## RequireJS setup

The Host or Demo must provide both aliases.

```javascript
require.config({
  paths: {
    'UnifiedControl': 'https://cdn.skylarkjs.com/itoolkits/developments/UnifiedControl/scripts',
    'UnifiedWriter': '<UnifiedWriter package root>/scripts'
  }
});
```

The application package manifest declares:

```json
{
  "requiredPackages": {
    "UnifiedControl": {
      "apiVersion": ">=0.7 <1.0",
      "publicEntry": "scripts/main.js",
      "required": true
    }
  }
}
```

## Public factories

```javascript
require(['UnifiedWriter/main'], function (UnifiedWriter) {
  var editor = UnifiedWriter.createEditorControl({
    container: '#editorFrame',
    mode: 'edit'
  });

  var viewer = UnifiedWriter.createEditorControl({
    container: '#viewerFrame',
    mode: 'view',
    readOnly: true,
    hostProfile: 'oneViewer'
  });

  var workbench = UnifiedWriter.createWorkbenchControl({
    container: '#workbenchFrame',
    showMenuBar: true,
    showToolbar: true
  });
});
```

`createViewerControl()` remains only as a compatibility alias.  New OneViewer integration should use `createEditorControl({ mode:'view', readOnly:true })`.

## Control API

The new Control classes expose the standard Host-facing methods:

- `mount(container)`
- `destroy()`
- `exec(commandId, payload)` / `executeCommand(commandId, payload)`
- `on(eventName, handler)` / `off(eventName, handler)`
- `getState(path)` / `setState(path, value)`
- `dialog(options)`
- `getCommandRegistry(options)`
- `getCommandContributions(surface, options)`
- `getMenuContributions(options)`
- `getToolbarContributions(options)`
- `getContextMenuContributions(options)`
- `getFileCapabilities()`

## Migration note

The existing implementation still contains the mature `UnifiedWriterApp` and `NativeEditorAdapter` runtime inside `scripts/app/unified_writer.js`.  This is intentional for v5.66.2.  The new public Control classes act as a migration shell around the runtime.  Future work should continue moving View / Service / Adapter responsibilities out of the legacy monolith, but Host integrations should already depend on the new Control classes.

## Non-goals

- Do not copy UnifiedControl into this package.
- Do not create `BaseControl` or a `DialogControl` compatibility layer.
- Do not make Workbench a base class.
- Do not move Host routing, Window shell, authentication, page topbar or SEO into UnifiedWriter.

## Verification

- `EditorControl.prototype instanceof UnifiedControl.Control` when loaded with the real UnifiedControl package.
- `WorkbenchControl.prototype instanceof UnifiedControl.Control` by inheritance.
- `PACKAGE_MANIFEST.json` contains `requiredPackages.UnifiedControl`.
- `createEditorControl()` and `createWorkbenchControl()` return Control class instances, not plain objects.
- Command execution still flows through the same writer command IDs and readOnly/view mode guards.