---
title: "UI contract helpers"
description: "Generated package @sota/platform còn expose metadata của build contract và một typed descriptor helper. Manifest v3 vẫn là authority đăng ký contribution."
url: "https://sotaagents.ai/vi/manual/developer-guide/ui-contract-helpers"
generated_by: "sotaagents-ldp"
docs_index: "https://sotaagents.ai/manual/llms.txt"
locale: "vi"
---

# UI contract helpers

Generated package `@sota/platform` còn expose metadata của build contract và một typed descriptor helper. Manifest v3 vẫn là authority đăng ký contribution.

| Export | Contract |
| --- | --- |
| `PLATFORM_API_VERSION` | Public API version được compile trong runtime. |
| `getAppUiContractHash()` | Trả exact UI declaration hash đã cài; throw ngoài app runtime. |
| `assertCoreCompatibility(hash)` | No-op giữ source compatibility cho native app đời đầu. Exact hash định danh artifact, không phải runtime compatibility gate. |
| `defineAppExtension(descriptor)` | Validate `id`/`appId` không rỗng và trả frozen typed copy. Nó không đăng ký contribution bị thiếu trong manifest. |

### Type-only exports

| Nhóm | Types |
| --- | --- |
| Runtime context | `AppPlatformContextValue`, `AppLocale`, `AppTheme`, `AppSurfaceKind`, `AppLightboxImage`. |
| Tool UI | `ToolResultSurfaceProps`, `ToolResultSurfaceValue`, `ToolResultSurfaceState`, `ToolResultSurfaceCommon`, `ToolResultSurfaceExecution`. |
| Descriptor | `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/` bằng CLI hiện tại; không copy declaration giữa project hoặc sửa tay.

> [!WARNING]
> Generated declaration bundle không phải API catalog.
>
> App được dùng các export `@sota/platform` đã document và `useComposer`. Những host declaration khác vô tình xuất hiện trong `@sota/core/hooks` vẫn là internal nếu chưa có developer API page riêng.