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.

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.