# Public API Contract

UnifiedControl exposes a Host-facing UI Control API. Host code should call `createControl` / `createDesignerControl`, then operate the instance through Control methods instead of directly manipulating internal DOM.

## Stable public entry

- `scripts/main.js`

## Version contract

- productVersion: public product line version.
- developmentVersion: development milestone.
- apiVersion: Host-facing API compatibility version.

## Control class contract

- `Control` is the official base class name.
- `BaseControl` is removed during development and must not be used by Host or application packages.
- Controls always have UI. UI-less responsibilities are Service / Adapter / Registry / Command / Model / Validator / Serializer / Migrator.
- `ContentControl` is the designable composite Control with ControlContent load/save support.
- Workbench is a reusable view/manager owned by Controls. It is not a Control base class.
- Dialog is opened through `control.dialog()` and DialogService. There is no DialogControl.

## dev-0.2.0 Workbench contract

A designer control exposes view operations:

```javascript
control.hideView('palette');
control.showView('palette');
control.toggleView('inspector');
control.exec('resetLayout');
var layout = control.getWorkbenchLayout();
```

The returned layout is a plain object with `views` and `activeViewByRegion`. Host code may store it and pass it back through the `dockLayout` option during initialization.

Internal CSS class names and Dock DOM structure are not part of the public contract.

## dev-0.3.x Designer Canvas contract

Designer-related operations are available through `control.exec(commandId)` and through `control.canvas` for adapter/testing integration.

Recommended Host-facing command examples:

```javascript
control.exec('undo');
control.exec('redo');
control.exec('toggleSnap');
control.exec('toggleSmartGuides');
control.exec('alignLeft');
control.exec('nestIntoContainer');
```

Development adapter APIs exposed on `control.canvas` include:

```javascript
control.canvas.getComponents();
control.canvas.selectMany(['id1', 'id2']);
control.canvas.alignSelected('left');
control.canvas.nestSelectedInto('containerId');
control.canvas.unnestSelected();
```

The component tree uses plain serializable objects with optional `children` arrays. Internal DOM class names remain non-contractual.

## ControlContent contract

UnifiedControl-side designable content uses the `UnifiedControl.ControlContent` format. This is not FormSchema.

```javascript
var content = control.saveContent();
control.loadContent(content);
```

Application packages may adapt ControlContent to their own schema. For example, UnifiedForm should keep FormSchema v1, validation, binding and submit behavior in UnifiedForm and use a FormSchemaAdapter if conversion is needed.


## File I/O callback contract / dev-0.3.3

`OpenFile(request, context)` and `SaveFile(request, context)` are Host-provided callbacks. UnifiedControl sends standardized requests and expects File / Blob / handle responses. Save As uses a choose phase followed by a write phase. Native `.uctlx` is Save / Save As; JSON is an Export example and does not update the native file context.


## dev-0.4.0 Contract Notes

- `ControlContent` version is `1.0` for newly saved content.
- Event handler code is data. `openContent()` and `loadContent()` must not execute scripts.
- Host runtime execution, when introduced, must be guarded by capability approval and sandboxing.
- Property changes and event handler changes must flow through events/commands and update the canvas/content model, not direct DOM mutation.


## dev-0.7.1 Command Contribution Contract

UnifiedControl commands are discoverable through the Control API and can be rendered by either UnifiedControl Workbench views or Host-owned menu / toolbar views. Contribution descriptors are declarative and must not require direct access to UnifiedControl internal DOM.

### Required stability rules

- Legacy command IDs remain supported for existing demos and tests.
- Host-facing aliases use the package prefix `uctl.` by default.
- Package command aliases must not collide with Host common commands such as `host.settings.open`.
- Commands that correspond to common operations may expose `standardCommandId`, for example `file.save` or `edit.undo`.
- Contribution descriptors reference command IDs / aliases and do not own command execution logic.

### Public APIs

- `getCommand(commandId)`
- `getCommands(filter)`
- `getCommandAliases()`
- `getCommandContributions(surface, payload)`
- `registerCommandAlias(aliasId, commandId)`

### Host rendering policy

Hosts may hide UnifiedControl MenuBar / Toolbar with options and render their own surfaces from contributions. The Host must execute commands through `control.exec(commandId, payload)` and must not operate on UnifiedControl internal View DOM.