## dev-0.3.4 Toolbar and command surface note
Toolbar rendering is icon-only. Command labels remain available through hint text and `aria-label`. `addTextbox` and `addPanel` are API commands rather than toolbar commands; components are normally inserted through Palette.

# UnifiedControl API

## Entry

```javascript
require.config({ paths: { UnifiedControl: '<PackageRootUrl>/scripts' } });
require(['UnifiedControl/main'], function (UnifiedControl) {
  var control = UnifiedControl.createDesignerControl({
    container: '#target',
    language: 'ja',
    theme: 'flat',
    snapToGrid: true,
    gridSize: 8
  });
});
```

## Main exports

- `createControl(options)` - default factory for the generic designer Control.
- `createDesignerControl(options)` - creates `UnifiedControlDesignerControl`.
- `createDefaultComponentRegistry()` - returns a registry with Basic and Layout components.
- `Control` - official base class for Host-facing UI Controls.
- `ContentControl` - designable composite Control with `content` load/save support.
- `DesignerControl` - thin designer-specific Control base.
- `UnifiedControlDesignerControl` - generic Control Designer Workbench.
- `CommandRegistry`, `ComponentRegistry`, `ViewRegistry`, `DockLayoutView`, `WorkbenchView`.
- `DialogService`, `UndoRedoService`, `RegressionTestService`.
- `ControlDefinitionService`, `ControlDefinitionSerializer`, `ControlDefinitionValidator`, `ControlDefinitionMigrator`.

`BaseControl` is not exported and the file `scripts/controls/BaseControl.js` does not exist.

## Control API

All Controls are UI Controls and expose the same Host-facing basics:

- `mount(container)`
- `destroy()`
- `exec(commandId, payload)`
- `on(eventName, handler)` / `off(eventName, handler)`
- `emit(eventName, payload)`
- `getState(path, defaultValue)` / `setState(path, value, metadata)`
- `dialog(options)`
- `refresh()` / `resize()` hooks

## ContentControl API

`ContentControl` is the user-control style designable composite Control.

- `content`
- `loadContent(content, options)`
- `saveContent()`
- `serializeContent()`
- `deserializeContent(text, options)`
- `getComponentTree()`
- `setComponentTree(tree, options)`
- `validateContent(content)`
- `markDirty(reason)` / `clearDirty()`

Example:

```javascript
var contentControl = new UnifiedControl.ContentControl({ autoMount: false });
contentControl.setComponentTree([
  { id: 'name1', type: 'textbox', props: { label: 'Name' }, layout: { x: 40, y: 40, width: 160, height: 32 }, children: [] }
]);
var content = contentControl.saveContent();
```

## Designer Control commands

The following commands are available through `control.exec(commandId)` and shared by toolbar, menu and keyboard where applicable.

- `addTextbox`
- `addPanel`
- `deleteSelected`
- `undo`
- `redo`
- `selectAll`
- `toggleSnap`
- `toggleSmartGuides`
- `alignLeft`, `alignTop`, `alignRight`, `alignBottom`
- `distributeHorizontal`, `distributeVertical`
- `sameWidth`, `sameHeight`
- `bringToFront`, `sendToBack`
- `nestIntoContainer`, `unnestSelected`
- `togglePalette`, `toggleOutline`, `toggleInspector`, `toggleEventLog`
- `resetLayout`

## Designer content APIs

DesignerControl can save/load the generic canvas component tree as ControlContent:

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

## Canvas APIs

`control.canvas` is an internal View/Controller owned by the Control, but it is exposed during development for integration tests and future adapter work.

- `addComponent(type, layout)`
- `getComponents()`
- `setComponents(components, options)`
- `findComponent(id)`
- `select(id, append)`
- `selectMany(ids, options)`
- `selectAll()`
- `getSelection()`
- `deleteSelected()`
- `undo()` / `redo()`
- `setSnapEnabled(enabled)` / `toggleSnap()`
- `setSmartGuidesEnabled(enabled)` / `toggleSmartGuides()`
- `alignSelected(edge)`
- `distributeSelected(axis)`
- `makeSelectedSameSize(dimension)`
- `nestSelectedInto(parentId)` / `unnestSelected()`

## Events

- `ready`
- `beforeDestroy`
- `dialogOpened`, `dialogClosed`
- `contentLoaded`, `contentDirtyChanged`
- `canvasModelChanged`
- `canvasSelectionChanged`
- `canvasRendered`
- `canvasHistoryChanged`
- `canvasSnapChanged`
- `canvasSmartGuidesChanged`
- `dockViewVisibilityChanged`
- `dockLayoutReset`
- `beforeCommand`, `afterCommand`, `commandError`


## File I/O API / dev-0.3.3

Designer controls accept `OpenFile` and `SaveFile` callbacks in options. The Control does not own Local Disk / Google Drive / Backend storage UI.

Commands:

- `newContent`
- `openContent`
- `saveContentFile`
- `saveContentAs`
- `importContent`
- `exportContentJson`
- `showContentProperties`

Additional services exported from `scripts/main.js`:

- `FileIoService`
- `ContentPackageService`

`getFileContext()` returns the current file name, format, extension, MIME, Host handle, storage info and dirty state.


## dev-0.4.0 additions

### ControlContentSchema

Exported from `UnifiedControl/main` as `ControlContentSchema`. Describes the native design data edited by the Designer.

### EventHandlerSchema

Exported as `EventHandlerSchema`. Provides `defaultEvents` and `createHandler(options)` helper for event handler definitions.

### PropertyEditorRegistry

Exported as `PropertyEditorRegistry`. Register custom property editor definitions for `text`, `number`, `boolean`, `select`, `lines`, `color`, `expression`, `code`, or application-specific types.

### ScriptSecurityPolicyService

Exported as `ScriptSecurityPolicyService`. Validates stored handler definitions and reports warnings. It does not execute code.

### Events

- `eventHandlerChanged`
- `eventHandlerCleared`
- `scriptSecurityWarning`

### Content package entries

`.uctlx` packageVersion 1.0 contains:

- `manifest.json`
- `content/control-content.json`
- `scripts/handlers.json`
- `scripts/handlers.js` for source inspection only

## dev-0.4.1 additions

### Canvas editing commands

The following commands are registered through `CommandRegistry` and can be invoked by `control.exec(commandId)`:

- `copySelected`
- `cutSelected`
- `pasteClipboard`
- `duplicateSelected`
- `lockSelected`
- `unlockSelected`
- `hideSelected`
- `showSelected`
- `showSafePreview`

### Services

`ContentPreviewService` renders `ControlContent` without executing handler code.

`WorkbenchLayoutService` optionally persists Workbench layout state when Host supplies or enables a storage key.

### Save As behavior

`saveContentAs` uses the selected file extension to choose output generation. `.uctlx` writes the native package. `.json` writes `ControlContent` JSON. Export remains separate and does not update the main file context.


## dev-0.4.5 Runtime / Test Run API

Commands:

- `testRunContent`: render current content as runtime UI in a dialog.
- `stopTestRun`: dispose the active test-run renderer.
- `exportContentHtml`: export safe standalone HTML; event handler code is not embedded for execution.

Exports:

- `RestrictedScriptRunner`
- `EventBindingService`
- `ContentControlRuntimeRenderer`

Options:

- `allowTestRunScriptExecution`: default false. Enables handler execution in Test Run only when explicitly true.
- `testRunExecutionTimeoutMs`: default 1000.


## dev-0.4.6 Event Handler Persistence / Inspection Fix
- Event Handler save now updates component event binding and handler code as one atomic canvas change.
- Inspector Events tab refreshes immediately after Save / Clear so the saved handler can be confirmed without changing selection.
- Added Inspect Content Definition command to show current ControlContent JSON, event bindings, and saved handlers.
- Added regression coverage for handler save confirmation and content serialization.


## dev-0.7.0 Runtime / Form Adapter / Host Integration
- Added ContentRuntimeControl / createRuntimeControl for running saved ControlContent without Designer UI.
- Added DisplayComponents and runtime/designer previews for Table, List, Card, Tree, Menu, Toolbar, HTML Block and Hidden.
- Added FormSchemaAdapter for UnifiedForm migration preparation.
- Added HostIntegrationService and Integration Info.
- Added SecurityAuditService and stronger restricted script execution hardening.
- Added zoom, manual guide, group and ungroup commands on the Designer Canvas.
- Updated .uctlx package manifest to packageVersion 1.2.


## dev-0.7.1 Command Contribution / Runtime Stabilization API

### Command aliases and contribution discovery

UnifiedControl now exposes stable package-prefixed command aliases for Host integration. Legacy command IDs remain executable for compatibility, but Host-owned menu / toolbar composition should prefer aliases such as:

- `uctl.file.new`
- `uctl.file.open`
- `uctl.file.save`
- `uctl.file.saveAs`
- `uctl.edit.undo`
- `uctl.edit.redo`
- `uctl.view.testRun`
- `uctl.host.integrationInfo`

New Control APIs:

- `control.getCommand(commandId)`: returns a command by legacy ID or alias.
- `control.getCommands(filter)`: returns registered commands, optionally filtered by surface / group / capability data.
- `control.getCommandAliases()`: returns alias-to-command mappings.
- `control.getCommandContributions(surface, payload)`: returns declarative menu / toolbar / context contribution descriptors.
- `control.registerCommandAlias(aliasId, commandId)`: lets Host profiles add stable aliases without replacing the original command.

A command may include `standardCommandId` such as `file.save` so multi-package Hosts can map package-specific commands to common Host operations.

### Workbench surface options

`createDesignerControl()` accepts the following display options:

- `showWorkbenchTitle`: default false.
- `showMenuBar`: default true.
- `showToolbar`: default true.
- `commandPrefix`: default `uctl`.
- `hostSurface`: default `workbench`.

Hosts that fully own menu or toolbar UI can set `showMenuBar: false` or `showToolbar: false` and use `getCommandContributions()` to render their own UI.

### Runtime value lifecycle

`ContentRuntimeControl` now emits `runtimeValueChanged` when runtime input / select / textarea / checkbox / radio values change. The current runtime values are also stored in the Control state under `values`. Calling `loadContent(content)` after mount re-renders the runtime surface.

### Runtime safety behavior

Runtime rendering applies disabled / readonly / hidden / locked states to generated DOM. Image URLs are filtered to safe schemes. HTML Block content is escaped by default and sanitized when `allowHtml: true` is explicitly set. Stored script handlers are still never executed on load.