@umbraco-ai/core 1.10.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umbraco-ai/core",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "type": "module",
   "types": "./types/umbraco-ai-public-types.d.ts",
   "files": [
@@ -8,8 +8,8 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@umbraco-cms/backoffice": "^17.3.0",
+    "@umbraco-cms/backoffice": "^17.4.0",
     "chart.js": "^4.5.1",
-    "diff": "^8.0.3"
+    "diff": "^9.0.0"
   }
 }

package/types/umbraco-ai-public-types.d.ts

@@ -24,32 +24,220 @@ import { UmbModalBaseElement } from '@umbraco-cms/backoffice/modal';
 import { UmbModalToken } from '@umbraco-cms/backoffice/modal';
 import { UUIFormControlMixinElement } from '@umbraco-ui/uui-base';
 
-declare interface AiHttpClient {
-    setConfig: (config: any) => unknown;
-    interceptors: {
-        response: {
-            use: (fn: (response: Response, request: Request, opts?: unknown) => Response | Promise<Response>) => unknown;
-        };
+export declare type AiDocumentMetadataModel = {
+    contentTypeKey: string;
+    variants: Array<AiVariantIdModel>;
+    isVariant: boolean;
+    isSegmented: boolean;
+    name?: string | null;
+};
+
+export declare type AiDocumentMetadataModelWritable = {
+    contentTypeKey: string;
+    variants: Array<AiVariantIdModelWritable>;
+    isVariant: boolean;
+    isSegmented: boolean;
+    name?: string | null;
+};
+
+export declare type AiPropertyOperationModel = 'AddItem' | 'RemoveItem' | 'MoveItem' | 'SetValue' | 'ClearValue';
+
+declare type AiPropertyPathSegmentModel = {
+    [key: string]: never;
+};
+
+export declare type AiPropertyValueOperationErrorModel = {
+    code: string;
+    message: string;
+    details?: {
+        [key: string]: JsonNode;
+    } | null;
+};
+
+export declare type AiVariantIdModel = {
+    culture?: string | null;
+    segment?: string | null;
+    readonly isInvariant: boolean;
+};
+
+export declare type AiVariantIdModelWritable = {
+    culture?: string | null;
+    segment?: string | null;
+};
+
+declare type ArrayStyle = 'form' | 'spaceDelimited' | 'pipeDelimited';
+
+declare interface Auth {
+    /**
+     * Which part of the request do we use to send the auth?
+     *
+     * @default 'header'
+     */
+    in?: 'header' | 'query' | 'cookie';
+    /**
+     * Header or query parameter name.
+     *
+     * @default 'Authorization'
+     */
+    name?: string;
+    scheme?: 'basic' | 'bearer';
+    type: 'apiKey' | 'http';
+}
+
+declare type AuthToken = string | undefined;
+
+declare type BodySerializer = (body: unknown) => unknown;
+
+declare type BuildUrlFn = <TData extends {
+    body?: unknown;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    url: string;
+}>(options: TData & Options_2<TData>) => string;
+
+declare type Client = Client_2<RequestFn, Config, MethodFn, BuildUrlFn, SseFn> & {
+    interceptors: Middleware<Request, Response, unknown, ResolvedRequestOptions>;
+};
+
+declare type Client_2<RequestFn = never, Config = unknown, MethodFn = never, BuildUrlFn = never, SseFn = never> = {
+    /**
+     * Returns the final request URL.
+     */
+    buildUrl: BuildUrlFn;
+    getConfig: () => Config;
+    request: RequestFn;
+    setConfig: (config: Config) => Config;
+} & {
+    [K in HttpMethod]: MethodFn;
+} & ([SseFn] extends [never] ? {
+    sse?: never;
+} : {
+    sse: {
+        [K in HttpMethod]: SseFn;
     };
+});
+
+declare interface ClientOptions {
+    baseUrl?: string;
+    responseStyle?: ResponseStyle;
+    throwOnError?: boolean;
+}
+
+declare interface Config<T extends ClientOptions = ClientOptions> extends Omit<RequestInit, 'body' | 'headers' | 'method'>, Config_2 {
+    /**
+     * Base URL for all requests made by this client.
+     */
+    baseUrl?: T['baseUrl'];
+    /**
+     * Fetch API implementation. You can use this option to provide a custom
+     * fetch instance.
+     *
+     * @default globalThis.fetch
+     */
+    fetch?: typeof fetch;
+    /**
+     * Please don't use the Fetch client for Next.js applications. The `next`
+     * options won't have any effect.
+     *
+     * Install {@link https://www.npmjs.com/package/@hey-api/client-next `@hey-api/client-next`} instead.
+     */
+    next?: never;
+    /**
+     * Return the response data parsed in a specified format. By default, `auto`
+     * will infer the appropriate method from the `Content-Type` response header.
+     * You can override this behavior with any of the {@link Body} methods.
+     * Select `stream` if you don't want to parse response data at all.
+     *
+     * @default 'auto'
+     */
+    parseAs?: 'arrayBuffer' | 'auto' | 'blob' | 'formData' | 'json' | 'stream' | 'text';
+    /**
+     * Should we return only data or multiple fields (data, error, response, etc.)?
+     *
+     * @default 'fields'
+     */
+    responseStyle?: ResponseStyle;
+    /**
+     * Throw an error instead of returning it in the response?
+     *
+     * @default false
+     */
+    throwOnError?: T['throwOnError'];
+}
+
+declare interface Config_2 {
+    /**
+     * Auth token or a function returning auth token. The resolved value will be
+     * added to the request payload as defined by its `security` array.
+     */
+    auth?: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken;
+    /**
+     * A function for serializing request body parameter. By default,
+     * {@link JSON.stringify()} will be used.
+     */
+    bodySerializer?: BodySerializer | null;
+    /**
+     * An object containing any HTTP headers that you want to pre-populate your
+     * `Headers` object with.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
+     */
+    headers?: RequestInit['headers'] | Record<string, string | number | boolean | (string | number | boolean)[] | null | undefined | unknown>;
+    /**
+     * The request method.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
+     */
+    method?: Uppercase<HttpMethod>;
+    /**
+     * A function for serializing request query parameters. By default, arrays
+     * will be exploded in form style, objects will be exploded in deepObject
+     * style, and reserved characters are percent-encoded.
+     *
+     * This method will have no effect if the native `paramsSerializer()` Axios
+     * API function is used.
+     *
+     * {@link https://swagger.io/docs/specification/serialization/#query View examples}
+     */
+    querySerializer?: QuerySerializer | QuerySerializerOptions;
+    /**
+     * A function validating request data. This is useful if you want to ensure
+     * the request conforms to the desired shape, so it can be safely sent to
+     * the server.
+     */
+    requestValidator?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function transforming response data before it's returned. This is useful
+     * for post-processing data, e.g., converting ISO strings into Date objects.
+     */
+    responseTransformer?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function validating response data. This is useful if you want to ensure
+     * the response conforms to the desired shape, so it can be safely passed to
+     * the transformers and returned to the user.
+     */
+    responseValidator?: (data: unknown) => Promise<unknown>;
 }
 
 /**
- * Configures a generated hey-api client with the backoffice auth callback
- * and attaches a silent 401 recovery interceptor.
+ * Configures a generated hey-api client for authenticated calls to the
+ * Umbraco backoffice Management API.
  *
- * The interceptor calls `authContext.makeRefreshTokenRequest()` on a 401
- * and retries the request once. This is a workaround for CMS issue
- * https://github.com/umbraco/Umbraco-CMS/issues/22647 — the default
- * `UmbApiInterceptorController.bindDefaultInterceptors` is unusable from
- * third-party entry-point hosts because its `UmbAuthSignalerContext`
- * ends up scoped below `umb-app` and emissions never reach `UmbAuthContext`.
+ * Delegates to `authContext.configureClient(client)`, which:
+ * - Sets `baseUrl`, `credentials: 'include'`, and an `auth` callback that
+ *   gates each request on `#ensureTokenReady` (inline refresh + cross-tab
+ *   Web Lock coordination).
+ * - Binds the default response interceptors (401 retry, 403 handling,
+ *   error normalization, server notifications) with the auth context's
+ *   own host so the `UmbAuthSignalerContext` is registered at `umb-app`
+ *   and emissions reach `UmbAuthContext` correctly.
  *
  * @param host The entry point's `host` parameter (`UmbElement`).
  * @param client The generated hey-api client to configure.
  * @returns A Promise that resolves once auth is configured on the client.
  * @public
  */
-export declare function configureAiClient(host: UmbElement, client: AiHttpClient): Promise<void>;
+export declare function configureAiClient(host: UmbElement, client: unknown): Promise<void>;
 
 export declare const coreClientReady: Promise<void>;
 
@@ -101,6 +289,8 @@ declare type EntityVersionResponseModel = {
     changeDescription?: string | null;
 };
 
+declare type ErrInterceptor<Err, Res, Req, Options> = (error: Err, response: Res, request: Req, options: Options) => Err | Promise<Err>;
+
 export declare function formatDateTime(input: string | Date, locale?: string): string;
 
 /**
@@ -111,6 +301,57 @@ export declare function formatDateTime(input: string | Date, locale?: string): s
  */
 export declare function hasEntityAdapter(entityType: string): boolean;
 
+declare type HttpMethod = 'connect' | 'delete' | 'get' | 'head' | 'options' | 'patch' | 'post' | 'put' | 'trace';
+
+declare class Interceptors<Interceptor> {
+    fns: Array<Interceptor | null>;
+    clear(): void;
+    eject(id: number | Interceptor): void;
+    exists(id: number | Interceptor): boolean;
+    getInterceptorIndex(id: number | Interceptor): number;
+    update(id: number | Interceptor, fn: Interceptor): number | Interceptor | false;
+    use(fn: Interceptor): number;
+}
+
+declare type InvokeData = {
+    body?: PropertyValueOperationRequestModelWritable;
+    path?: never;
+    query?: never;
+    url: '/umbraco/ai/management/api/v1/property-value-operation';
+};
+
+declare type InvokeErrors = {
+    /**
+     * Bad Request
+     */
+    400: unknown;
+    /**
+     * The resource is protected and requires an authentication token
+     */
+    401: unknown;
+};
+
+declare type InvokeResponses = {
+    /**
+     * OK
+     */
+    200: PropertyValueOperationResponseModel;
+};
+
+declare type JsonNode = {
+    options?: JsonNodeOptions | null;
+    parent?: JsonNode | null;
+    root: JsonNode;
+};
+
+declare type JsonNodeOptions = {
+    propertyNameCaseInsensitive: boolean;
+};
+
+declare type JsonNodeWritable = {
+    [key: string]: never;
+};
+
 /**
  * Manifest for entity adapter extensions.
  */
@@ -124,6 +365,27 @@ export declare interface ManifestEntityAdapter extends ManifestBase {
     }>;
 }
 
+/**
+ * Manifest for property value preparer extensions.
+ *
+ * Registered preparers are looked up by `forPropertyEditorSchemaAlias` whenever the entity
+ * adapter is about to call `setPropertyValue`. The first matching preparer's `prepare` is
+ * invoked; editors with no registered preparer use a small default that attempts JSON.parse on
+ * string input and returns the result unchanged.
+ */
+export declare interface ManifestUaiPropertyValuePreparer extends ManifestBase {
+    type: typeof UAI_PROPERTY_VALUE_PREPARER_EXTENSION_TYPE;
+    /**
+     * The CMS property editor schema alias this preparer handles (e.g. `Umbraco.BlockList`).
+     * Matched case-insensitively against the property editor of the value being applied.
+     */
+    forPropertyEditorSchemaAlias: string;
+    /** The preparer API class loader. */
+    api: () => Promise<{
+        default: new () => UaiPropertyValuePreparerApi;
+    }>;
+}
+
 /**
  * Manifest for request context contributor extensions.
  *
@@ -188,6 +450,131 @@ export declare interface ManifestUaiTestFeatureEntityRepository extends Manifest
     };
 }
 
+declare type MethodFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+
+declare interface Middleware<Req, Res, Err, Options> {
+    error: Interceptors<ErrInterceptor<Err, Res, Req, Options>>;
+    request: Interceptors<ReqInterceptor<Req, Options>>;
+    response: Interceptors<ResInterceptor<Res, Req, Options>>;
+}
+
+declare type ObjectStyle = 'form' | 'deepObject';
+
+declare type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
+
+declare type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = Options_2<TData, ThrowOnError, TResponse> & {
+    /**
+     * You can provide a client instance returned by `createClient()` instead of
+     * individual options. This might be also useful if you want to implement a
+     * custom client.
+     */
+    client?: Client;
+    /**
+     * You can pass arbitrary values through the `meta` object. This can be
+     * used to access values that aren't defined as part of the SDK function.
+     */
+    meta?: Record<string, unknown>;
+};
+
+declare type Options_2<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown, TResponseStyle extends ResponseStyle = 'fields'> = OmitKeys<RequestOptions<TResponse, TResponseStyle, ThrowOnError>, 'body' | 'path' | 'query' | 'url'> & ([TData] extends [never] ? unknown : Omit<TData, 'url'>);
+
+export declare type PropertyValueOperationRequestModel = {
+    path: Array<AiPropertyPathSegmentModel>;
+    operation: AiPropertyOperationModel;
+    args?: JsonNode | null;
+    rootValue?: JsonNode | null;
+    rootEditorSchemaAlias: string;
+    documentMetadata: AiDocumentMetadataModel;
+};
+
+export declare type PropertyValueOperationRequestModelWritable = {
+    path: Array<AiPropertyPathSegmentModel>;
+    operation: AiPropertyOperationModel;
+    args?: JsonNodeWritable | null;
+    rootValue?: JsonNodeWritable | null;
+    rootEditorSchemaAlias: string;
+    documentMetadata: AiDocumentMetadataModelWritable;
+};
+
+export declare type PropertyValueOperationResponseModel = {
+    success: boolean;
+    newRootValue?: JsonNode | null;
+    blockKey?: string | null;
+    error?: AiPropertyValueOperationErrorModel | null;
+};
+
+export declare class PropertyValueOperationsService {
+    static invoke<ThrowOnError extends boolean = false>(options?: Options<InvokeData, ThrowOnError>): RequestResult<InvokeResponses, InvokeErrors, ThrowOnError, "fields">;
+}
+
+declare type QuerySerializer = (query: Record<string, unknown>) => string;
+
+declare type QuerySerializerOptions = QuerySerializerOptionsObject & {
+    /**
+     * Per-parameter serialization overrides. When provided, these settings
+     * override the global array/object settings for specific parameter names.
+     */
+    parameters?: Record<string, QuerySerializerOptionsObject>;
+};
+
+declare type QuerySerializerOptionsObject = {
+    allowReserved?: boolean;
+    array?: Partial<SerializerOptions<ArrayStyle>>;
+    object?: Partial<SerializerOptions<ObjectStyle>>;
+};
+
+declare type ReqInterceptor<Req, Options> = (request: Req, options: Options) => Req | Promise<Req>;
+
+declare type RequestFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'> & Pick<Required<RequestOptions<TData, TResponseStyle, ThrowOnError>>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+
+declare interface RequestOptions<TData = unknown, TResponseStyle extends ResponseStyle = 'fields', ThrowOnError extends boolean = boolean, Url extends string = string> extends Config<{
+    responseStyle: TResponseStyle;
+    throwOnError: ThrowOnError;
+}>, Pick<ServerSentEventsOptions<TData>, 'onRequest' | 'onSseError' | 'onSseEvent' | 'sseDefaultRetryDelay' | 'sseMaxRetryAttempts' | 'sseMaxRetryDelay'> {
+    /**
+     * Any body that you want to add to your request.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/fetch#body}
+     */
+    body?: unknown;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    /**
+     * Security mechanism(s) to use for the request.
+     */
+    security?: ReadonlyArray<Auth>;
+    url: Url;
+}
+
+declare type RequestResult<TData = unknown, TError = unknown, ThrowOnError extends boolean = boolean, TResponseStyle extends ResponseStyle = 'fields'> = ThrowOnError extends true ? Promise<TResponseStyle extends 'data' ? TData extends Record<string, unknown> ? TData[keyof TData] : TData : {
+    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
+    request: Request;
+    response: Response;
+}> : Promise<TResponseStyle extends 'data' ? (TData extends Record<string, unknown> ? TData[keyof TData] : TData) | undefined : ({
+    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
+    error: undefined;
+} | {
+    data: undefined;
+    error: TError extends Record<string, unknown> ? TError[keyof TError] : TError;
+}) & {
+    request: Request;
+    response: Response;
+}>;
+
+declare type ResInterceptor<Res, Req, Options> = (response: Res, request: Req, options: Options) => Res | Promise<Res>;
+
+/**
+ * Looks up the preparer registered for a given editor schema alias and runs it. Editors with no
+ * registered preparer fall back to a permissive default that attempts JSON.parse on string input
+ * and returns the result unchanged.
+ */
+export declare function resolveAndPrepareValue(value: unknown, editorAlias: string | undefined, currentValue: unknown): Promise<unknown>;
+
+declare interface ResolvedRequestOptions<TResponseStyle extends ResponseStyle = 'fields', ThrowOnError extends boolean = boolean, Url extends string = string> extends RequestOptions<unknown, TResponseStyle, ThrowOnError, Url> {
+    headers: Headers;
+    serializedBody?: string;
+}
+
 /**
  * Resolve an entity adapter by entity type.
  *
@@ -208,6 +595,98 @@ export declare interface ManifestUaiTestFeatureEntityRepository extends Manifest
  */
 export declare function resolveEntityAdapterByType(entityType: string): Promise<UaiEntityAdapterApi | undefined>;
 
+declare type ResponseStyle = 'data' | 'fields';
+
+declare interface SerializerOptions<T> {
+    /**
+     * @default true
+     */
+    explode: boolean;
+    style: T;
+}
+
+declare type ServerSentEventsOptions<TData = unknown> = Omit<RequestInit, 'method'> & Pick<Config_2, 'method' | 'responseTransformer' | 'responseValidator'> & {
+    /**
+     * Fetch API implementation. You can use this option to provide a custom
+     * fetch instance.
+     *
+     * @default globalThis.fetch
+     */
+    fetch?: typeof fetch;
+    /**
+     * Implementing clients can call request interceptors inside this hook.
+     */
+    onRequest?: (url: string, init: RequestInit) => Promise<Request>;
+    /**
+     * Callback invoked when a network or parsing error occurs during streaming.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @param error The error that occurred.
+     */
+    onSseError?: (error: unknown) => void;
+    /**
+     * Callback invoked when an event is streamed from the server.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @param event Event streamed from the server.
+     * @returns Nothing (void).
+     */
+    onSseEvent?: (event: StreamEvent<TData>) => void;
+    serializedBody?: RequestInit['body'];
+    /**
+     * Default retry delay in milliseconds.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @default 3000
+     */
+    sseDefaultRetryDelay?: number;
+    /**
+     * Maximum number of retry attempts before giving up.
+     */
+    sseMaxRetryAttempts?: number;
+    /**
+     * Maximum retry delay in milliseconds.
+     *
+     * Applies only when exponential backoff is used.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @default 30000
+     */
+    sseMaxRetryDelay?: number;
+    /**
+     * Optional sleep function for retry backoff.
+     *
+     * Defaults to using `setTimeout`.
+     */
+    sseSleepFn?: (ms: number) => Promise<void>;
+    url: string;
+};
+
+declare type ServerSentEventsResult<TData = unknown, TReturn = void, TNext = unknown> = {
+    stream: AsyncGenerator<TData extends Record<string, unknown> ? TData[keyof TData] : TData, TReturn, TNext>;
+};
+
+declare type SseFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<never, TResponseStyle, ThrowOnError>, 'method'>) => Promise<ServerSentEventsResult<TData, TError>>;
+
+declare interface StreamEvent<TData = unknown> {
+    data: TData;
+    event?: string;
+    id?: string;
+    retry?: number;
+}
+
+declare interface TDataShape {
+    body?: unknown;
+    headers?: unknown;
+    path?: unknown;
+    query?: unknown;
+    url: string;
+}
+
 /**
  * Converts a string to camelCase by splitting on separators (-, _, ., spaces).
  * Used for converting tool/scope IDs to localization key format.
@@ -245,6 +724,11 @@ export declare const UAI_ITEM_PICKER_MODAL: UmbModalToken<UaiItemPickerModalData
 
 export declare const UAI_MONITORING_MENU_ALIAS = "Uai.Menu.Monitoring";
 
+/**
+ * Extension type alias for property value preparers.
+ */
+export declare const UAI_PROPERTY_VALUE_PREPARER_EXTENSION_TYPE = "uaiPropertyValuePreparer";
+
 /**
  * Extension type alias for request context contributors.
  */
@@ -557,7 +1041,10 @@ export declare class UaiDocumentAdapter implements UaiEntityAdapterApi {
     getName(workspaceContext: unknown): string;
     /**
      * Get an observable for the document name for reactive updates.
-     * Uses the variants observable which properly tracks name changes.
+     * Uses the variants observable which properly tracks name changes, and
+     * picks the variant whose culture matches what the editor currently has
+     * focused so the AI context selector shows the right name on multi-
+     * variant documents.
      */
     getNameObservable(workspaceContext: unknown): Observable<string | undefined> | undefined;
     /**
@@ -573,7 +1060,12 @@ export declare class UaiDocumentAdapter implements UaiEntityAdapterApi {
     /**
      * Serialize document for LLM context.
      * Uses structure to get all properties, then merges with values.
-     * Only includes TextBox and TextArea properties for now.
+     *
+     * Multi-variant content: `getValues()` returns one entry per
+     * (alias, culture, segment). We pick the entry that matches the variant
+     * the editor currently has focused, falling back to the invariant entry
+     * for properties that don't vary, so prompt template variables like
+     * `{{header}}` resolve to the active culture's value.
      */
     serializeForLlm(workspaceContext: unknown): Promise<UaiSerializedEntity>;
     /**
@@ -583,6 +1075,19 @@ export declare class UaiDocumentAdapter implements UaiEntityAdapterApi {
      * Only supports text-based properties (TextBox, TextArea) for now.
      */
     applyValueChange(workspaceContext: unknown, change: UaiValueChange): Promise<UaiValueChangeResult>;
+    /**
+     * Persist staged changes to the document (equivalent to clicking Save).
+     * Delegates to the workspace's `requestSubmit()`; any validation failure thrown by the
+     * workspace is converted into a structured error so the LLM can read it.
+     */
+    save(workspaceContext: unknown): Promise<UaiPersistResult>;
+    /**
+     * Save the document and publish it. Resolves the document publishing workspace context as a
+     * sibling of the workspace context (both register against the same host) and delegates to
+     * `saveAndPublish()`. On multi-variant documents this can surface the CMS's variant-picker
+     * modal — same UX as clicking the Save and publish button.
+     */
+    publish(workspaceContext: unknown): Promise<UaiPersistResult>;
     /**
      * Cleanup method required by UmbApi base type.
      * Currently no resources to clean up as the adapter is stateless.
@@ -737,6 +1242,19 @@ export declare interface UaiEntityAdapterApi extends UmbApi {
      * @returns Result indicating success or failure with error message
      */
     applyValueChange?(workspaceContext: unknown, change: UaiValueChange): Promise<UaiValueChangeResult>;
+    /**
+     * Persist the workspace's staged changes (the equivalent of clicking the workspace's Save
+     * button). Optional — entity types that don't own their own save (e.g. blocks, whose changes
+     * save with the parent document) should omit this so the caller can return a clear "not
+     * supported" error.
+     */
+    save?(workspaceContext: unknown): Promise<UaiPersistResult>;
+    /**
+     * Persist the workspace's staged changes and publish them. Optional — only entity types with
+     * a publish concept (documents) implement this; media and other always-live entities should
+     * omit it.
+     */
+    publish?(workspaceContext: unknown): Promise<UaiPersistResult>;
 }
 
 /**
@@ -784,6 +1302,19 @@ export declare class UaiEntityAdapterContext extends UmbControllerBase {
      * @returns Result indicating success or failure with error message
      */
     applyValueChange(change: UaiValueChange): Promise<UaiValueChangeResult>;
+    /**
+     * Persist the currently selected entity's staged changes (equivalent of the user clicking
+     * Save). Returns a structured "not supported" error when the entity type doesn't own a save
+     * action — most commonly when the user has a block workspace selected, since block changes
+     * save with the parent document.
+     */
+    saveSelectedEntity(): Promise<UaiPersistResult>;
+    /**
+     * Persist and publish the currently selected entity. Returns a structured "not supported"
+     * error for entity types without a publish concept (media, blocks) — publishing only applies
+     * to documents.
+     */
+    publishSelectedEntity(): Promise<UaiPersistResult>;
 }
 
 /**
@@ -971,6 +1502,18 @@ export declare class UaiPartialUpdateCommand<TReceiver> extends UaiCommandBase<T
     execute(receiver: TReceiver): void;
 }
 
+/**
+ * Result of a save (or save-and-publish) operation triggered by an AI tool. Adapters convert
+ * exceptions thrown by the underlying workspace into a structured payload so the LLM can read the
+ * error message rather than treat the call as silently successful.
+ */
+declare interface UaiPersistResult {
+    /** Whether persistence completed successfully. */
+    success: boolean;
+    /** Human-readable error message if persistence failed. */
+    error?: string;
+}
+
 export declare type UaiPickableItemModel = {
     value: string;
     label: string;
@@ -1043,6 +1586,38 @@ export declare class UaiProfilePickerElement extends UaiProfilePickerElement_bas
 
 declare const UaiProfilePickerElement_base: HTMLElementConstructor<UmbFormControlMixinElement<string | string[] | undefined>> & typeof UmbLitElement;
 
+/**
+ * Property Value Preparer
+ *
+ * Editor-specific frontend adjustment applied to a property value on its way from an AI tool
+ * (or any caller of `UaiEntityAdapterContext.applyValueChange`) into `workspaceContext.setPropertyValue`.
+ *
+ * Preparers exist because some property editor lit components have frontend-only quirks that the
+ * backend dispatcher can't fix:
+ * - block-shaped editors return pre-built object envelopes that must NOT be re-stringified;
+ * - rich-text expects `{ markup, blocks }` and may receive a bare markup string;
+ * - media picker 3's thumbnail subcomponent doesn't react to in-place `mediaKey` changes, so we
+ *   re-mint the entry's `key` to force lit to re-mount the subcomponent.
+ *
+ * Each preparer owns ALL the editor-specific behavior — including any JSON.parse on string input,
+ * any shape adjustments, and any reactivity workarounds. Preparers are stateless and pure.
+ *
+ * Third parties register a preparer for their own editor's quirks via
+ * `uaiPropertyValuePreparer` extension manifest. Editors with no registered preparer fall back to
+ * a default that attempts JSON.parse on string inputs and returns the result.
+ */
+export declare interface UaiPropertyValuePreparerApi {
+    /**
+     * Adjust a value on its way to `setPropertyValue`.
+     *
+     * @param value The new value being applied (whatever shape the caller produced).
+     * @param currentValue The value currently staged in the workspace, if any. Used by preparers
+     * that need to compare incoming entries to existing ones (e.g. to detect content changes).
+     * @returns The adjusted value to pass through to `setPropertyValue`.
+     */
+    prepare(value: unknown, currentValue: unknown): unknown | Promise<unknown>;
+}
+
 /**
  * Mutable context bag passed to each contributor.
  * Mirrors the backend AIRuntimeContext pattern -- contributors
@@ -1166,6 +1741,14 @@ export declare interface UaiSerializedEntity {
     name: string;
     /** Parent unique when creating a new entity. Undefined for existing entities. */
     parentUnique?: string | null;
+    /**
+     * Active culture the editor was on when the entity was serialized.
+     * Null/undefined for invariant entities. Used by the server to pick the
+     * matching property entry from `data.properties` on multi-variant content.
+     */
+    culture?: string | null;
+    /** Active segment when the entity was serialized. */
+    segment?: string | null;
     /**
      * Free-form entity data as JSON object.
      * Adapters decide the structure based on entity type.
@@ -1175,7 +1758,7 @@ export declare interface UaiSerializedEntity {
      * {
      *   contentType: "blogPost",
      *   properties: [
-     *     { alias: "title", label: "Title", editorAlias: "Umbraco.TextBox", value: "Hello" }
+     *     { alias: "title", label: "Title", editorAlias: "Umbraco.TextBox", value: "Hello", culture: "en-US", segment: null }
      *   ]
      * }
      * ```
@@ -1194,15 +1777,18 @@ export declare interface UaiSerializedEntity {
 
 /**
  * Serialized property for LLM context.
- * @deprecated Entity data is now stored in UaiSerializedEntity.data as free-form JSON.
- * For CMS entities, properties are nested inside the data field.
- * This interface is kept for reference only.
+ * Used as the element type of `UaiSerializedEntity.data.properties` for CMS entities.
+ *
+ * `culture` and `segment` describe which variant this property value belongs to:
+ * `null` means invariant (no culture/segment dimension on the property).
  */
 export declare interface UaiSerializedProperty {
     alias: string;
     label: string;
     editorAlias: string;
     value: unknown;
+    culture: string | null;
+    segment: string | null;
 }
 
 /**