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 しません。

生成 declaration bundle は API catalog ではありません。

App が利用できるのは文書化された @sota/platform export と useComposer です。@sota/core/hooks に偶然含まれる他の host declaration は、専用 developer API page がない限り internal です。