---
title: "UI contract helpers"
description: "The generated @sota/platform package also exposes build-time contract metadata and one typed descriptor helper. Manifest v3 remains the registration authority."
url: "https://sotaagents.ai/manual/developer-guide/ui-contract-helpers"
generated_by: "sotaagents-ldp"
docs_index: "https://sotaagents.ai/manual/llms.txt"
locale: "en"
---

# UI contract helpers

The generated `@sota/platform` package also exposes build-time contract metadata and one typed descriptor helper. Manifest v3 remains the registration authority.

| Export | Contract |
| --- | --- |
| `PLATFORM_API_VERSION` | The public API version compiled into the runtime. |
| `getAppUiContractHash()` | Returns the exact installed UI declaration hash; it throws outside an installed app runtime. |
| `assertCoreCompatibility(hash)` | Source-compatible no-op retained for early native apps. Exact hashes identify artifacts and are not runtime compatibility gates. |
| `defineAppExtension(descriptor)` | Validates non-empty `id`/`appId` and returns a frozen typed copy. It does not register a contribution omitted from the manifest. |

### Type-only exports

| Group | Types |
| --- | --- |
| Runtime context | `AppPlatformContextValue`, `AppLocale`, `AppTheme`, `AppSurfaceKind`, `AppLightboxImage`. |
| Tool UI | `ToolResultSurfaceProps`, `ToolResultSurfaceValue`, `ToolResultSurfaceState`, `ToolResultSurfaceCommon`, `ToolResultSurfaceExecution`. |
| Descriptors | `AppExtensionDescriptor`, `AppSurfaceSlot`, `NativeModuleSurfaceDescriptor`, `ToolResultSurfaceDescriptor`, `MessageDecorationDescriptor`, `ArtifactSurfaceDescriptor`, `ArtifactSurfaceRenderInput`. |

TypeScript

```
import {
  PLATFORM_API_VERSION,
  defineAppExtension,
  getAppUiContractHash,
} from '@sota/platform';

const descriptor = defineAppExtension({ id: 'reports', appId: 'reports-app' });
console.log(PLATFORM_API_VERSION, getAppUiContractHash(), descriptor.id);
```

TypeScript

```
import type {
  AppPlatformContextValue,
  ToolResultSurfaceProps,
  ToolResultSurfaceState,
} from '@sota/platform';

export type RuntimeIdentity = Pick<AppPlatformContextValue, 'appId' | 'appVersion'>;
export type CalendarSurface = ToolResultSurfaceProps<
  { from: string; to: string },
  { events: unknown[] }
>;
export const terminalStates: readonly ToolResultSurfaceState[] = [
  'output-available', 'output-error', 'output-denied',
];
```

Regenerate `.sota/app-ui-contracts/` with the current CLI instead of copying declaration files between projects or hand-editing them.

> [!WARNING]
> The generated declaration bundle is not an API catalog.
>
> Apps may use the documented `@sota/platform` exports and `useComposer`. Other host declarations that happen to appear under `@sota/core/hooks` are internal unless they receive their own developer API page.