---
title: "UI contract helper"
description: "生成された @sota/platform は build contract metadata と typed descriptor helper も公開します。Manifest v3 が registration authority である点は変わりません。"
url: "https://sotaagents.ai/ja/manual/developer-guide/ui-contract-helpers"
generated_by: "sotaagents-ldp"
docs_index: "https://sotaagents.ai/manual/llms.txt"
locale: "ja"
---

# UI contract helper

生成された `@sota/platform` は build contract metadata と typed descriptor helper も公開します。Manifest v3 が registration authority である点は変わりません。

| Export | Contract |
| --- | --- |
| `PLATFORM_API_VERSION` | Runtime に compile された public API version。 |
| `getAppUiContractHash()` | Installed UI declaration の exact hash。App runtime 外では throw。 |
| `assertCoreCompatibility(hash)` | 初期 native app との source compatibility 用 no-op。Exact hash は artifact identity であり compatibility gate ではありません。 |
| `defineAppExtension(descriptor)` | 非空 `id`/`appId` を検証して frozen typed copy を返します。Manifest にない contribution は登録しません。 |

### Type-only export

| Group | 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',
];
```

`.sota/app-ui-contracts/` は現在の CLI で再生成し、手動編集・別 project から copy しません。

> [!WARNING]
> 生成 declaration bundle は API catalog ではありません。
>
> App が利用できるのは文書化された `@sota/platform` export と `useComposer` です。`@sota/core/hooks` に偶然含まれる他の host declaration は、専用 developer API page がない限り internal です。