@kittl/sdk 1.0.0-alpha.1 → 1.0.0-alpha.2

package/dist/editorContentPanel/sdk.d.ts

@@ -56,7 +56,11 @@ declare const ANIMATION_CHANNELS: readonly [
 	"scaleY",
 	"skewX",
 	"skewY",
-	"opacity"
+	"opacity",
+	"offsetDistance",
+	"translateZ",
+	"rotateX",
+	"rotateY"
 ];
 declare const ANIMATION_EASING_NAMES: readonly [
 	"linear",
@@ -65,6 +69,7 @@ declare const ANIMATION_EASING_NAMES: readonly [
 	"ease-out",
 	"ease-in-out"
 ];
+declare const ANIMATION_SHAPE_CHANNEL = "d";
 declare const APP_STATE_SUBSCRIPTION_KEYS: readonly [
 	"selectedObjectsIds",
 	"selectedLayersIds",
@@ -171,9 +176,7 @@ declare const DEFAULT_VALUES$1: {
 	generation?: {
 		meta?: GenerationMeta;
 		generationId?: string;
-		aiArtId? /**
-		 * Cache key to support local history changes without relying on persistence
-		 */: string;
+		aiArtId?: string;
 		generatorKey?: string;
 	};
 };
@@ -264,6 +267,37 @@ declare const GUIDE_DEFAULT_VALUES: {
 	version: string;
 	type: ObjectType.Guide;
 };
+declare const GenerateContentActionOrigin: {
+	readonly COPILOT: "COPILOT";
+	readonly RIGHT_PANEL: "RIGHT_PANEL";
+	readonly LEFT_PANEL: "LEFT_PANEL";
+	readonly MICRO_APP: "MICRO_APP";
+	readonly IMAGE_SETS: "IMAGE_SETS";
+	readonly AI_CHAT: "AI_CHAT";
+	readonly SMARTBOARD: "SMARTBOARD";
+	readonly AI_INPUT_GENERATE_IMAGE: "AI_INPUT_GENERATE_IMAGE";
+	readonly AI_INPUT_REMIX_IMAGE: "AI_INPUT_REMIX_IMAGE";
+	readonly AI_INPUT_GENERATE_VIDEO: "AI_INPUT_GENERATE_VIDEO";
+	readonly AI_INPUT_MICRO_EDITOR_REMIX: "AI_INPUT_MICRO_EDITOR_REMIX";
+	readonly AI_INPUT_MICRO_EDITOR_INPAINT: "AI_INPUT_MICRO_EDITOR_INPAINT";
+	readonly AI_HUB_GENERATE_IMAGE: "AI_HUB_GENERATE_IMAGE";
+	readonly AI_HUB_REMIX_IMAGE: "AI_HUB_REMIX_IMAGE";
+	readonly AI_HUB_GENERATE_VIDEO: "AI_HUB_GENERATE_VIDEO";
+	readonly VIDEOBOARD: "VIDEOBOARD";
+	readonly AGENT: "AGENT";
+	readonly WORKFLOW: "WORKFLOW";
+	readonly AI_HUB_AGENT: "AI_HUB_AGENT";
+	readonly MCP: "MCP";
+	readonly MCP_WORKFLOW: "MCP_WORKFLOW";
+	readonly AI_AGENT: "AI_AGENT";
+	readonly AI_AGENT_CHAT: "AI_AGENT_CHAT";
+	readonly AI_AGENT_CHAT_WEBSITE: "AI_AGENT_CHAT_WEBSITE";
+	readonly MOBILE_APP_GENERATE_IMAGE: "MOBILE_APP_GENERATE_IMAGE";
+	readonly MOBILE_APP_REMIX_IMAGE: "MOBILE_APP_REMIX_IMAGE";
+	readonly MOBILE_APP_GENERATE_VIDEO: "MOBILE_APP_GENERATE_VIDEO";
+	readonly MOBILE_APP_AGENT: "MOBILE_APP_AGENT";
+	readonly AI_AGENT_WORKFLOW: "AI_AGENT_WORKFLOW";
+};
 declare const GenerationStatus: {
 	readonly CREATED: "CREATED";
 	readonly QUEUED: "QUEUED";
@@ -412,6 +446,7 @@ declare const PendingOperation: {
 	readonly UPSCALE: "upscale";
 	readonly REMOVE_BACKGROUND: "removeBackground";
 	readonly REFRAME: "reframe";
+	readonly RASTERIZE: "rasterize";
 };
 declare const RICH_TEXT_DEFAULT_VALUES: {
 	opacity?: number | undefined;
@@ -706,6 +741,17 @@ export interface AddFontStyleOptions {
 /**
  * API for managing application state including selection, viewport, active tool, and canvas mode.
  *
+ * ## Selection
+ *
+ * {@link AppState.selectionIds} is the only stored selection list; every
+ * selection getter is derived from it and the current design state. Derived results are identity-stable — the very same array instance is
+ * returned until the selection or the design state changes — so React
+ * subscribers and the extension bridge can diff them by reference.
+ *
+ * Every selection setter replaces the whole selection: whatever ids it is
+ * given are expanded into their closure and committed to
+ * {@link AppState.selectionIds}.
+ *
  * @public
  */
 export interface AppStateAPI {
@@ -714,7 +760,7 @@ export interface AppStateAPI {
 	 */
 	getSelectedObjectsIds(): string[];
 	/**
-	 * Sets the selected object IDs.
+	 * Replaces the selection with the given objects.
 	 *
 	 * @param ids - Array of object IDs to select
 	 * @param origin - Optional origin tag for loop prevention in bidirectional syncs.
@@ -727,41 +773,51 @@ export interface AppStateAPI {
 	 */
 	getSelectedLayersIds(): string[];
 	/**
-	 * Sets the selected layer IDs.
+	 * Replaces the selection with the given layers.
+	 *
+	 * Board sub-layer ids (artboard, background, texture) select the board they
+	 * belong to.
 	 *
 	 * @param ids - Array of layer IDs to select
+	 * @param origin - Optional origin tag for loop prevention in bidirectional syncs
 	 */
-	setSelectedLayersIds(ids: string[]): void;
+	setSelectedLayersIds(ids: string[], origin?: Origin): void;
 	/**
 	 * Gets the IDs of selected artboards.
 	 */
 	getSelectedArtboardIds(): string[];
 	/**
-	 * Sets the selected artboard IDs.
+	 * Replaces the selection with the given artboards.
 	 *
 	 * @param ids - Array of artboard IDs to select
+	 * @param origin - Optional origin tag for loop prevention in bidirectional syncs
 	 */
-	setSelectedArtboardIds(ids: string[]): void;
+	setSelectedArtboardIds(ids: string[], origin?: Origin): void;
 	/**
 	 * Gets the object IDs within selected artboards.
 	 */
 	getSelectedArtboardsObjectIds(): string[];
 	/**
-	 * Sets the object IDs within selected artboards.
+	 * Replaces the selection with the given objects.
 	 *
 	 * @param ids - Array of object IDs
+	 * @param origin - Optional origin tag for loop prevention in bidirectional syncs
 	 */
-	setSelectedArtboardsObjectIds(ids: string[]): void;
+	setSelectedArtboardsObjectIds(ids: string[], origin?: Origin): void;
 	/**
 	 * Gets all selected object IDs including objects, artboards, and artboard objects.
+	 *
+	 * A flat, deduplicated list of ids that exist as boards or objects; it never
+	 * contains group ids or synthetic (`link__`, `path__`) ids.
 	 */
 	getAllSelectedObjectsIds(): string[];
 	/**
-	 * Sets all selected object IDs.
+	 * Replaces the selection with the given ids.
 	 *
 	 * @param ids - Array of all object IDs to select
+	 * @param origin - Optional origin tag for loop prevention in bidirectional syncs
 	 */
-	setAllSelectedObjectsIds(ids: string[]): void;
+	setAllSelectedObjectsIds(ids: string[], origin?: Origin): void;
 	/**
 	 * Gets the current canvas mode.
 	 *
@@ -955,11 +1011,13 @@ export interface AsyncAIAPI {
  * Sandboxed-side API proxies where all calls resolve asynchronously.
  */
 export interface AsyncApiMapping {
+	agent: WithAsync<PublicAgentAPI>;
 	ai: AsyncAIAPI;
 	aiGenerator: AsyncAIGeneratorAPI;
 	brandKit: WithAsync<PublicBrandKitAPI>;
 	mockup: WithAsync<MockupDataAPI>;
-	context: AsyncContextAPI;
+	/** One proxy serves every entrypoint, so it is typed with every mount's fields. */
+	context: AsyncContextAPI<KittlWidestContext>;
 	data: AsyncDataAPI;
 	/** @deprecated Use `project.design.api`. */
 	design: AsyncDesignAPI;
@@ -1026,7 +1084,7 @@ export interface AsyncProjectAPI {
 		createBatch(): Promise<AsyncBatchDesignAPI>;
 	};
 	app: {
-		state: AsyncPublicStateAPI<AppState, PublicAppSelectorState>;
+		state: AsyncPublicStateAPI<PublicAppState, PublicAppSelectorState>;
 		api: AsyncAppStateAPI;
 	};
 }
@@ -1270,14 +1328,6 @@ export interface CancellableSubmission {
 	 * first point the backend reports a schedule.
 	 */
 	until?: number;
-	/**
-	 * Drops the work still being done to prepare this submission's generations,
-	 * for a caller that handed the tracker an abort handle.
-	 *
-	 * Cancelling is `cancelGenerations`; this only saves finishing an upload for
-	 * a generation the user has already stopped.
-	 */
-	abort?: () => void;
 }
 /**
  * Methods for generating preview images and exports from the canvas.
@@ -2371,6 +2421,27 @@ export interface ImageAPI {
 	 * @throws When the specified image ID doesn't exist in the design
 	 */
 	resetImageBackgroundRemoval(params: ResetImageBackgroundRemovalParams, opts?: DesignApiOptions): SdkResultAsync<NormalizedIllustrationImageObject, SdkError>;
+	/**
+	 * Crops an image to its non-transparent pixels, for example after its
+	 * background was removed.
+	 *
+	 * Loads the image source, finds the transparent rows and columns along its
+	 * edges, and crops them away. The image is moved so its visible content
+	 * stays in place on the canvas, respecting rotation, scale, and flip.
+	 *
+	 * Leaves the image unchanged when it:
+	 * - is already cropped,
+	 * - has no transparent edges,
+	 * - is fully transparent, or
+	 * - had its source replaced while the image was loading.
+	 *
+	 * @param params - Configuration parameters identifying the image to trim
+	 * @param opts - Additional options for the design API operation
+	 * @returns Promise that resolves to the trimmed image object
+	 * @throws When the specified image ID doesn't exist in the design, or the
+	 * image source cannot be loaded or read
+	 */
+	trimTransparentEdges(params: TrimTransparentEdgesParams, opts?: UpdateObjectApiOptions): SdkResultAsync<NormalizedIllustrationImageObject, SdkError>;
 }
 /** @public */
 export interface ImageGenerationResult {
@@ -2840,8 +2911,15 @@ export interface MockupDataAPI {
 	getOverview(options?: Pick<PaginationOptions, "sort">): SdkResultAsync<MockupOverviewDto>;
 	/** Fetches a paginated list of mockups within a specific group. */
 	getGroup(groupId: string, options?: PaginationOptions): SdkResultAsync<MockupGroupDto>;
-	/** Searches mockups by a text query. */
-	search(query: string, options?: PaginationOptions): SdkResultAsync<PaginatedResult<CatalogItem>>;
+	/**
+	 * Searches mockups by text. OpenSearch uses relevance ordering and ignores sort.
+	 *
+	 * @param query - Search text.
+	 * @param options - Pagination, database sort, and optional OpenSearch mode.
+	 *
+	 * @returns Lightweight catalog summaries or an SDK error.
+	 */
+	search(query: string, options?: MockupSearchOptions): SdkResultAsync<PaginatedResult<CatalogItem>>;
 	/** Fetches suggested tags and groups for mockup discovery. */
 	getSuggestions(): SdkResultAsync<MockupSuggestions>;
 }
@@ -2879,6 +2957,14 @@ export interface MockupOverviewGroupDto {
 	/** Total number of mockups in this group */
 	total: number;
 }
+/** Pagination and search source options for the mockup catalog. */
+export interface MockupSearchOptions extends PaginationOptions {
+	/**
+	 * Uses OpenSearch relevance ordering instead of database sorting when true.
+	 * OpenSearch currently ignores `sort`. Defaults to false.
+	 */
+	useOpenSearch?: boolean;
+}
 /**
  * Suggested tags and groups for mockup discovery.
  */
@@ -3005,7 +3091,7 @@ export interface ObjectAPI {
 	 *
 	 * @example
 	 * ```typescript
-	 * const objectApi = new ObjectAPI(projectManager, store);
+	 * const objectApi = new ObjectAPI(projectCapability, store);
 	 *
 	 * // Lock a background image to prevent accidental modification
 	 * const result = await objectApi.setLockedState({
@@ -3045,7 +3131,7 @@ export interface ObjectAPI {
 	 *
 	 * @example
 	 * ```typescript
-	 * const objectApi = new ObjectAPI(projectManager, store);
+	 * const objectApi = new ObjectAPI(projectCapability, store);
 	 *
 	 * // Hide an object
 	 * const result = await objectApi.setHiddenState({
@@ -3096,7 +3182,7 @@ export interface ObjectAPI {
   
 	 * @example
 	 * ```typescript
-	 * const objectApi = new ObjectAPI(projectManager, store);
+	 * const objectApi = new ObjectAPI(projectCapability, store);
 	 *
 	 * // Rotate a text element 90 degrees clockwise around its center (default)
 	 * await objectApi.rotateObject({
@@ -3269,6 +3355,43 @@ export interface PlacementAPI {
 		batchClient?: BatchClient<NormalizedDesignState>;
 	}): SmartPlacementOutput;
 }
+/**
+ * Agent methods sandboxed extensions can call through the public SDK.
+ *
+ * Deliberately narrower than {@link AgentAPI}: a single-object, JSON-serializable
+ * argument per method, and only what an apps panel item needs to hand work to
+ * the agent. Both act on the chat open beside the panel, which the host
+ * decides (see {@link AgentAPI.getOpenChatId}); an app never names a chat.
+ * Listing, archiving and feedback stay host-internal.
+ */
+export interface PublicAgentAPI {
+	/**
+	 * Posts a text user message into the open chat and runs the agent on it.
+	 * Resolves once the run leaves its interruptible phase, like
+	 * {@link AgentAPI.sendMessage}. Text only: an image an app wants the agent
+	 * to see goes through {@link PublicAgentAPI.attachImage}, so the user stays
+	 * in charge of what is sent. Rejects when no chat is open, and while that
+	 * chat's run is still active (see {@link AgentAPI.getIsRunActive}): unlike
+	 * the host API, an app never replaces an answer the user is waiting for.
+	 */
+	sendMessage: (args: PublicAgentSendMessageArgs) => Promise<void>;
+	/**
+	 * Adds an image to the open chat composer's reference row. The user sees it
+	 * beside the prompt, can remove it, and sends it with their next message.
+	 * Nothing is sent by this call. See {@link AgentAPI.attachImage}.
+	 */
+	attachImage: (args: PublicAgentAttachImageArgs) => Promise<void>;
+}
+/** Arguments of {@link PublicAgentAPI.attachImage}. */
+export interface PublicAgentAttachImageArgs {
+	/** The image to attach: the record `upload.image.upload` returned. */
+	image: SandboxedAgentComposerImage;
+}
+/** Arguments of {@link PublicAgentAPI.sendMessage}. */
+export interface PublicAgentSendMessageArgs {
+	/** The user-role prompt to send, as the user had typed it. */
+	text: string;
+}
 /**
  * Public drag-and-drop API for extension-provided images.
  *
@@ -3444,6 +3567,18 @@ export interface RotateObjectParams {
 		y: OriginY;
 	};
 }
+/**
+ * An image an apps panel item attaches to the chat composer: the record
+ * `upload.image.upload` returned to it. `id` is the upload object id the agent
+ * loop stores (see {@link AgentMessageFilePart}); `objectName` is what the
+ * host builds the thumbnail from.
+ */
+export interface SandboxedAgentComposerImage {
+	/** Upload object id of the image. */
+	id: string;
+	/** Storage object name of the upload, for the composer thumbnail. */
+	objectName: string;
+}
 export interface SerializeBoardBase {
 	objects: SerializedObject[];
 	groupStructure: StructureObject;
@@ -3925,26 +4060,6 @@ export interface StructureObjectMeta {
 	 */
 	maskBackgroundColor?: string | null;
 }
-/**
- * What a generation's caller knows about the submission it belongs to.
- *
- * One submission is one Stop, so every generation of a group shares these.
- *
- * @public
- */
-export interface SubmissionOptions {
-	/**
-	 * Abandons the work of preparing this generation - rasterizing and uploading
-	 * its reference images - when the caller stops the submission it belongs to.
-	 *
-	 * An optimization, not the way to cancel: stopping a generation is
-	 * {@link AIGeneratorAPI.cancelGenerations}, which works the same with or
-	 * without this, and aborting once the create request has been sent does
-	 * nothing. Pass it to avoid finishing an upload whose generation the user
-	 * has already taken back.
-	 */
-	signal?: AbortSignal;
-}
 /**
  * API for creating and managing text elements in the design.
  *
@@ -4376,7 +4491,8 @@ export interface WithObjectLayout {
 	flipX: boolean;
 	flipY: boolean;
 }
-export type AIGenerationActionOrigin = "COPILOT" | "RIGHT_PANEL" | "LEFT_PANEL" | "MICRO_APP" | "IMAGE_SETS" | "AI_CHAT" | "SMARTBOARD" | "AI_INPUT_GENERATE_IMAGE" | "AI_INPUT_REMIX_IMAGE" | "AI_INPUT_GENERATE_VIDEO" | "AI_INPUT_MICRO_EDITOR_REMIX" | "AI_INPUT_MICRO_EDITOR_INPAINT" | "AI_HUB_GENERATE_IMAGE" | "AI_HUB_REMIX_IMAGE" | "AI_HUB_GENERATE_VIDEO" | "VIDEOBOARD" | "AGENT" | "AI_HUB_AGENT" | "WORKFLOW" | "MCP" | "MCP_WORKFLOW" | "AI_AGENT" | "AI_AGENT_CHAT" | "AI_AGENT_CHAT_WEBSITE" | "MOBILE_APP_GENERATE_IMAGE" | "MOBILE_APP_REMIX_IMAGE" | "MOBILE_APP_GENERATE_VIDEO" | "MOBILE_APP_AGENT";
+/** Where generation started, using the API's action-origin contract. */
+export type AIGenerationActionOrigin = GenerateContentActionOrigin;
 export type AIGenerationContentType = "image" | "video";
 export type AIGenerationModelTaskType = "IMAGE_TO_IMAGE" | "IMAGE_INPAINT" | "IMAGE_OUTPAINT" | "TEXT_TO_IMAGE" | "IMAGE_TO_VIDEO";
 /**
@@ -4451,11 +4567,9 @@ export type AIGeneratorAPI = {
 	 * @param generatorId - Unique identifier for the generator type
 	 * @param inputSettings - Generator-specific input parameters matching the API schema
 	 * @param output - Requested output settings for the generation
-	 * @param options - What the caller knows about the submission this
-	 *   generation belongs to, see {@link SubmissionOptions}
 	 * @returns Object containing the generation ID
 	 */
-	generate: (generatorId: string, inputSettings: GenerationInputSettings, output: GenerationOutputSettings, options?: SubmissionOptions) => {
+	generate: (generatorId: string, inputSettings: GenerationInputSettings, output: GenerationOutputSettings) => {
 		generationId: string;
 	};
 	/**
@@ -4499,10 +4613,6 @@ export type AIGeneratorAPI = {
 	 * generation whose create request has not been sent is taken back without the
 	 * backend ever hearing about it.
 	 *
-	 * Takes the submission rather than bare ids so this is also where the
-	 * preparation still running for it is dropped - callers never do that
-	 * themselves, and so cannot forget to.
-	 *
 	 * @param submission - The submission to stop, from `createSubmissionTracker`.
 	 *   A caller without a tracker can pass `{ generationIds }`.
 	 * @returns Promise resolving once every cancellation settled, listing the
@@ -4809,7 +4919,7 @@ export type AddSmartboardParams = {
 } & {
 	position: AbsolutePosition | RelativePosition;
 	size: Dimensions;
-};
+} & Pick<SmartboardOptions, "generationSettings">;
 /**
  * Comprehensive font and styling properties for text customization and typography control.
  *
@@ -4887,6 +4997,11 @@ export type AddTextParams = {
 	 * **Default dimensions**: 200x50 pixels if not specified
 	 */
 	size: Dimensions;
+	/**
+	 * When set, assigns the new text to this board instead of resolving the board
+	 * id via `getObjectBoardId`.
+	 */
+	boardId?: string;
 };
 /**
  * Parameters for adding a new video to the design.
@@ -4974,6 +5089,11 @@ export type AnimateViewportToBoundsParams = ViewportAnimationSettings & ObjectPo
  */
 export type AnimateViewportToCenterParams = ViewportAnimationSettings & ObjectPositionRect;
 export type AnimationChannel = (typeof ANIMATION_CHANNELS)[number];
+/**
+ * How a track combines with the object's own property: `add` is
+ * `property + value`, `replace` sets it.
+ */
+export type AnimationComposite = "add" | "replace";
 /**
  * `cubic-bezier(x1, y1, x2, y2)`; x values within `[0, 1]`, y values may
  * overshoot. A mutable tuple on purpose: `Normalized<>` cannot map `readonly`
@@ -4988,13 +5108,39 @@ export type AnimationCubicBezierEasing = {
 		y2: number
 	];
 };
-export type AnimationEasing = AnimationEasingName | AnimationCubicBezierEasing;
+export type AnimationEasing = AnimationEasingName | AnimationCubicBezierEasing | AnimationStepsEasing | AnimationHoldEasing;
 export type AnimationEasingName = (typeof ANIMATION_EASING_NAMES)[number];
+/** Keeps the keyframe value until the next keyframe. */
+export type AnimationHoldEasing = {
+	type: "hold";
+};
 /**
  * Key of an animation in the design state, built from its
  * {@link AnimationTarget}: `objectId` or `objectId/pathItemId`.
  */
 export type AnimationKey = string;
+/**
+ * Curve the target travels along, driven by the `offsetDistance` channel.
+ * Offsets are added to the position, so the curve is relative to where the
+ * target rests (usually ending at `0,0`), in its parent's units.
+ */
+export type AnimationMotionPath = {
+	/**
+	 * SVG path data made of one absolute `M` followed by absolute `L` / `C`
+	 * commands, e.g. `'M -200 300 C -150 100 -50 0 0 0'`. A string rather than
+	 * points keeps it one atomic value in the design state.
+	 */
+	path: string;
+	/** Rotates the target along the curve's tangent, on top of `rotate`. */
+	autoRotate?: boolean;
+};
+export type AnimationShapeChannel = typeof ANIMATION_SHAPE_CHANNEL;
+/** `steps(count, position)`: jumps in `count` equal steps. */
+export type AnimationStepsEasing = {
+	type: "steps";
+	count: number;
+	position: "start" | "end";
+};
 export type Animations = Record<AnimationKey, NormalizedAnimation>;
 /**
  * Application state interface containing selection, viewport, active tool, and other UI state.
@@ -5006,25 +5152,27 @@ export type Animations = Record<AnimationKey, NormalizedAnimation>;
  */
 export type AppState = {
 	/**
-	 * Array of selected objects' ids.
-	 * Note: unlike `selectedLayersIds`, this includes all selected objects regardless group structure; there won't be ids of groups.
-	 */
-	selectedObjectsIds: string[];
-	/**
-	 * Array of selected layers' ids.
-	 * Note: all items in the list are on the same level in the group structure; there might be ids of groups.
-	 */
-	selectedLayersIds: string[];
-	/**
-	 * Array of selected artboards' ids.
-	 */
-	selectedArtboardIds: string[];
-	/**
-	 * Array of selected artboards' object ids.
+	 * Every selected id, in selection order — the single stored selection list
+	 * every selection getter of {@link AppStateAPI} (including
+	 * `getAllSelectedObjectsIds`) is derived from.
+	 *
+	 * The list holds the full closure of the selection: selecting a board or a
+	 * group also lists everything nested inside it, in canvas render order. It
+	 * mixes all the kinds of things that can be selected:
+	 *
+	 * - board ids
+	 * - object ids
+	 * - group ids (structure nodes that are not objects themselves)
+	 * - `link__<inputBoardId>_<targetBoardId>` ids for the connection between a
+	 *   smartboard input and its target
+	 * - `path__<childObjectId>` ids for a single sub-path of an illustration
+	 * - ids the design state does not know yet, passed through untouched
+	 *
+	 * A board's texture and background are not selectable on their own: they
+	 * exist only as layer ids, which {@link AppStateAPI.getSelectedLayersIds}
+	 * derives from the selected board.
 	 */
-	selectedArtboardsObjectIds: string[];
-	/** All selected objects including: objects, artboards and artboards' objects */
-	allSelectedObjectsIds: string[];
+	selectionIds: string[];
 	/**
 	 * Active canvas mode after its mode-specific entry succeeds.
 	 *
@@ -5046,6 +5194,12 @@ export type AppState = {
 	isViewOnlyMode: boolean;
 	/** Whether the loaded design contains objects outside the supported viewport bounds. */
 	hasLegacyOutOfBoundsObjects: boolean;
+	/**
+	 * Canvas-owned: true when recoverable content exists but none is in view.
+	 * Excludes helpers and hidden/transparent objects; false in runtimes without
+	 * the renderer's content visibility stage and outside the default working mode.
+	 */
+	isContentOutOfView: boolean;
 	canvasSettings: SettingsType;
 	/** Last-used pen tool stroke/fill settings, applied to newly drawn paths. */
 	penToolSetting: {
@@ -5170,7 +5324,7 @@ export type BoundingRect = {
 	bottom: number;
 	right: number;
 };
-/** Brand kit data exposed through the project manager. */
+/** Brand kit data exposed through the `brandKit` capability. */
 export type BrandKit = {
 	id: string;
 	name: string;
@@ -5272,6 +5426,16 @@ export type CanvasMode = {
 } | {
 	mode: "inpaint";
 	targetId: string;
+}
+/**
+ * A rich text object is being edited. Set by the canvas while the text is in
+ * editing mode; it is not a `CanvasModeManager` mode. `range` holds the
+ * selected characters and is absent until the canvas reports it.
+ */
+ | {
+	mode: "text-editing";
+	targetId: string;
+	range?: TextRange;
 } | {
 	mode: "custom";
 	id: string;
@@ -5284,7 +5448,7 @@ export type CanvasMode = {
  *
  * @public
  */
-export type CanvasModeKind = "erase" | "erase-and-fill" | "crop" | "reframe" | "inpaint" | null;
+export type CanvasModeKind = "erase" | "erase-and-fill" | "crop" | "reframe" | "inpaint" | "text-editing" | null;
 /**
  * The index of a character in the rich text object.
  */
@@ -5368,6 +5532,10 @@ export type CreateBasicShapeInput = CreateElementWithPositionAndSize & {
  */
 export type CreateBoardParams = Omit<CreateElementWithPositionAndSize, "size" | "boardId"> & {
 	title?: string;
+	/**
+	 * Layout of the new artboard. Defaults to the standard layout.
+	 */
+	activeLayout?: ArtboardOptions["activeLayout"];
 	/**
 	 * size required on artboard
 	 */
@@ -5673,6 +5841,7 @@ export type FileBrowserCapability = {
  * Union of nodes a dynamic tab can return.
  */
 export type FileBrowserContent = FileBrowserItem | FileBrowserFolder;
+export type FileBrowserContentSource = "generated" | "uploaded";
 /**
  * Input arguments for a file browser content request.
  */
@@ -5748,6 +5917,8 @@ export type FileBrowserItem = {
 	animatedPreview?: string;
 	content: {
 		data: string;
+		/** Identifies whether the content came from uploads or generated content. */
+		source?: FileBrowserContentSource;
 		/** Optional MIME type used when materializing the selected asset. */
 		mimeType?: string;
 		/** Persisted upload classification. */
@@ -5909,6 +6080,7 @@ export type FullColor = {
 	visible: boolean;
 };
 export type FunctionType = (...args: never) => unknown;
+export type GenerateContentActionOrigin = (typeof GenerateContentActionOrigin)[keyof typeof GenerateContentActionOrigin];
 /** Alias: capability name for AIGenerationInputSettings. @public */
 export type GenerationInputSettings = AIGenerationInputSettings;
 /** Alias: capability name for AIGenerationOutputSettings. @public */
@@ -6158,6 +6330,22 @@ export type JSONObject = {
 	[key: string]: JSONValue;
 };
 export type JSONValue = null | boolean | number | string | Array<JSONValue> | JSONObject;
+export type KeyframeBase = {
+	id: string;
+	/**
+	 * Easing of the segment that starts at this keyframe. Defaults to
+	 * {@link DEFAULT_KEYFRAME_EASING}, ignored on the last keyframe.
+	 */
+	easing?: AnimationEasing;
+};
+/**
+ * Every field any mounting point's host context can carry. The extension-side
+ * bridge is typed with it because it is one proxy shared by all entrypoints;
+ * each entrypoint narrows it to the context its mounting point receives.
+ *
+ * @public
+ */
+export type KittlWidestContext = KittlEditorContext;
 /**
  * The predefined OpenType variation axes. However, a font can define custom
  * axes using a four-character string.
@@ -6178,6 +6366,15 @@ export type LeftTopPosition = {
 	left: number;
 	top: number;
 };
+/**
+ * The derived selection lists readable through the `appState` subscribe
+ * channel. None of them is stored in {@link AppState} (only the selection
+ * closure `selectionIds` is); they are derived by the app state API, and the host bridge merges
+ * them in before delivering updates (see `createExtensionAppStateStore` in
+ * `@repo/sandbox-wrapper`), so published extensions can keep subscribing to
+ * them by their legacy names.
+ */
+export type LegacySelectionKey = "selectedObjectsIds" | "selectedLayersIds" | "selectedArtboardIds" | "selectedArtboardsObjectIds" | "allSelectedObjectsIds";
 /**
  * The line height of the text.
  */
@@ -6273,8 +6470,6 @@ export type MicroEditorWorkflowSource = {
 	presetId: string;
 	/** Whether outputs from the workflow preset support layerization. */
 	isLayerizable: boolean;
-	/** Whether this particular workflow result is ready for layerization. */
-	readyToLayerize?: boolean;
 	/** Generated-content record associated with this workflow result. */
 	generatedContentId?: string;
 	/** Original upload id accepted by the image-spec API. */
@@ -6409,10 +6604,20 @@ export type NormalizeValue<T> = T extends null | undefined ? T : NonNullable<T>
  * instead of trying to normalize the union as a whole.
  */
 export type Normalized<T> = T extends null | undefined ? T : T extends Builtin ? T : T extends unknown[] | readonly unknown[] ? NormalizeArray<T> : T extends object ? NormalizeObject<T> : T;
-/** `keyframes` becomes a record plus `keyframesIndices` for ordering. */
-export type NormalizedAnimation = Normalized<SerializedAnimation>;
+/** `tracks` becomes a record plus `tracksIndices` for ordering. */
+export type NormalizedAnimation = Normalized<Omit<SerializedAnimation, "tracks">> & {
+	tracks: Record<string, NormalizedTrack>;
+	tracksIndices: Record<string, string>;
+};
 export type NormalizedBasicShapeObject = Normalized<BasicShapeSerializedObject>;
 export type NormalizedBoard = NormalizedStandardBoard | NormalizedFloatingBoard;
+/**
+ * `keyframes` becomes a record plus `keyframesIndices` for ordering. A record
+ * has no first entry, so it holds any {@link SerializedKeyframe}.
+ */
+export type NormalizedChannelTrack = Normalized<Omit<SerializedChannelTrack, "keyframes"> & {
+	keyframes: SerializedKeyframe[];
+}>;
 export type NormalizedCombinedShapeObject = Normalized<CombinedShapeSerializedObject>;
 export type NormalizedDesignState = {
 	boards: Record<ID, NormalizedBoard>;
@@ -6446,11 +6651,14 @@ export type NormalizedPathTextObject = Normalized<PathTextSerializedObject>;
  * In the normalized form all object references are replaced by their ids.
  */
 export type NormalizedRichTextObject = Normalized<RichTextSerializedObject>;
+/** `keyframes` becomes a record plus `keyframesIndices` for ordering. */
+export type NormalizedShapeTrack = Normalized<SerializedShapeTrack>;
 /**
  * The normalized version of a StandardBoard
  */
 export type NormalizedStandardBoard<T extends ArtboardOptions = ArtboardOptions> = Normalized<BaseStandardBoard<T>>;
 export type NormalizedStandardObject = NormalizedBasicShapeObject | NormalizedCombinedShapeObject | NormalizedIllustrationImageObject | NormalizedIllustrationObject | NormalizedLoadingCardObject | NormalizedMaskObject | NormalizedMockupDesignObject | NormalizedPathTextObject | NormalizedRichTextObject | NormalizedVideoObject;
+export type NormalizedTrack = NormalizedChannelTrack | NormalizedShapeTrack;
 export type NormalizedVideoObject = Normalized<VideoSerializedObject>;
 export type NullablePathTextShadowOptions = PathTextShadowOptions | {
 	type: null;
@@ -6678,6 +6886,8 @@ export type PlainInputSetting = {
 	isPremium?: boolean;
 	name: "combineBoards" | (string & {});
 	label?: string;
+	/** Help text shown when hovering a boolean setting. */
+	tooltip?: string;
 	disabled?: true;
 } & ({
 	type: "selection";
@@ -6720,18 +6930,16 @@ export type PrintMargins = {
 	bottom: number;
 	left: number;
 };
+/** Generator API exposed to iframe clients. Same as {@link AIGeneratorAPI}. */
+export type PublicAIGeneratorAPI = AIGeneratorAPI;
+/** App selectors cover the approved subscription fields within the full snapshot. */
+export type PublicAppSelectorState = Pick<PublicAppState, (typeof APP_STATE_SUBSCRIPTION_KEYS)[number]>;
 /**
- * Generator API exposed to iframe clients. Local AbortSignals and abort callbacks
- * cannot cross postMessage; cancellation uses the host's generation IDs instead.
+ * The shape of the state extensions can subscribe to over the `appState`
+ * channel: the current {@link AppState} plus the five derived, read-only
+ * {@link LegacySelectionKey} lists.
  */
-export type PublicAIGeneratorAPI = Omit<AIGeneratorAPI, "generate" | "cancelGenerations"> & {
-	/** Starts a generation without accepting a caller-local AbortSignal. */
-	generate: (generatorId: string, inputSettings: GenerationInputSettings, output: GenerationOutputSettings) => ReturnType<AIGeneratorAPI["generate"]>;
-	/** Cancels a submission using only its serializable fields. */
-	cancelGenerations: (submission: Pick<CancellableSubmission, "generationIds" | "until">) => ReturnType<AIGeneratorAPI["cancelGenerations"]>;
-};
-/** App selectors cover the approved subscription fields within the full snapshot. */
-export type PublicAppSelectorState = Pick<AppState, (typeof APP_STATE_SUBSCRIPTION_KEYS)[number]>;
+export type PublicAppState = AppState & Record<LegacySelectionKey, string[]>;
 /**
  * Brand kit methods sandboxed extensions can call through the public SDK.
  * Read-only for now: image uploads into a brand kit need a write scope first.
@@ -7426,8 +7634,9 @@ export type SerialisedPhotoFilter = ({
 export type SerializableCornerRadii = Record<string, Record<string, number>>;
 export type SerializableObjectType = ObjectType.IllustrationImage | ObjectType.Illustration | ObjectType.Artboard | ObjectType.Smartboard | ObjectType.Videoboard | ObjectType.MockupBoard | ObjectType.PathText | ObjectType.RichText | ObjectType.MockupDesign | ObjectType.OverlayTexture | ObjectType.Mask | ObjectType.BasicShape | ObjectType.VectorPath | ObjectType.Guide | ObjectType.CombinedShape | ObjectType.LoadingCard | ObjectType.Video;
 /**
- * Keyframes of one target. The animation lasts until its last keyframe (see
- * `getAnimationDuration`), so there is no separate duration to keep in sync.
+ * Tracks of one target, at most one per channel. The animation lasts until
+ * its last keyframe (see `getAnimationDuration`), so there is no separate
+ * duration to keep in sync.
  */
 export type SerializedAnimation = {
 	/**
@@ -7438,22 +7647,77 @@ export type SerializedAnimation = {
 		x: number;
 		y: number;
 	};
-	keyframes: SerializedKeyframe[];
+	motionPath?: AnimationMotionPath;
+	/**
+	 * Distance from the viewer to the canvas plane for the 3D channels, in
+	 * canvas px, like CSS `perspective()`; positive. Defaults to `1000`. When
+	 * several animations apply to one object, the most specific one that sets
+	 * it wins.
+	 */
+	perspective?: number;
+	tracks: SerializedTrack[];
 };
 export type SerializedAnimations = Record<AnimationKey, SerializedAnimation>;
 export type SerializedBoard = SerializedStandardBoard | SerializedFloatingBoard;
-export type SerializedKeyframe = {
+/** Keyframes of one channel. */
+export type SerializedChannelTrack = {
 	id: string;
+	channel: AnimationChannel;
+	composite: AnimationComposite;
+	/** Unique times; the fractional-index order only breaks ties. */
+	keyframes: SerializedKeyframes;
+};
+/** Any keyframe of a track, see {@link SerializedKeyframes} for their order. */
+export type SerializedKeyframe<TValue = number> = SerializedStartKeyframe<TValue> | SerializedTimedKeyframe<TValue>;
+/**
+ * Keyframes of a track. Only the first one may be a start keyframe without
+ * `value`; every later keyframe has one. A track whose first keyframe comes
+ * after `0` starts from the target's own value with
+ * {@link DEFAULT_KEYFRAME_EASING}, as if it had a start keyframe without
+ * value and easing.
+ */
+export type SerializedKeyframes<TValue = number> = [
+] | [
+	SerializedKeyframe<TValue>,
+	...SerializedTimedKeyframe<TValue>[]
+];
+export type SerializedObject = StandardSerializedObject | GuideSerializedObject;
+/**
+ * Keyframe of the shape track: `value` is absolute SVG path data (`M L C Q
+ * Z`). Lines, quadratics and cubics may morph into each other as long as the
+ * structure (subpaths, segment count per subpath, closed flags) matches the
+ * path's own; only positions interpolate. Every shape keyframe has a value,
+ * since playback cannot read the path's own shape, and the track holds its
+ * first shape before its first keyframe.
+ */
+export type SerializedShapeKeyframe = SerializedTimedKeyframe<string>;
+/** Keyframes of the path shape; it replaces the shape, so has no composite. */
+export type SerializedShapeTrack = {
+	id: string;
+	channel: AnimationShapeChannel;
+	/** Unique times; the fractional-index order only breaks ties. */
+	keyframes: SerializedShapeKeyframe[];
+};
+/**
+ * Keyframe at the animation start. Without `value` it starts from the
+ * target's own value, like a CSS animation without a `0%` keyframe, so it
+ * can set only the easing of the first segment.
+ */
+export type SerializedStartKeyframe<TValue = number> = KeyframeBase & {
+	time: 0;
+	value?: TValue;
+};
+export type SerializedTimedKeyframe<TValue = number> = KeyframeBase & {
 	/** Offset from the animation start, integer milliseconds. */
 	time: number;
-	/** Easing of the segment that ends at this keyframe. Defaults to `linear`. */
-	easing?: AnimationEasing;
-	/** A channel that is omitted keeps its previous value. */
-	values: Partial<Record<AnimationChannel, number>>;
-	/** Channels not listed here use `add`. */
-	composites?: Partial<Record<AnimationChannel, "replace">>;
+	/**
+	 * Relative to the object, not to the previous keyframe: with `add` an
+	 * offset from the object's own property (e.g. `translateX: 10` is 10px right
+	 * of the object), with `replace` the absolute property value.
+	 */
+	value: TValue;
 };
-export type SerializedObject = StandardSerializedObject | GuideSerializedObject;
+export type SerializedTrack = SerializedChannelTrack | SerializedShapeTrack;
 export type SetCanvasModeWithTargetOptions = {
 	/**
 	 * Optional origin metadata for state propagation.
@@ -7463,6 +7727,11 @@ export type SetCanvasModeWithTargetOptions = {
 	 * Optional id of the object that should enter the mode.
 	 */
 	targetId?: string | null;
+	/**
+	 * Optional selected character range of the edited text. Only used by
+	 * `'text-editing'`.
+	 */
+	range?: TextRange;
 };
 /** Color updates to apply to one object. */
 export type SetColorsParams = {
@@ -7542,6 +7811,7 @@ export type ShapeProperties = {
 	skewY?: BasicShapeSerializedObject["skewY"];
 	cornerRadii?: BasicShapeSerializedObject["cornerRadii"];
 	name?: BasicShapeSerializedObject["name"];
+	defaultName?: BasicShapeSerializedObject["defaultName"];
 	shadowOptions?: BasicShapeSerializedObject["shadowOptions"];
 	fill?: NonNullable<BasicShapeSerializedObject["fill"]>;
 	fillColor?: NonNullable<BasicShapeSerializedObject["fill"]>[number]["value"];
@@ -7858,6 +8128,15 @@ export type TextProperties = {
 	 */
 	strokeWidth?: number;
 };
+/**
+ * Character range of the text being edited, in Fabric character indices.
+ * A line break (`'\n'`) counts as one character, and `start === end` is a
+ * caret without a selection.
+ */
+export type TextRange = {
+	start: number;
+	end: number;
+};
 /**
  * Parameters for changing the hidden state of an illustration path.
  *
@@ -7878,6 +8157,9 @@ export type ToggleLockIllustrationPathParams = {
 	pathId: string;
 	locked: boolean;
 };
+export type TrimTransparentEdgesParams = {
+	id: IllustrationImageSerializedObject["id"];
+};
 /** Preserves variant-specific object fields in design selectors. */
 export type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer I) => void ? I : never;
 /**
@@ -7945,6 +8227,9 @@ export type UpdateIllustrationParams = {
 	stroke?: IllustrationSerializedObject["stroke"];
 	strokeWidth?: IllustrationSerializedObject["strokeWidth"];
 	fill?: IllustrationSerializedObject["fill"];
+	opacity?: IllustrationSerializedObject["opacity"];
+	flipX?: IllustrationSerializedObject["flipX"];
+	flipY?: IllustrationSerializedObject["flipY"];
 };
 /**
  * Parameters for updating an existing image.
@@ -7966,6 +8251,23 @@ export type UpdateImageParams = {
 	strokeWidth?: IllustrationImageSerializedObject["strokeWidth"];
 	inpaintingStrokeWidth?: IllustrationImageSerializedObject["inpaintingStrokeWidth"];
 	inpaintingSelectionMode?: IllustrationImageSerializedObject["inpaintingSelectionMode"];
+	opacity?: IllustrationImageSerializedObject["opacity"];
+	flipX?: IllustrationImageSerializedObject["flipX"];
+	flipY?: IllustrationImageSerializedObject["flipY"];
+	/**
+	 * Photo filters to add or replace, keyed by filter id; `null` removes one.
+	 * Merged into the current filters. Every filter must end up with an index
+	 * in `filtersIndices`, and an image has at most one filter of each type.
+	 */
+	filters?: Record<string, NonNullable<NormalizedIllustrationImageObject["filters"]>[string] | null>;
+	/**
+	 * Fractional index of each filter id, which sets the order the filters
+	 * apply in; `null` removes one. Merged into the current indices, so the
+	 * filters can be reordered without sending them.
+	 */
+	filtersIndices?: Record<string, string | null>;
+	globalCompositeOperation?: IllustrationImageSerializedObject["globalCompositeOperation"];
+	backgroundRestorePathBoundary?: IllustrationImageSerializedObject["backgroundRestorePathBoundary"];
 } & GeneratableObject;
 export type UpdateImageSourceParams = {
 	id: IllustrationImageSerializedObject["id"];
@@ -8105,6 +8407,36 @@ export type UpdateTextParams = {
 	left?: number;
 	top?: number;
 	angle?: number;
+	/**
+	 * Opacity of the whole text element, from 0 (transparent) to 1 (opaque)
+	 */
+	opacity?: number;
+	/**
+	 * Mirror the text horizontally
+	 */
+	flipX?: boolean;
+	/**
+	 * Mirror the text vertically
+	 */
+	flipY?: boolean;
+	/**
+	 * Width of the text box in pixels
+	 */
+	width?: number;
+	/**
+	 * Height of the text box in pixels
+	 */
+	height?: number;
+	/**
+	 * Per-character style overrides, in the compressed format the text
+	 * object stores. Replaces the stored overrides as a whole.
+	 */
+	styles?: RichTextCompressedStyles;
+	/**
+	 * Transform (warp, circle, free form or free line) shaping the text, with
+	 * its points. Replaces the stored transform as a whole.
+	 */
+	activeTransformPlugin?: RichTextSerializedTransformPluginObject;
 } & Partial<TextProperties>;
 /**
  * Parameters for updating texture properties.
@@ -8269,6 +8601,13 @@ export type VideoboardOptions = ConnectedArtboardOptions<ObjectType.Videoboard>
  * @public
  */
 export type Viewport = {
+	/**
+	 * Viewport size in screen pixels, measured from the canvas container.
+	 */
+	pixelSize: {
+		width: number;
+		height: number;
+	};
 	/**
 	 * Viewport corners in canvas coordinates (derived from transform + canvas size).
 	 * - tl: top-left
@@ -8361,12 +8700,15 @@ export type ViewportAPI = {
 	 */
 	setTransform(transform: Viewport["transform"], origin?: Origin): void;
 	/**
-	 * Returns the current viewport size in screen pixels.
+	 * Returns the current viewport size in screen pixels, measured from the
+	 * canvas container.
 	 */
 	getPixelSize(): {
 		width: number;
 		height: number;
 	};
+	/** Reads the canvas-owned {@link AppState.isContentOutOfView} flag. */
+	isContentOutOfView(): boolean;
 	/**
 	 * Returns the current viewport zoom level.
 	 */
@@ -8396,7 +8738,8 @@ export type ViewportAPI = {
 	 */
 	getCoords(): Viewport["coords"];
 	/**
-	 * Sets the viewport corner coordinates.
+	 * Sets the viewport corner coordinates and, when supplied, its measured
+	 * screen-space size.
 	 *
 	 * This is primarily for internal synchronization. In normal usage, prefer
 	 * updating the viewport via {@link set}, {@link setZoom}, or
@@ -8404,8 +8747,19 @@ export type ViewportAPI = {
 	 *
 	 * @param coords - The viewport corner coordinates to set
 	 * @param origin - Optional origin metadata for state propagation
+	 * @param pixelSize - Canvas-container size measured with these coordinates
+	 *   (legacy callers that omit it derive a size from coordinates and zoom)
+	 */
+	setCoords(coords: Viewport["coords"], origin?: Origin, pixelSize?: Viewport["pixelSize"]): void;
+	/**
+	 * Publishes a viewport snapshot from the canvas renderer.
+	 *
+	 * Internal only — callers must obtain all fields from the same Fabric state.
+	 *
+	 * @param viewport - Transform, coordinates, and measured canvas size
+	 * @param origin - Optional origin metadata for state propagation
 	 */
-	setCoords(coords: Viewport["coords"], origin?: Origin): void;
+	setSnapshot(viewport: Viewport, origin?: Origin): void;
 	/**
 	 * Returns the current viewport center in world space.
 	 */