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.

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.