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

package/dist/editorScriptRunner/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;
@@ -695,6 +730,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 {
@@ -703,7 +749,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.
@@ -716,41 +762,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.
 	 *
@@ -970,7 +1026,7 @@ export interface AsyncProjectAPI {
 		createBatch(): Promise<AsyncBatchDesignAPI>;
 	};
 	app: {
-		state: AsyncPublicStateAPI<AppState, PublicAppSelectorState>;
+		state: AsyncPublicStateAPI<PublicAppState, PublicAppSelectorState>;
 		api: AsyncAppStateAPI;
 	};
 }
@@ -1205,14 +1261,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.
@@ -2237,6 +2285,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 {
@@ -2645,8 +2714,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>;
 }
@@ -2684,6 +2760,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.
  */
@@ -2810,7 +2894,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({
@@ -2850,7 +2934,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({
@@ -2901,7 +2985,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({
@@ -3703,26 +3787,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.
  *
@@ -4149,7 +4213,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";
 /**
@@ -4224,11 +4289,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;
 	};
 	/**
@@ -4272,10 +4335,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
@@ -4582,7 +4641,7 @@ export type AddSmartboardParams = {
 } & {
 	position: AbsolutePosition | RelativePosition;
 	size: Dimensions;
-};
+} & Pick<SmartboardOptions, "generationSettings">;
 /**
  * Comprehensive font and styling properties for text customization and typography control.
  *
@@ -4660,6 +4719,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.
@@ -4747,6 +4811,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`
@@ -4761,13 +4830,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.
@@ -4779,25 +4874,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.
 	 *
@@ -4819,6 +4916,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: {
@@ -4984,6 +5087,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;
@@ -4996,7 +5109,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.
  */
@@ -5074,6 +5187,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
 	 */
@@ -5494,6 +5611,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 */
@@ -5737,6 +5855,14 @@ 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;
+};
 /**
  * The predefined OpenType variation axes. However, a font can define custom
  * axes using a four-character string.
@@ -5757,6 +5883,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.
  */
@@ -5912,10 +6047,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>;
@@ -5949,11 +6094,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;
@@ -6127,6 +6275,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";
@@ -6169,18 +6319,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[]>;
 /** Design domain methods; whole-state reads belong to the state surface. */
 export type PublicDesignAPI = PublicDesignMethods<Omit<DesignAPI, "state"> & {
 	state: Omit<DesignAPI["state"], "getState">;
@@ -6823,8 +6971,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 = {
 	/**
@@ -6835,20 +6984,75 @@ 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 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.
@@ -6858,6 +7062,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 = {
@@ -6937,6 +7146,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"];
@@ -7230,6 +7440,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.
  *
@@ -7250,6 +7469,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;
 /**
@@ -7317,6 +7539,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.
@@ -7338,6 +7563,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"];
@@ -7477,6 +7719,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.
@@ -7640,6 +7912,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
@@ -7732,12 +8011,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.
 	 */
@@ -7767,7 +8049,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
@@ -7775,8 +8058,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.
 	 */