framer-api 0.1.1 → 0.1.2-alpha.0

package/dist/index.d.ts

@@ -46,9 +46,11 @@ type LintIssueSeverityValue = "error" | "warning";
 /** @deprecated The lintCode API was removed. This type will be removed in the near future. */
 type LintConfig = Record<LintRuleNameValue, LintIssueSeverityValue>;
 interface DiagnosticBase {
+    /** The error or warning message describing the diagnostic. */
     message: string;
     span?: DiagnosticSpan;
 }
+/** A span of characters in a code file, used to locate a diagnostic. */
 interface DiagnosticSpan {
     /** The first character, counted from the beginning of the file, 0-based. */
     offset: number;
@@ -67,18 +69,23 @@ interface LintLink {
 interface LintDiagnostic extends DiagnosticBase {
     /** The span of the invalid code in the file. */
     span: DiagnosticSpan;
+    /** Issue severity: `"error"` or `"warning"`. */
     severity: LintIssueSeverityValue;
+    /** Optional documentation link for the diagnostic issue. */
     link?: LintLink;
 }
+/** A diagnostic produced by type-checking a code file. */
 interface TypecheckDiagnostic extends DiagnosticBase {
     /**
      * The span of the invalid code in the file.
      * Could be undefined if the diagnostic is system-level (and not file-specific), like e.g. an error about invalid TS options.
      */
     span?: DiagnosticSpan;
-    /** Could be undefined if the diagnostic is system-level (and not file-specific), like e.g. an error about invalid TS options */
+    /** Source file name. Could be undefined if the diagnostic is system-level (and not file-specific), like e.g. an error about invalid TS options. */
     fileName?: string;
+    /** TypeScript error code. */
     code: number;
+    /** Error category from the TypeScript compiler. */
     category: ts.DiagnosticCategory;
 }
 
@@ -108,40 +115,76 @@ declare const getHTMLForNodeMessageType = "INTERNAL_getHTMLForNode";
 declare const setHTMLForNodeMessageType = "INTERNAL_setHTMLForNode";
 
 type LocaleId = string;
+/**
+ * A locale configured in the project for localization. Locales represent
+ * a language paired with an optional region (e.g. English, or English (Canada)).
+ */
 interface Locale {
+    /** A unique identifier for the locale. */
     id: LocaleId;
+    /** The BCP 47 language code, e.g. `"en-US"` or `"nl"`. */
     code: string;
+    /** The display name of the locale, e.g. `"English (US)"`. */
     name: string;
+    /** The URL slug used for this locale, e.g. `"en"`. */
     slug: string;
+    /**
+     * The ID of the fallback locale. When a Localization Source does not have
+     * a localized value set for this locale, Framer will fall back to the value
+     * defined in the fallback locale.
+     */
     fallbackLocaleId?: string;
 }
 interface LocalizationValueBase {
-    /** A `value` of `null` means that the value explicitly falls back to the fallback locale */
+    /**
+     * The actual text of the localized value. A `value` of `null` means that
+     * the value will fall back to the value set in the fallback locale.
+     */
     value: string | null;
+    /** The timestamp (in milliseconds since epoch) of when this localized value was last edited. */
     lastEdited: number;
     /**
      * Whether the value is read only and therefore cannot be updated.
      *
      * For example, this is the case for localized values that were set
      * when syncing a managed collection. To update these values, you must
-     * sync using the plugin that manages the collection.
+     * provide them when syncing the plugin that manages the collection.
      */
     readonly: boolean;
 }
+/** A localization value that has not been set yet. */
 interface LocalizationValueNew {
+    /** Always `null` for new (unset) localization values. */
     value: null;
+    /** Indicates this value is currently not set. */
     status: "new";
 }
+/** A localization value that has been set but needs review, either manually flagged or because the default locale value changed. */
 interface LocalizationValueNeedsReview extends LocalizationValueBase {
+    /** Indicates this value needs review. */
     status: "needsReview";
 }
+/** A localization value that has been set and is considered complete. */
 interface LocalizationValueDone extends LocalizationValueBase {
+    /** Indicates this value has been set. */
     status: "done";
 }
+/** A localization value that has been set but has warnings. */
 interface LocalizationValueWarning extends LocalizationValueBase {
+    /** Indicates this value has warnings. */
     status: "warning";
+    /** A message describing why the localized value has a warning status. Only set when status is `"warning"`. */
     warning: string;
 }
+/**
+ * The localized value and associated metadata for a specific locale. Use the `status`
+ * discriminator to narrow the type:
+ *
+ * - `"new"` - A value that is currently not set.
+ * - `"needsReview"` - A value that has been set but marked as needing review.
+ * - `"warning"` - A value that has been set but has warnings.
+ * - `"done"` - A value that has been set and is complete.
+ */
 type LocalizationValue = LocalizationValueNew | LocalizationValueNeedsReview | LocalizationValueDone | LocalizationValueWarning;
 type LocalizationValueByLocale = Record<LocaleId, LocalizationValue>;
 type InlineLocalizationValueByLocale = Record<LocaleId, LocalizationValue>;
@@ -149,24 +192,45 @@ type LocalizationGroupId = string;
 type LocalizationSourceId = string;
 type LocalizedValueStatus = LocalizationValue["status"];
 type LocalizationSourceType = "string" | "formattedText" | "altText" | "slug" | "link";
+/**
+ * A localizable string on your site. Localization sources are the actual
+ * translatable strings from your site, along with their localized values.
+ */
 interface LocalizationSource {
-    /** A stable ID of the localization source that can be used for updating and synchronizing */
+    /** A unique identifier for the localization source, stable across syncs. */
     id: LocalizationSourceId;
-    /** The type of value for this source */
+    /** The type of value for this source, such as `"string"`, `"formattedText"`, `"altText"`, `"slug"`, or `"link"`. */
     type: LocalizationSourceType;
-    /** Current Source value */
+    /** The current value of the localization source in the default locale. */
     value: string;
-    /** Localized values and metadata for each locale */
+    /** Localized values and metadata for each locale, keyed by locale ID. */
     valueByLocale: LocalizationValueByLocale;
 }
 type LocalizationGroupStatus = "excluded" | "ready";
 type LocalizationGroupStatusByLocale = Record<LocaleId, LocalizationGroupStatus>;
+/**
+ * A group of related localization sources, such as all translatable content for a
+ * page or collection item. Localization groups are things like pages or CMS items
+ * that contain one or more localization sources.
+ *
+ * A group can have a different status in each locale. For example, you may want to
+ * show a blog post in your French locale but exclude it in your Dutch locale.
+ */
 interface LocalizationGroup {
+    /** A unique identifier for the localization group. */
     id: LocalizationGroupId;
+    /** The name of the localization group. */
     name: string;
+    /** The kind of content this group represents. */
     type: "collection" | "collection-item" | "component" | "page" | "settings" | "template";
+    /** Whether this group supports the `"excluded"` status for locales. */
     supportsExcludedStatus: boolean;
+    /** The localization sources within this group. */
     sources: LocalizationSource[];
+    /**
+     * The status of each locale for this group. A localization group can have
+     * a different status in each locale (`"excluded"` or `"ready"`).
+     */
     statusByLocale: LocalizationGroupStatusByLocale;
 }
 type LocalizedValueUpdate = {
@@ -270,6 +334,7 @@ declare const fontWeights: readonly [100, 200, 300, 400, 500, 600, 700, 800, 900
  * - `900` - Black (Heavy)
  * */
 type FontWeight = (typeof fontWeights)[number];
+/** A font available in the project, including custom uploaded fonts. */
 declare class Font {
     /** An identifier used internally for differentiating fonts. */
     readonly selector: string;
@@ -546,9 +611,13 @@ interface WithReplicaInfoTrait {
     readonly originalId: string | null;
 }
 interface WithComponentVariantTrait {
+    /** Whether this is a component variant. Supported by FrameNode. */
     readonly isVariant: boolean;
+    /** Whether this is the primary variant. Supported by FrameNode. */
     readonly isPrimaryVariant: boolean;
+    /** Gesture state for component variants: `"hover"`, `"pressed"`, `"loading"`, or `"error"`. Supported by FrameNode. */
     readonly gesture: Gesture | null;
+    /** ID of the node this variant inherits from. Supported by FrameNode. */
     readonly inheritsFromId: string | null;
 }
 interface IsComponentVariant {
@@ -560,16 +629,31 @@ interface IsComponentGestureVariant extends IsComponentVariant {
     readonly gesture: Gesture;
 }
 interface WithNameTrait {
+    /**
+     * The name of the node displayed in the layers panel.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode,
+     * ComponentNode, VectorSetNode, VectorSetItemNode.
+     */
     readonly name: string | null;
 }
 interface WithVisibleTrait {
+    /**
+     * Whether the node is visible on the canvas. Defaults to `true`.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode, VectorSetItemNode.
+     */
     readonly visible: boolean;
 }
 interface WithLockedTrait {
+    /**
+     * Whether the node is locked for editing. Defaults to `false`.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode, VectorSetItemNode.
+     */
     readonly locked: boolean;
 }
 interface WithBreakpointTrait {
+    /** Whether this is a breakpoint. Supported by FrameNode. */
     readonly isBreakpoint: boolean;
+    /** Whether this is the primary breakpoint. Supported by FrameNode. */
     readonly isPrimaryBreakpoint: boolean;
 }
 interface IsBreakpoint {
@@ -577,23 +661,41 @@ interface IsBreakpoint {
     readonly isPrimaryBreakpoint: boolean;
 }
 interface WithBackgroundColorTrait<T extends TraitVariant> {
-    /** Color of the frame in RGBA format, e.g `rgba(242, 59, 57, 1)`, or as a `ColorStyle` instance. */
+    /**
+     * Background color in RGBA format (e.g. `rgba(242, 59, 57, 1)`) or as a {@link ColorStyle} instance.
+     * Setting to `null` removes the background color. Supported by FrameNode.
+     */
     readonly backgroundColor: (T extends TraitVariantData ? ColorStyleData : ColorStyle) | string | null;
 }
 interface WithBackgroundImageTrait<T extends TraitVariant> {
+    /** Background image asset. Supported by FrameNode. */
     readonly backgroundImage: (T extends TraitVariantData ? ImageAssetData : ImageAsset) | null;
 }
 interface WithBackgroundGradientTrait<T extends TraitVariant> {
+    /** Background gradient (linear, radial, or conic). Supported by FrameNode. */
     readonly backgroundGradient: (T extends TraitVariantData ? GradientData : Gradient) | null;
 }
 interface WithRotationTrait {
+    /**
+     * Rotation angle in degrees. Defaults to `0`.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode.
+     */
     readonly rotation: number;
 }
 interface WithOpacityTrait {
+    /**
+     * Opacity of the node, from `0` (fully transparent) to `1` (fully opaque). Defaults to `1`.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode.
+     */
     readonly opacity: number;
 }
 type BorderRadius = CSSDimension<CSSUnit.Percentage | CSSUnit.Pixel> | `${CSSDimension<CSSUnit.Pixel>} ${CSSDimension<CSSUnit.Pixel>} ${CSSDimension<CSSUnit.Pixel>} ${CSSDimension<CSSUnit.Pixel>}` | null;
 interface WithBorderRadiusTrait {
+    /**
+     * Border radius for rounded corners. Single value (e.g. `"10px"` or `"50%"`)
+     * or per-corner (e.g. `"10px 20px 30px 40px"` for top-left, top-right, bottom-right, bottom-left).
+     * Setting to `null` removes the border radius. Supported by FrameNode.
+     */
     readonly borderRadius: BorderRadius;
 }
 type BorderWidth = CSSDimension<CSSUnit.Pixel> | `${CSSDimension<CSSUnit.Pixel>} ${CSSDimension<CSSUnit.Pixel>} ${CSSDimension<CSSUnit.Pixel>} ${CSSDimension<CSSUnit.Pixel>}`;
@@ -604,123 +706,271 @@ interface Border {
     style: BorderStyle;
 }
 interface WithBorderTrait<T extends TraitVariant> {
+    /**
+     * Border properties including width, color, and style.
+     * Styles: `"solid"`, `"dashed"`, `"dotted"`, `"double"`.
+     * Width can be per-side (e.g. `"1px 2px 3px 4px"`).
+     * Setting to `null` removes the border. Supported by FrameNode.
+     */
     readonly border: (T extends TraitVariantData ? Marshaled<Border> : Border) | null;
 }
+/** Controls how images are rendered. Use `"pixelated"` for pixel art. */
 type ImageRendering = "auto" | "pixelated";
 interface WithImageRenderingTrait {
+    /**
+     * How images should be rendered when scaled: `"auto"` or `"pixelated"`.
+     * Only applies to frames with image backgrounds.
+     * Setting to `null` uses default rendering. Supported by FrameNode.
+     */
     readonly imageRendering: ImageRendering | null;
 }
+/** Controls whether content that overflows the frame is clipped. */
 type Overflow = "visible" | "hidden" | "auto" | "clip";
 type AxisOverflow = Overflow;
 interface WithOverflowTrait {
+    /**
+     * Controls how content that exceeds the element's box is handled.
+     * Setting to `null` removes the overflow property. Will overwrite `overflowX` or `overflowY`.
+     * Supported by FrameNode, TextNode.
+     */
     readonly overflow: Overflow | null;
+    /**
+     * Controls horizontal overflow behavior.
+     * Setting to `null` removes the overflow X property. Supported by FrameNode, TextNode.
+     */
     readonly overflowX: AxisOverflow | null;
+    /**
+     * Controls vertical overflow behavior.
+     * Setting to `null` removes the overflow Y property. Supported by FrameNode, TextNode.
+     */
     readonly overflowY: AxisOverflow | null;
 }
 interface WithTextTruncationTrait {
+    /**
+     * Maximum number of lines a text node can display before being truncated with an ellipsis.
+     * Must be used alongside `overflow`. Setting to `null` removes the text truncation property.
+     * Supported by TextNode.
+     */
     readonly textTruncation: number | null;
 }
 interface WithZIndexTrait {
+    /**
+     * Stacking order of positioned elements. Higher values appear on top of lower values.
+     * Setting to `null` removes the z-index property. Supported by FrameNode, TextNode.
+     */
     readonly zIndex: number | null;
 }
 interface WithRequiredComponentInfoTrait {
+    /** Identifier of the component. Supported by ComponentInstanceNode, ComponentNode. */
     readonly componentIdentifier: string;
 }
 interface WithNullableComponentInfoTrait {
     readonly insertURL: string | null;
+    /** Name of the component. Supported by ComponentInstanceNode, ComponentNode. */
     readonly componentName: string | null;
 }
 interface WithComponentInfoTrait extends WithRequiredComponentInfoTrait, WithNullableComponentInfoTrait {
 }
 interface WithWebPageInfoTrait {
+    /** URL path for the web page. Supported by WebPageNode. */
     readonly path: string | null;
+    /** Collection ID for the web page. Supported by WebPageNode. */
     readonly collectionId: string | null;
 }
 interface WithLinkTrait {
+    /**
+     * URL or internal page link. External: `"https://example.com"`, internal: `"/about"`,
+     * email: `"mailto:user@example.com"`. Setting to `null` removes the link.
+     * Supported by FrameNode, TextNode.
+     */
     readonly link: string | null;
+    /**
+     * Whether to open the link in a new tab. Default is automatically determined based on link type.
+     * Supported by FrameNode, TextNode.
+     */
     readonly linkOpenInNewTab: boolean | null;
 }
 type ControlAttributes = Record<string, unknown>;
 interface WithControlAttributesTrait {
+    /** Property control values for code components. Supported by ComponentInstanceNode. */
     readonly controls: ControlAttributes;
 }
 interface WithSVGTrait {
+    /** SVG markup content. Supported by SVGNode. */
     readonly svg: string;
 }
+/** The CSS position property for a node. */
 type Position = "relative" | "absolute" | "fixed" | "sticky";
 interface WithPositionTrait {
+    /**
+     * Positioning behavior of the node.
+     * - `"relative"`: Default for nodes in stack/grid layouts
+     * - `"absolute"`: Positioned relative to parent
+     * - `"fixed"`: Positioned relative to viewport
+     * - `"sticky"`: Sticks to viewport edges when scrolling
+     *
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode.
+     */
     position: Position;
 }
 type FitContent = "fit-content";
 type FitImage = "fit-image";
 interface WithPinsTrait {
+    /**
+     * Distance from top edge when using absolute/fixed positioning.
+     * Only applies when position is not `"relative"`.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode, VectorSetItemNode.
+     */
     top: CSSDimension<CSSUnit.Pixel> | null;
+    /**
+     * Distance from right edge when using absolute/fixed positioning.
+     * Only applies when position is not `"relative"`.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode, VectorSetItemNode.
+     */
     right: CSSDimension<CSSUnit.Pixel> | null;
+    /**
+     * Distance from bottom edge when using absolute/fixed positioning.
+     * Only applies when position is not `"relative"`.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode, VectorSetItemNode.
+     */
     bottom: CSSDimension<CSSUnit.Pixel> | null;
+    /**
+     * Distance from left edge when using absolute/fixed positioning.
+     * Only applies when position is not `"relative"`.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode, VectorSetItemNode.
+     */
     left: CSSDimension<CSSUnit.Pixel> | null;
+    /**
+     * Center anchor horizontal position as percentage (e.g. `"50%"`).
+     * Used when pins are not set.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode, VectorSetItemNode.
+     */
     centerX: CSSDimension<CSSUnit.Percentage> | null;
+    /**
+     * Center anchor vertical position as percentage (e.g. `"50%"`).
+     * Used when pins are not set.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode, VectorSetItemNode.
+     */
     centerY: CSSDimension<CSSUnit.Percentage> | null;
 }
 type Length = CSSDimension<CSSUnit.Pixel | CSSUnit.Percentage | CSSUnit.Fraction>;
 type WidthLength = Length | FitContent | FitImage;
 type HeightLength = Length | FitContent | CSSDimension<CSSUnit.ViewportHeight> | FitImage;
 interface WithSizeTrait {
+    /**
+     * Width of the node. Accepts pixel, percentage, fraction values, or `"fit-content"`.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode, VectorSetItemNode.
+     */
     width: WidthLength | null;
+    /**
+     * Height of the node. Accepts pixel, percentage, fraction, viewport-height values, or `"fit-content"`.
+     * Supported by FrameNode, TextNode, SVGNode, ComponentInstanceNode, VectorSetItemNode.
+     */
     height: HeightLength | null;
 }
 interface WithAspectRatioTrait {
+    /**
+     * Width-to-height ratio (e.g. `1.5` for 3:2).
+     * Setting to `null` removes the aspect ratio constraint.
+     * Supported by FrameNode, ComponentInstanceNode.
+     */
     aspectRatio: number | null;
 }
 type WidthConstraint = CSSDimension<CSSUnit.Pixel | CSSUnit.Percentage>;
 type HeightConstraint = CSSDimension<CSSUnit.Pixel | CSSUnit.Percentage | CSSUnit.ViewportHeight>;
 interface WithSizeConstraintsTrait {
+    /** Maximum width constraint. Supported by FrameNode, TextNode, ComponentInstanceNode. */
     maxWidth: WidthConstraint | null;
+    /** Minimum width constraint. Supported by FrameNode, TextNode, ComponentInstanceNode. */
     minWidth: WidthConstraint | null;
+    /** Maximum height constraint. Supported by FrameNode, TextNode, ComponentInstanceNode. */
     maxHeight: HeightConstraint | null;
+    /** Minimum height constraint. Supported by FrameNode, TextNode, ComponentInstanceNode. */
     minHeight: HeightConstraint | null;
 }
 interface WithInlineTextStyleTrait<T extends TraitVariant> {
+    /**
+     * Apply a text style preset. Setting to `null` removes the text style.
+     * Supported by TextNode.
+     */
     readonly inlineTextStyle: (T extends TraitVariantData ? TextStyleData : TextStyle) | null;
 }
 interface WithFontTrait<T extends TraitVariant> {
+    /** Font selection for text. Supported by TextNode. */
     readonly font: (T extends TraitVariantData ? FontData : Font) | null;
 }
 type TraitVariantData = "data";
 type TraitVariantNode = "node";
+/** The direction children are laid out in a stack. */
 type StackDirection = "horizontal" | "vertical";
+/** How children are distributed along the main axis of a stack. */
 type StackDistribution = "start" | "center" | "end" | "space-between" | "space-around" | "space-evenly";
+/** How children are aligned along the cross axis of a stack. */
 type StackAlignment = "start" | "center" | "end";
+/** The layout type for a frame: `"stack"` (flex) or `"grid"` (CSS grid). */
 type LayoutType = "stack" | "grid";
 interface StackLayout {
+    /** Direction of items in a stack layout. Requires `layout: "stack"`. Supported by FrameNode. */
     stackDirection: StackDirection | null;
+    /** How items are distributed in a stack layout. Requires `layout: "stack"`. Supported by FrameNode. */
     stackDistribution: StackDistribution | null;
+    /** How items are aligned perpendicular to the stack direction. Requires `layout: "stack"`. Supported by FrameNode. */
     stackAlignment: StackAlignment | null;
+    /** Whether items should wrap to the next line. Requires `layout: "stack"`. Supported by FrameNode. */
     stackWrapEnabled: boolean | null;
 }
 type GridContentAlignment = "start" | "center" | "end";
 interface GridLayout {
+    /** Number of columns in the grid. Requires `layout: "grid"`. Supported by FrameNode. */
     gridColumnCount: number | "auto-fill" | null;
+    /** Number of rows in the grid. Requires `layout: "grid"`. Supported by FrameNode. */
     gridRowCount: number | null;
+    /** How items are aligned within the grid. Requires `layout: "grid"`. Supported by FrameNode. */
     gridAlignment: GridContentAlignment | null;
+    /** Type of column width sizing: `"fixed"` or `"minmax"`. Requires `layout: "grid"`. Supported by FrameNode. */
     gridColumnWidthType: "fixed" | "minmax" | null;
+    /** Width of grid columns in pixels. Requires `layout: "grid"`. Supported by FrameNode. */
     gridColumnWidth: number | null;
+    /** Minimum width of grid columns in pixels. Requires `layout: "grid"`. Supported by FrameNode. */
     gridColumnMinWidth: number | null;
+    /** Type of row height sizing: `"fixed"`, `"auto"`, or `"fit"`. Requires `layout: "grid"`. Supported by FrameNode. */
     gridRowHeightType: "fixed" | "auto" | "fit" | null;
+    /** Height of grid rows in pixels. Requires `layout: "grid"`. Supported by FrameNode. */
     gridRowHeight: number | null;
 }
 interface WithLayoutTrait extends StackLayout, GridLayout {
+    /**
+     * Enables stack or grid layout. Setting to `null` disables any applied layout.
+     * Operation is deferred and applied after the current update cycle. Supported by FrameNode.
+     */
     layout: LayoutType | null;
+    /**
+     * Spacing between items in a layout. Single value (e.g. `"10px"`) applies to both axes;
+     * two values (e.g. `"10px 20px"`) set horizontal and vertical separately.
+     * Only works with layout enabled. Supported by FrameNode.
+     */
     gap: CSSDimension<CSSUnit.Pixel> | `${CSSDimension<CSSUnit.Pixel>} ${CSSDimension<CSSUnit.Pixel>}` | null;
+    /**
+     * Inner spacing of a container with layout. Single value (e.g. `"10px"`) applies to all sides;
+     * four values (e.g. `"10px 20px 30px 40px"`) set top, right, bottom, left.
+     * Only works with layout enabled. Supported by FrameNode.
+     */
     padding: CSSDimension<CSSUnit.Pixel> | `${CSSDimension<CSSUnit.Pixel>} ${CSSDimension<CSSUnit.Pixel>} ${CSSDimension<CSSUnit.Pixel>} ${CSSDimension<CSSUnit.Pixel>}` | null;
 }
 type GridItemAlignment = "start" | "center" | "end";
 type GridItemColumnSpan = number | "all";
 interface WithGridItemTrait {
+    /** Whether to fill the grid cell width. For nodes inside a grid container. Defaults to `true`. Supported by FrameNode, TextNode. */
     gridItemFillCellWidth: boolean | null;
+    /** Whether to fill the grid cell height. For nodes inside a grid container. Defaults to `true`. Supported by FrameNode, TextNode. */
     gridItemFillCellHeight: boolean | null;
+    /** Horizontal alignment within grid cell. For nodes inside a grid container. Defaults to `"center"`. Supported by FrameNode, TextNode. */
     gridItemHorizontalAlignment: GridItemAlignment | null;
+    /** Vertical alignment within grid cell. For nodes inside a grid container. Defaults to `"center"`. Supported by FrameNode, TextNode. */
     gridItemVerticalAlignment: GridItemAlignment | null;
+    /** Number of columns to span, or `"all"` for all columns. For nodes inside a grid container. Defaults to `1`. Supported by FrameNode, TextNode. */
     gridItemColumnSpan: GridItemColumnSpan | null;
+    /** Number of rows to span. For nodes inside a grid container. Defaults to `1`. Supported by FrameNode, TextNode. */
     gridItemRowSpan: number | null;
 }
 type TraitVariant = TraitVariantData | TraitVariantNode;
@@ -789,8 +1039,42 @@ interface ColorStyleData extends RequiredColorStyleAttributes, OptionalColorStyl
     path: string;
 }
 type ColorStyleAttributes = Prettify<RequiredColorStyleAttributes & Partial<OptionalColorStyleAttributes> & AssetPath>;
+/**
+ * A reusable color style defined in the project. Supports light and dark
+ * theme variants. Color styles let you manage color appearances from one
+ * place in a project. In the UI, you can find them in the Assets panel.
+ * Plugins can use these styles to do things like sync design systems or
+ * check accessibility.
+ *
+ * Colors are stored in RGBA format, e.g. `rgba(242, 59, 57, 1)`. The
+ * `light` attribute is the default color used in light theme. The `dark`
+ * attribute is an optional color used in the dark theme.
+ *
+ * To organize color styles into folders, use `/` as a separator in the
+ * name, e.g. `"My Plugin/My Cool Color"`.
+ *
+ * @example
+ * ```ts
+ * // Create a new color style with light and dark variants.
+ * const colorStyle = await framer.createColorStyle({
+ *   name: "My Cool Color",
+ *   light: "rgba(242, 59, 57, 1)",
+ *   dark: "rgba(120, 22, 11, 1)"
+ * })
+ *
+ * // Update an existing color style.
+ * await colorStyle.setAttributes({ dark: "rgba(10, 10, 10, 0.2)" })
+ *
+ * // Remove a color style from the project.
+ * await colorStyle.remove()
+ *
+ * // Store plugin data on a color style.
+ * await colorStyle.setPluginData("key", "value")
+ * ```
+ */
 declare class ColorStyle {
     #private;
+    /** A unique identifier for the color style. */
     readonly id: NodeId;
     readonly name: string;
     /**
@@ -807,29 +1091,57 @@ declare class ColorStyle {
     static [$framerInternal.unmarshal](engine: PluginEngine, data: ColorStyleData): ColorStyle;
     [$framerInternal.marshal](): ColorStyleData;
     /**
-     * Set the attributes of a color style.
+     * Set the attributes of a color style. Attributes are merged with existing
+     * values, so only the provided attributes are updated.
+     *
+     * @param update - The attributes to update.
+     * @returns The updated color style, or `null` if the style was not found.
      *
      * Use `"ColorStyle.setAttributes"` to check if this method is allowed.
+     *
+     * @example
+     * ```ts
+     * await colorStyle.setAttributes({ dark: "rgba(10, 10, 10, 0.2)" })
+     * ```
      */
     setAttributes(update: Partial<ColorStyleAttributes>): Promise<ColorStyle | null>;
     /**
      * Get plugin data for this color style by key.
+     *
+     * @param key - The plugin data key.
+     * @returns The stored value, or `null` if no data exists for the key.
      */
     getPluginData(key: string): Promise<string | null>;
     /**
      * Set plugin data on this color style by key.
      *
+     * @param key - The plugin data key.
+     * @param value - The value to set, or `null` to remove.
+     *
      * Use `"ColorStyle.setPluginData"` to check if this method is allowed.
+     *
+     * @example
+     * ```ts
+     * await colorStyle.setPluginData("key", "value")
+     * ```
      */
     setPluginData(key: string, value: string | null): Promise<void>;
     /**
      * Get all plugin data keys for this color style.
+     *
+     * @returns An array of all plugin data keys set on this color style.
      */
     getPluginDataKeys(): Promise<string[]>;
     /**
-     * Deletes the color style from the project.
+     * Deletes the color style from the project. You need a reference to the
+     * style to call this method.
      *
      * Use `"ColorStyle.remove"` to check if this method is allowed.
+     *
+     * @example
+     * ```ts
+     * await colorStyle.remove()
+     * ```
      */
     remove(): Promise<void>;
 }
@@ -885,6 +1197,60 @@ type TextStyleAttributes = Prettify<Partial<Omit<TextStyleData, "id" | "color" |
     boldItalicFont: Font | null;
     breakpoints: TextStyleBreakpointAttributes[];
 }> & AssetPath>;
+/**
+ * A reusable text style defined in the project, including font, size,
+ * color, and responsive breakpoints. Text styles let you manage text
+ * appearances from one place in a project. In the UI, you can find them
+ * in the Assets panel.
+ *
+ * Text styles support responsive breakpoints that apply different values
+ * at different window widths. A maximum of four breakpoints can be added.
+ * Breakpoints are automatically ordered from largest to smallest `minWidth`.
+ * Each breakpoint must have a unique `minWidth` value.
+ *
+ * By default, text styles use a built-in font. Use
+ * {@link Font} to customize a text style's typeface. All font variants
+ * (bold, italic, boldItalic) must share the same font family as the base
+ * font.
+ *
+ * To organize text styles into folders, use `/` as a separator in the
+ * name, e.g. `"My Plugin/Heading"`.
+ *
+ * @example
+ * ```ts
+ * // Create a new text style.
+ * const textStyle = await framer.createTextStyle({
+ *   name: "Heading",
+ *   tag: "h1",
+ *   fontSize: "30px",
+ *   lineHeight: "1.6em",
+ * })
+ *
+ * // Create a text style with responsive breakpoints.
+ * const textStyle = await framer.createTextStyle({
+ *   fontSize: "24px",
+ *   minWidth: 1280,
+ *   breakpoints: [
+ *     { minWidth: 1024, fontSize: "18px" },
+ *     { minWidth: 320, fontSize: "16px" }
+ *   ]
+ * })
+ *
+ * // Update an existing text style.
+ * await textStyle.setAttributes({
+ *   color: "rgba(242, 59, 57, 1)"
+ * })
+ *
+ * // Create a text style with a custom font.
+ * const font = await framer.getFont("Open Sans")
+ * if (font) {
+ *   const textStyle = await framer.createTextStyle({ font })
+ * }
+ *
+ * // Remove a text style from the project.
+ * await textStyle.remove()
+ * ```
+ */
 declare class TextStyle {
     #private;
     readonly id: NodeId;
@@ -980,33 +1346,85 @@ declare class TextStyle {
     static [$framerInternal.unmarshal](engine: PluginEngine, data: TextStyleData): TextStyle;
     [$framerInternal.marshal](): TextStyleData;
     /**
-     * Set the attributes of the text style.
+     * Set the attributes of the text style. All attributes except
+     * `breakpoints` are merged with existing values. When setting
+     * `breakpoints`, the provided array replaces any existing breakpoints
+     * entirely. To update breakpoints without overriding them all, iterate
+     * over the existing breakpoints and merge them.
      *
+     * @param attributes - The attributes to update.
+     * @returns The updated text style, or `null` if the style was not found.
      * @throws If the number of breakpoints is bigger than the limit of 4.
      * @throws If any of the font families used for `boldFont`, `italicFont` and
      * `boldItalicFont` do not match the family of `font`.
      *
      * Use `"TextStyle.setAttributes"` to check if this method is allowed.
+     *
+     * @example
+     * ```ts
+     * // Update the color of a text style.
+     * const textStyle = await framer.getTextStyle("text-style-id")
+     * if (textStyle) {
+     *   await textStyle.setAttributes({
+     *     color: "rgba(242, 59, 57, 1)"
+     *   })
+     * }
+     *
+     * // Replace breakpoints on a text style.
+     * await textStyle.setAttributes({
+     *   breakpoints: [
+     *     { minWidth: 320, fontSize: "24px" }
+     *   ]
+     * })
+     *
+     * // Scale font sizes across all breakpoints without losing them.
+     * await textStyle.setAttributes({
+     *   fontSize: parseInt(textStyle.fontSize) * 0.8 + "px",
+     *   breakpoints: textStyle.breakpoints.map((bp) => ({
+     *     ...bp,
+     *     fontSize: parseInt(bp.fontSize) * 0.8 + "px"
+     *   }))
+     * })
+     * ```
      */
     setAttributes(attributes: TextStyleAttributes): Promise<TextStyle | null>;
     /**
      * Get plugin data for this text style by key.
+     *
+     * @param key - The plugin data key.
+     * @returns The stored value, or `null` if no data exists for the key.
      */
     getPluginData(key: string): Promise<string | null>;
     /**
      * Set plugin data on this text style by key.
      *
+     * @param key - The plugin data key.
+     * @param value - The value to set, or `null` to remove.
+     *
      * Use `"TextStyle.setPluginData"` to check if this method is allowed.
+     *
+     * @example
+     * ```ts
+     * await textStyle.setPluginData("key", "value")
+     * ```
      */
     setPluginData(key: string, value: string | null): Promise<void>;
     /**
      * Get all plugin data keys for this text style.
+     *
+     * @returns An array of all plugin data keys set on this text style.
      */
     getPluginDataKeys(): Promise<string[]>;
     /**
-     * Deletes the text style from the project.
+     * Deletes the text style from the project. You need a reference to
+     * the style to call this method.
      *
      * Use `"TextStyle.remove"` to check if this method is allowed.
+     *
+     * @example
+     * ```ts
+     * await textStyle.remove()
+     * ```
      */
     remove(): Promise<void>;
 }
@@ -1303,20 +1721,49 @@ interface EnumCaseData extends WithId, WithName, WithNameByLocale {
 }
 interface UpdateEnumCase extends Partial<WithName>, Partial<WithNameByLocaleUpdate> {
 }
+/** An individual case (option) within an Enum Field or Enum Variable. */
 declare class EnumCase {
     #private;
+    /** A unique identifier for the enum case. */
     get id(): string;
+    /** The display name of the enum case. */
     get name(): string;
+    /**
+     * Localized values for the name of this enum case.
+     *
+     * @example
+     * ```ts
+     * const dutchName = enumCase.nameByLocale[dutchLocale.id] // "Naam"
+     * ```
+     */
     get nameByLocale(): InlineLocalizationValueByLocale;
     constructor(engine: PluginEngine, nodeId: string, variableId: string, enumCaseData: EnumCaseData);
     /**
-     * Update a mutable enum case property, for example the name.
+     * Update the attributes of this enum case.
+     *
+     * @example
+     * ```ts
+     * enumCase.setAttributes({
+     * 	name: "New Name",
+     * 	nameByLocale: {
+     * 		nl: { action: "set", value: "Nieuwe naam" }
+     * 	}
+     * })
+     * ```
+     *
+     * @param attributes - The attributes to update: `name` and/or `nameByLocale`.
+     * @returns The updated `EnumCase`, or `null` if the case was removed before the update.
      *
      * Use `"EnumCase.setAttributes"` to check if this method is allowed.
      */
     setAttributes(attributes: UpdateEnumCase): Promise<EnumCase | null>;
     /**
-     * Remove the enum case.
+     * Remove this enum case from its parent enum field.
+     *
+     * @example
+     * ```ts
+     * enumCase.remove()
+     * ```
      *
      * Use `"EnumCase.remove"` to check if this method is allowed.
      */
@@ -1574,10 +2021,16 @@ type UpdateFieldAttributes<T extends {
 }>, // This is NOT the same as Extract<UpdateField, T>
 // This is NOT the same as Extract<UpdateField, T>
 "id" | "type">;
+/**
+ * Base class for all CMS Collection field types. Use the `type` property
+ * to narrow to a specific field class.
+ */
 declare abstract class FieldBase {
     #private;
     abstract readonly type: FieldDefinitionData["type"];
+    /** The unique identifier of the field. */
     get id(): string;
+    /** The display name of the field as shown in the UI. */
     get name(): string;
     constructor(engine: PluginEngine, collectionId: string, data: FieldDefinitionBase);
     /**
@@ -1597,6 +2050,8 @@ declare abstract class FieldBase {
      * Returns the updated field on success, and `null` in the unlikely event of it being removed
      * between getting it and calling this method.
      *
+     * @param attributes - The attributes to update.
+     *
      * Use `"Field.setAttributes"` to check if this method is allowed.
      */
     setAttributes(attributes: UpdateFieldAttributes<typeof this>): Promise<typeof this | null>;
@@ -1609,88 +2064,143 @@ declare abstract class FieldBase {
 }
 declare abstract class FieldBaseWithRequired extends FieldBase implements WithFieldRequired {
     #private;
+    /** Whether this field is required. Required fields must have a value set on every CMS item. */
     get required(): boolean;
     constructor(engine: PluginEngine, collectionId: string, data: FieldDefinitionBase & WithFieldRequired);
 }
+/** A CMS Collection field that stores a boolean (true or false) value. */
 declare class BooleanField extends FieldBase {
     readonly type = "boolean";
 }
+/** A CMS Collection field that stores a color value (RGBA/HSL/HEX format). */
 declare class ColorField extends FieldBase {
     readonly type = "color";
 }
+/** A CMS Collection field that stores a numeric value. */
 declare class NumberField extends FieldBase {
     readonly type = "number";
 }
+/** A CMS Collection field that stores a text string value. */
 declare class StringField extends FieldBaseWithRequired implements WithFieldBasedOn {
     #private;
     readonly type = "string";
     constructor(engine: PluginEngine, collectionId: string, data: StringFieldDefinitionData);
     get basedOn(): string | null;
 }
+/** A CMS Collection field that stores HTML-formatted text content (H1-H6, P, and other standard content elements). */
 declare class FormattedTextField extends FieldBaseWithRequired {
     readonly type = "formattedText";
 }
+/** A CMS Collection field that stores an image asset (`ImageAsset`). */
 declare class ImageField extends FieldBaseWithRequired {
     readonly type = "image";
 }
+/** A CMS Collection field that stores a URL in string format. */
 declare class LinkField extends FieldBaseWithRequired {
     readonly type = "link";
 }
+/** A CMS Collection field that stores a date in UTC format. Optionally displays time. */
 declare class DateField extends FieldBaseWithRequired {
     #private;
     readonly type = "date";
+    /** Controls whether time is enabled on this date field. */
     get displayTime(): boolean | undefined;
     constructor(engine: PluginEngine, collectionId: string, data: DateFieldDefinitionData);
 }
+/** A visual divider between fields in the CMS UI. Not a data field. */
 declare class FieldDivider extends FieldBase {
     readonly type = "divider";
 }
+/**
+ * A field type that is not yet supported by the plugin API.
+ * Returned when Framer uses a field type that the plugin API does not recognize.
+ */
 declare class UnsupportedField extends FieldBase {
     readonly type = "unsupported";
 }
+/** A CMS Collection field that stores a file asset (`FileAsset`). */
 declare class FileField extends FieldBaseWithRequired implements WithAllowedFileTypes {
     #private;
     readonly type = "file";
-    /** @inheritdoc */
+    /** The file extensions that are allowed for uploads to this field, e.g. `["pdf", "txt"]`. */
     get allowedFileTypes(): string[];
     constructor(engine: PluginEngine, collectionId: string, data: FileFieldDefinitionData);
 }
+/**
+ * A CMS Collection field with a fixed set of enum cases (options) that the user
+ * can choose from. Enum cases must be defined as options before they can be
+ * assigned to CMS items.
+ */
 declare class EnumField extends FieldBase {
     #private;
     readonly type = "enum";
+    /** The available enum cases for this field. */
     get cases(): readonly EnumCase[];
     constructor(engine: PluginEngine, collectionId: string, data: EnumFieldDefinitionData);
     /**
-     * Add a new enum case.
+     * Add a new enum case to this field.
+     *
+     * @example
+     * ```ts
+     * await enumField.addCase({
+     * 	name: "Name",
+     * 	nameByLocale: {
+     * 		nl: { action: "set", value: "Naam" }
+     * 	}
+     * })
+     * ```
+     *
+     * @param attributes - An object with the enum case name and optional localized names.
+     * @returns The newly created `EnumCase`, or `null` if the case could not be added.
      *
      * Use `"EnumField.addCase"` to check if this method is allowed.
      */
     addCase(attributes: CreateEnumCase): Promise<EnumCase | null>;
     /**
-     * Arrange enum cases in a specific order.
+     * Set the order of the enum field's cases.
+     *
+     * @example
+     * ```ts
+     * const alphabeticalCaseOrder = enumField.cases
+     * 	.toSorted((a, b) => a.name.localeCompare(b.name))
+     * 	.map(({ id }) => id)
+     * await enumField.setCaseOrder(alphabeticalCaseOrder)
+     * ```
+     *
+     * @param caseIds - An array of the IDs of all enum cases, in the desired new order.
      *
      * Use `"EnumField.setCaseOrder"` to check if this method is allowed.
      */
     setCaseOrder(caseIds: string[]): Promise<void>;
 }
+/** A field that references an item in another collection. */
 declare class CollectionReferenceField extends FieldBaseWithRequired implements WithFieldCollectionId {
     #private;
     readonly type = "collectionReference";
+    /** The ID of the referenced collection. */
     get collectionId(): string;
     constructor(engine: PluginEngine, collectionId: string, data: CollectionReferenceFieldDefinitionData);
 }
+/** A field that references multiple items in another collection. */
 declare class MultiCollectionReferenceField extends FieldBaseWithRequired implements WithFieldCollectionId {
     #private;
     readonly type = "multiCollectionReference";
+    /** The ID of the referenced collection. */
     get collectionId(): string;
     constructor(engine: PluginEngine, collectionId: string, data: MultiCollectionReferenceFieldDefinitionData);
 }
 type ArrayItemField = ImageField;
+/**
+ * A CMS Collection field that stores an array of nested fields. Currently only
+ * supports a single image field, which creates a Gallery in the CMS.
+ */
 declare class ArrayField extends FieldBaseWithRequired {
     readonly type = "array";
+    /** The nested fields within this array field. Currently limited to a single image field. */
     readonly fields: readonly [ArrayItemField];
     constructor(engine: PluginEngine, collectionId: string, data: ArrayFieldDefinitionData);
 }
+/** Union of all CMS Collection field types. */
 type Field = BooleanField | ColorField | NumberField | StringField | FormattedTextField | ImageField | LinkField | DateField | FieldDivider | UnsupportedField | FileField | EnumField | CollectionReferenceField | MultiCollectionReferenceField | ArrayField;
 declare function isField(value: unknown): value is FieldBase;
 
@@ -2253,6 +2763,18 @@ interface WithUserEditable {
 type ManagedCollectionField = SupportedFieldDefinitionData & WithUserEditable;
 /** @deprecated Use `ManagedCollectionFieldInput` instead. */
 type EditableManagedCollectionField = ManagedCollectionFieldInputData;
+/**
+ * A CMS Collection that is fully controlled by a plugin. Managed Collections
+ * allow plugins to define fields and sync items programmatically. Fields and
+ * items can only be added, edited, and deleted by the owning plugin, not by
+ * the user (unless a field is marked `userEditable`).
+ *
+ * A Managed Collection plugin becomes available within the CMS when it supports
+ * both `configureManagedCollection` and `syncManagedCollection` modes.
+ *
+ * Use `framer.getManagedCollection()` to obtain an instance when the plugin is
+ * launched in either of those modes.
+ */
 declare class ManagedCollection implements Navigable {
     #private;
     readonly id: NodeId;
@@ -2264,54 +2786,161 @@ declare class ManagedCollection implements Navigable {
      */
     readonly readonly: boolean;
     /**
-     * Collections managed by other plugins should are read-only.
+     * Returns who manages this Collection.
+     *
+     * - `"thisPlugin"` if the Collection is managed by the current plugin.
+     * - `"anotherPlugin"` if the Collection is managed by a different plugin.
+     *
+     * Collections managed by other plugins are read-only.
      */
     readonly managedBy: ManagedCollectionManagedBy;
     constructor(data: CollectionData, engine: PluginEngine);
     /**
-     * Get item keys in their set order.
+     * Retrieve all item IDs in this Managed Collection, in their current order.
+     *
+     * @returns An array of item IDs.
+     *
+     * @example
+     * ```ts
+     * const itemIds = await collection.getItemIds()
+     * ```
      */
     getItemIds(): Promise<string[]>;
     /**
-     * Arrange items in a specific order.
+     * Arrange CMS items in a specific order.
      *
      * Use `"ManagedCollection.setItemOrder"` to check if this method is allowed.
+     *
+     * @param ids - An array of item IDs in the desired order. Unknown IDs are ignored.
+     *
+     * @example
+     * ```ts
+     * await collection.setItemOrder([item3.id, item1.id, item2.id])
+     * ```
      */
     setItemOrder(ids: string[]): Promise<void>;
     /**
-     * Get all fields.
+     * Get all fields defined on this Managed Collection.
+     *
+     * @returns An array of managed collection field definitions.
+     *
+     * @example
+     * ```ts
+     * const fields = await collection.getFields()
+     * ```
      */
     getFields(): Promise<ManagedCollectionField[]>;
     /**
-     * Create, update or remove all fields in one go.
+     * Add, update, or remove Collection fields. Fields not included in the
+     * array will be removed. You can configure up to 30 custom fields.
+     *
+     * Each field requires an `id`, `name`, and `type`. For the `id`, use a
+     * unique identifier that stays the same across future synchronizations.
+     * Any change in `id` can break data assignments on the canvas. The maximum
+     * length for an `id` is 64 characters.
+     *
+     * By default, managed collection fields set by a plugin are not editable by
+     * users. Set `userEditable: true` on a field to allow user editing. Note
+     * that fields marked as `userEditable` can no longer have their values set
+     * by the plugin when using `addItems`.
      *
      * Use `"ManagedCollection.setFields"` to check if this method is allowed.
+     *
+     * @param fields - The array of fields that should be used for the collection.
+     *
+     * @example
+     * ```ts
+     * await collection.setFields([
+     *   { id: "1", type: "string", name: "Name" },
+     *   { id: "2", type: "number", name: "Age" },
+     *   { id: "3", type: "string", name: "Description", userEditable: true },
+     * ])
+     * ```
      */
     setFields(fields: ManagedCollectionFieldInput[]): Promise<void>;
     /**
-     * Add new items or update existing ones if their IDs match.
+     * Add new items or update existing ones if their IDs match. This method
+     * performs an upsert: items with matching IDs are updated, new IDs are
+     * inserted.
+     *
+     * Each item requires an `id` and `slug`. Custom field data is provided via
+     * the `fieldData` object, using field IDs as keys.
+     *
+     * Currently, calling `addItems` with existing item IDs merges the provided
+     * field data with the existing items' current field data, meaning any
+     * omitted fields remain unchanged. In version 4.0.0, this behavior will
+     * change to fully replace items, removing any fields not explicitly
+     * included. Always include all fields when updating existing items to avoid
+     * unexpected behavior.
      *
      * Use `"ManagedCollection.addItems"` to check if this method is allowed.
+     *
+     * @param items - An array of items to add or update.
+     *
+     * @example
+     * ```ts
+     * await collection.addItems([
+     *   {
+     *     id: "1",
+     *     slug: "item-1",
+     *     fieldData: {
+     *       [nameField.id]: { type: "string", value: "Eric" },
+     *       [ageField.id]: { type: "number", value: 47 },
+     *     },
+     *   },
+     * ])
+     * ```
      */
     addItems(items: ManagedCollectionItemInput[]): Promise<void>;
     /**
-     * Remove items by their ID.
+     * Remove CMS items by their ID.
      *
      * Use `"ManagedCollection.removeItems"` to check if this method is allowed.
+     *
+     * @param itemIds - The IDs of the items to remove.
+     *
+     * @example
+     * ```ts
+     * await collection.removeItems([item1.id, item5.id])
+     * ```
      */
     removeItems(itemIds: string[]): Promise<void>;
     /**
-     * Make this the active collection.
+     * Open this Collection in the Editor, making it the active selection in
+     * the Framer UI.
+     *
+     * @example
+     * ```ts
+     * await collection.setAsActive()
+     * ```
      */
     setAsActive(): Promise<void>;
     /**
-     * Set plugin data by key.
+     * Set plugin data by key. Similar to local storage, you can store custom
+     * data on the Managed Collection (e.g., the last synchronization date or a
+     * connected database ID).
      *
      * Use `"ManagedCollection.setPluginData"` to check if this method is allowed.
+     *
+     * @param key - The plugin data key.
+     * @param value - The value to set, or `null` to remove.
+     *
+     * @example
+     * ```ts
+     * const currentDate = new Date().toISOString()
+     * await collection.setPluginData("lastSynchronizedAt", currentDate)
+     * ```
      */
     setPluginData(key: string, value: string | null): Promise<void>;
     /**
      * Get plugin data by key.
+     *
+     * @param key - The plugin data key.
+     *
+     * @example
+     * ```ts
+     * const lastSynchronized = await collection.getPluginData("lastSynchronizedAt")
+     * ```
      */
     getPluginData(key: string): Promise<string | null>;
     /**
@@ -2323,93 +2952,222 @@ declare class ManagedCollection implements Navigable {
      */
     navigateTo(opts?: NavigableOptions): Promise<void>;
 }
+/**
+ * A CMS Collection in the project. Collections can be created by users or
+ * managed by plugins. Use `managedBy` to check the owner.
+ *
+ * Any kind of Collection can be read from. Unmanaged Collections are those
+ * created and updated by people. Use the `collection` mode to access CMS
+ * data from your plugin.
+ */
 declare class Collection implements Navigable {
     #private;
     readonly id: NodeId;
     readonly name: string;
+    /**
+     * The name of the field used as the slug.
+     *
+     * - Only Collections that are not managed by a Plugin will have this value set.
+     */
     readonly slugFieldName: string | null;
+    /**
+     * The ID of the field the slug is based on.
+     *
+     * - Only Collections that are not managed by a Plugin will have this value set.
+     */
     readonly slugFieldBasedOn: string | null;
     /**
+     * Whether this Collection is read-only.
+     *
+     * A Collection is considered read-only if:
+     * - The plugin operates in a view-only mode (e.g., user does not have
+     *   permission to edit content).
+     * - The Collection is managed by another plugin.
+     *
+     * Read-only Collections cannot be modified via the API.
+     *
      * @deprecated Use `managedBy` instead and the [Permissions
      * API](https://www.framer.com/developers/plugins-permissions) to check if users can edit the
      * collection.
      */
     readonly readonly: boolean;
     /**
-     * Collections managed by plugins are read-only. To be able to modify them use
-     * `ManagedCollection` (which is only possible in `configureManagedCollection` or
+     * Returns who manages this Collection.
+     *
+     * - `"user"` if the Collection is user-created.
+     * - `"thisPlugin"` if the Collection is managed by the current plugin.
+     * - `"anotherPlugin"` if the Collection is managed by another plugin.
+     *
+     * Collections managed by plugins are read-only. To modify them, use
+     * `ManagedCollection` (only possible in `configureManagedCollection` or
      * `syncManagedCollection` modes).
+     *
+     * Note: the plugin still needs to check if the user has permission to edit
+     * content via `framer.isAllowedTo`.
+     *
+     * @example
+     * ```ts
+     * const collection = await framer.getActiveCollection()
+     *
+     * if (framer.mode === "collection" && collection.managedBy !== "user") {
+     *   framer.notify("This Collection cannot be modified.", { variant: "warning" })
+     * }
+     * ```
      */
     readonly managedBy: CollectionManagedBy;
     constructor(data: CollectionData, engine: PluginEngine);
     /**
-     * Arrange items in a specific order.
+     * Reorder the items in this Collection based on an array of item IDs.
+     * Unknown item IDs are ignored.
      *
      * Use `"Collection.setItemOrder"` to check if this method is allowed.
-     */
-    setItemOrder(ids: NodeId[]): Promise<void>;
-    /**
-     * Get all fields.
+     *
+     * @param ids - An array of item IDs representing the desired order.
+     *
+     * @example
+     * ```ts
+     * await collection.setItemOrder([item3.id, item1.id, item2.id])
+     * ```
+     */
+    setItemOrder(ids: NodeId[]): Promise<void>;
+    /**
+     * Fetch all fields defined on this Collection, including dividers.
+     *
+     * Some fields might not be fully supported by the API; unsupported fields
+     * will be returned with an `unsupported` field type.
+     *
+     * @returns An array of Field instances.
+     *
+     * @example
+     * ```ts
+     * const fields = await collection.getFields()
+     * ```
      */
     getFields(): Promise<Field[]>;
     /**
-     * Create new fields. Use `Field.setAttributes` to update.
+     * Create new unmanaged Collection fields. Use `Field.setAttributes` to
+     * update existing fields.
      *
      * Use `"Collection.addFields"` to check if this method is allowed.
+     *
+     * @param fields - The array of fields that should be added to the collection.
+     * @returns The newly created Field instances.
+     *
+     * @example
+     * ```ts
+     * const createdFields = await collection.addFields([
+     *   { type: "string", name: "Name" },
+     *   { type: "enum", name: "Status", cases: [{ name: "New" }, { name: "Done" }] },
+     *   { type: "file", name: "Text", allowedFileTypes: ["md"] },
+     *   { type: "collectionReference", name: "Author", collectionId: "ASh5SZOh" },
+     * ])
+     * ```
      */
     addFields(fields: CreateField[]): Promise<Field[]>;
     /**
-     * Remove fields by their ID.
+     * Remove fields from this Collection by their IDs.
      *
      * Use `"Collection.removeFields"` to check if this method is allowed.
+     *
+     * @param fieldIds - An array of field IDs to remove.
+     *
+     * @example
+     * ```ts
+     * await collection.removeFields([field3.id, field4.id])
+     * ```
      */
     removeFields(fieldIds: string[]): Promise<void>;
     /**
-     * Arrange fields in a specific order.
+     * Reorder the fields in this Collection based on an array of field IDs.
+     * Unknown field IDs are ignored.
      *
      * Use `"Collection.setFieldOrder"` to check if this method is allowed.
+     *
+     * @param fieldIds - An array of field IDs representing the desired order.
+     *
+     * @example
+     * ```ts
+     * await collection.setFieldOrder([nameField.id, ageField.id])
+     * ```
      */
     setFieldOrder(fieldIds: string[]): Promise<void>;
     /**
-     * Get all items in their set order.
+     * Retrieve all items within this Collection, in their current order.
+     * Items may include drafts (unpublished items).
+     *
+     * @returns An array of CollectionItem instances.
+     *
+     * @example
+     * ```ts
+     * const items = await collection.getItems()
+     * ```
      */
     getItems(): Promise<CollectionItem[]>;
     /**
-     * Add new items or update existing ones if their IDs are provided.
+     * Add new items to this Collection, or update existing ones if their IDs
+     * match.
      *
-     * This creates a new item with "foo" as its slug:
+     * - If an `id` is provided and matches an existing item, that item will be
+     *   updated.
+     * - Items without an `id` are created as new records.
+     * - `slug` should be unique.
      *
-     * ```ts
-     * collection.addItems([{ slug: "foo" }])
-     * ```
+     * Use `"Collection.addItems"` to check if this method is allowed.
      *
-     * This updates an existing item with ID "aBc123" to have "bar" as its slug:
+     * @param items - An array of items to add or update.
      *
+     * @example
      * ```ts
-     * collection.addItems([{ id: "aBc123", slug: "bar" }])
-     * ```
+     * // Create a new item
+     * await collection.addItems([{
+     *   slug: "eric",
+     *   fieldData: {
+     *     [nameField.id]: { type: "string", value: "Eric" },
+     *     [ageField.id]: { type: "number", value: 47 },
+     *   },
+     * }])
      *
-     * Use `"Collection.addItems"` to check if this method is allowed.
+     * // Update an existing item
+     * await collection.addItems([{ id: "aBc123", slug: "bar" }])
+     * ```
      */
     addItems(items: CollectionItemInput[]): Promise<void>;
     /**
-     * Remove items by their ID.
+     * Remove items from this Collection by their IDs.
      *
      * Use `"Collection.removeItems"` to check if this method is allowed.
+     *
+     * @param itemIds - An array of item IDs to remove.
+     *
+     * @example
+     * ```ts
+     * await collection.removeItems([item3.id, item4.id])
+     * ```
      */
     removeItems(itemIds: NodeId[]): Promise<void>;
     /**
-     * Make this the active collection.
+     * Set this Collection as active, changing the selected Collection in the
+     * Framer UI.
+     *
+     * @example
+     * ```ts
+     * await collection.setAsActive()
+     * ```
      */
     setAsActive(): Promise<void>;
     /**
      * Set plugin data by key.
      *
      * Use `"Collection.setPluginData"` to check if this method is allowed.
+     *
+     * @param key - The plugin data key.
+     * @param value - The value to set, or `null` to remove.
      */
     setPluginData(key: string, value: string | null): Promise<void>;
     /**
      * Get plugin data by key.
+     *
+     * @param key - The plugin data key.
      */
     getPluginData(key: string): Promise<string | null>;
     /**
@@ -2421,36 +3179,77 @@ declare class Collection implements Navigable {
      */
     navigateTo(opts?: NavigableOptions): Promise<void>;
 }
+/**
+ * An item (row) in a CMS Collection. Each item contains field data keyed by
+ * field ID, a unique slug, and a draft status.
+ */
 declare class CollectionItem implements Navigable {
     #private;
+    /** A unique identifier for this Collection item. */
     readonly id: NodeId;
     /** External ID for managed collections, unique node ID otherwise. */
     readonly nodeId: NodeId;
+    /** Slug value of the CMS item. Slugs should be unique within a Collection. */
     readonly slug: string;
     readonly slugByLocale: InlineLocalizationValueByLocale;
+    /** Drafts are excluded from publishing. */
     readonly draft: boolean;
+    /**
+     * The fields and corresponding values of this Collection item. Field data
+     * uses the field `id` as keys in an object.
+     *
+     * @example
+     * ```ts
+     * const titleFieldData = collectionItem.fieldData[titleField.id]
+     * console.log(titleFieldData.value) // "Getting Started"
+     * ```
+     */
     readonly fieldData: Readonly<FieldData>;
     constructor(collectionItemData: CollectionItemSerializableData, engine: PluginEngine);
     /**
-     * Remove this item.
+     * Remove this item from the Collection.
      *
      * Use `"CollectionItem.remove"` to check if this method is allowed.
+     *
+     * @example
+     * ```ts
+     * await collectionItem.remove()
+     * ```
      */
     remove(): Promise<void>;
     /**
-     * Update the item.
+     * Set the values of the fields of this CMS item. May return `null` if the
+     * item was deleted before this method was called.
      *
      * Use `"CollectionItem.setAttributes"` to check if this method is allowed.
+     *
+     * @param update - The updated attributes for the collection item.
+     * @returns The updated CollectionItem, or `null` if the item no longer exists.
+     *
+     * @example
+     * ```ts
+     * const updatedItem = await collectionItem.setAttributes({
+     *   slug: "new-slug",
+     *   fieldData: {
+     *     [ageField.id]: { type: "number", value: 48 },
+     *   },
+     * })
+     * ```
      */
     setAttributes(update: EditableCollectionItemAttributes): Promise<CollectionItem | null>;
     /**
      * Set plugin data by key.
      *
      * Use `"CollectionItem.setPluginData"` to check if this method is allowed.
+     *
+     * @param key - The plugin data key.
+     * @param value - The value to set, or `null` to remove.
      */
     setPluginData(key: string, value: string | null): Promise<void>;
     /**
      * Get plugin data by key.
+     *
+     * @param key - The plugin data key.
      */
     getPluginData(key: string): Promise<string | null>;
     /**
@@ -2458,11 +3257,23 @@ declare class CollectionItem implements Navigable {
      */
     getPluginDataKeys(): Promise<string[]>;
     /**
-     * Navigate to this collection item. May switch modes to reveal the relevant view.
+     * Navigate the UI to this Collection item. May switch modes to reveal the
+     * relevant view, such as the CMS editor.
+     *
+     * @param opts - Optional navigation options, such as scrolling to a
+     *   specific field.
+     *
+     * @example
+     * ```ts
+     * await collectionItem.navigateTo({
+     *   scrollTo: { collectionFieldId: fieldId },
+     * })
+     * ```
      */
     navigateTo(opts?: NavigableOptions): Promise<void>;
 }
 
+/** Options for controlling the `zoomIntoView` behavior. */
 interface ZoomIntoViewOptions {
     /**
      * Set a percentage limit for the maximum zoom level.
@@ -2505,6 +3316,34 @@ interface NodeClassToEditableAttributes {
     VectorSetItemNode: EditableVectorSetItemNodeAttributes;
     UnknownNode: object;
 }
+/**
+ * Base class providing common methods shared by all node types. Nodes are
+ * the building blocks that make up the content in a project. They are
+ * represented as "layers" in the editor UI.
+ *
+ * Every node has a unique {@link NodeMethods.id | id}. Nodes support
+ * plugin data storage, tree traversal (parent/children), cloning,
+ * removal, and attribute updates.
+ *
+ * Every node has an {@link NodeMethods.isReplica | isReplica} property
+ * that indicates if the node is a replica. Replica nodes are used within
+ * non-primary breakpoints and component variants, and inherit attributes
+ * from the primary variant or breakpoint. Once a specific attribute is
+ * overridden on a replica node, it is no longer inherited from the
+ * primary node.
+ *
+ * @example
+ * ```ts
+ * // Get selected nodes.
+ * const selection = await framer.getSelection()
+ *
+ * // Get a node by ID.
+ * const node = await framer.getNode("some-node-id")
+ *
+ * // Get all frame nodes in a project.
+ * const frameNodes = await framer.getNodesWithType("FrameNode")
+ * ```
+ */
 declare abstract class NodeMethods implements WithIdTrait, Navigable {
     #private;
     abstract readonly [classKey]: PluginNodeClass;
@@ -2513,33 +3352,45 @@ declare abstract class NodeMethods implements WithIdTrait, Navigable {
     constructor(data: SomeNodeData, engine: PluginEngine);
     get isReplica(): boolean;
     /**
-     * Remove this node.
+     * Remove this node from the canvas tree.
      *
      * Use `"Node.remove"` to check if this method is allowed.
      */
     remove(): Promise<void>;
     /**
-     * Select this node.
+     * Select this node on the canvas.
      */
     select(): Promise<void>;
     /**
-     * Clone this node.
+     * Clone this node, creating a duplicate in the canvas tree.
+     *
+     * @returns The cloned node, or `null` if the clone failed.
+     * @throws If the node is an `UnknownNode`.
      *
      * Use `"Node.clone"` to check if this method is allowed.
      */
     clone(): Promise<(typeof this)[ClassKey] extends "UnknownNode" ? never : typeof this | null>;
     /**
-     * Set the attributes of this node.
+     * Set the attributes of this node. Attributes are merged with existing
+     * values, so only the provided attributes are updated.
+     *
+     * @param update - The attributes to update.
+     * @returns The updated node, or `null` if the node was not found.
+     * @throws If the node is an `UnknownNode`.
      *
      * Use `"Node.setAttributes"` to check if this method is allowed.
      */
     setAttributes(update: Partial<NodeClassToEditableAttributes[(typeof this)[ClassKey]]>): Promise<(typeof this)[ClassKey] extends "UnknownNode" ? never : typeof this | null>;
     /**
      * Get the bounding box of this node.
+     *
+     * @returns The bounding rectangle, or `null` if unavailable.
      */
     getRect(): Promise<Rect$1 | null>;
     /**
      * Pans and zooms the viewport to center the node.
+     *
+     * @param options - Options like `maxZoom` and `skipIfVisible`.
      */
     zoomIntoView(options?: ZoomIntoViewOptions): Promise<void>;
     /**
@@ -2547,15 +3398,35 @@ declare abstract class NodeMethods implements WithIdTrait, Navigable {
      */
     navigateTo(opts?: Pick<NavigableOptions, "select" | "zoomIntoView">): Promise<void>;
     /**
-     * Get the parent of this node.
+     * Get the parent of this node in the canvas tree.
+     *
+     * @returns The parent node, or `null` if this is a root node.
      */
     getParent(): Promise<AnyNode | null>;
     /**
-     * Get the children of this node.
+     * Get the children of this node in the canvas tree.
+     *
+     * @returns An array of child nodes. Returns an empty array for `UnknownNode`.
      */
     getChildren(): Promise<CanvasNode[]>;
     /**
-     * Get `type` descendants of this node.
+     * Get descendants of this node that match the given type. This can
+     * also be used to query within a selection subtree.
+     *
+     * @param type - The node type to search for.
+     * @returns An array of matching descendant nodes.
+     *
+     * @example
+     * ```ts
+     * // Get all frame nodes in a project.
+     * const frameNodes = await framer.getNodesWithType("FrameNode")
+     *
+     * // Query within a selection subtree.
+     * const selection = await framer.getSelection()
+     * if (selection.length === 1) {
+     *   const frameNodes = await selection[0].getNodesWithType("FrameNode")
+     * }
+     * ```
      */
     getNodesWithType(type: "FrameNode"): Promise<FrameNode[]>;
     getNodesWithType(type: "TextNode"): Promise<TextNode[]>;
@@ -2565,29 +3436,61 @@ declare abstract class NodeMethods implements WithIdTrait, Navigable {
     getNodesWithType(type: "WebPageNode"): Promise<WebPageNode[]>;
     getNodesWithType(type: "ComponentNode"): Promise<ComponentNode[]>;
     /**
-     * Get the descendants of this node that support `attribute`.
+     * Get the descendants of this node that support `attribute`. This
+     * returns nodes that have the given attribute defined in their type,
+     * regardless of whether it has been set.
+     *
+     * @param attribute - The attribute name to filter by.
+     * @returns An array of nodes that support the attribute.
+     *
+     * @example
+     * ```ts
+     * // Get any kind of node that has a background color attribute.
+     * const nodes = await framer.getNodesWithAttribute("backgroundColor")
+     * ```
      */
     getNodesWithAttribute<T extends NodeAttributeKey, Node = NodeWithAttribute<T>>(attribute: T): Promise<Node[]>;
     /**
-     * Get the descendants of this node that have `attribute` set.
+     * Get the descendants of this node that have `attribute` set to a
+     * non-null value.
+     *
+     * @param attribute - The attribute name to filter by.
+     * @returns An array of nodes that have the attribute set.
+     *
+     * @example
+     * ```ts
+     * // Get all nodes with a background image set.
+     * const nodes = await framer.getNodesWithAttributeSet("backgroundImage")
+     * ```
      */
     getNodesWithAttributeSet<T extends NodeAttributeKey, Node = NodeWithAttribute<T>>(attribute: T): Promise<Node[]>;
     /**
-     * Walk this node and its descendants recursively.
+     * Walk this node and its descendants recursively using an async
+     * generator. Yields nodes depth-first.
      */
     walk(this: AnyNode): AsyncGenerator<AnyNode>;
     /**
-     * Get plugin data by key.
+     * Get plugin data by key. Plugin data lets you store arbitrary
+     * string values on individual nodes, scoped to your plugin.
+     *
+     * @param key - The plugin data key.
+     * @returns The stored value, or `null` if no data exists for the key.
      */
     getPluginData(key: string): Promise<string | null>;
     /**
-     * Set plugin data by key.
+     * Set plugin data by key. Plugin data lets you store arbitrary
+     * string values on individual nodes, scoped to your plugin.
+     *
+     * @param key - The plugin data key.
+     * @param value - The value to set, or `null` to remove.
      *
      * Use `"Node.setPluginData"` to check if this method is allowed.
      */
     setPluginData(key: string, value: string | null): Promise<void>;
     /**
-     * Get all plugin data keys.
+     * Get all plugin data keys stored on this node.
+     *
+     * @returns An array of all plugin data keys.
      */
     getPluginDataKeys(): Promise<string[]>;
 }
@@ -2598,6 +3501,11 @@ interface EditableFrameNodeAttributes extends DrawableNode, WithPositionTrait, W
 interface FrameNodeData extends CommonNodeData, Partial<DrawableNode>, WithPositionTrait, Partial<WithComponentVariantTrait>, Partial<WithPinsTrait>, Partial<WithSizeTrait>, Partial<WithSizeConstraintsTrait>, Partial<WithAspectRatioTrait>, Partial<WithZIndexTrait>, Partial<WithOverflowTrait>, Partial<WithBackgroundColorTrait<TraitVariantData>>, Partial<WithBackgroundImageTrait<TraitVariantData>>, Partial<WithBackgroundGradientTrait<TraitVariantData>>, Partial<WithRotationTrait>, Partial<WithLinkTrait>, Partial<WithBorderRadiusTrait>, Partial<WithBorderTrait<TraitVariantData>>, Partial<WithLayoutTrait>, Partial<WithGridItemTrait>, Partial<WithBreakpointTrait>, Partial<WithImageRenderingTrait> {
     [classKey]: "FrameNode";
 }
+/**
+ * A frame layer on the canvas, the most common container node. Frames
+ * can contain children, have layout settings, backgrounds, borders, and
+ * can serve as breakpoint or component variants.
+ */
 declare class FrameNode extends NodeMethods implements EditableFrameNodeAttributes, WithBreakpointTrait {
     readonly [classKey]: FrameNodeData[ClassKey];
     readonly name: string | null;
@@ -2665,6 +3573,22 @@ interface EditableTextNodeAttributes extends DrawableNode, WithPositionTrait, Wi
 interface TextNodeData extends CommonNodeData, Partial<DrawableNode>, WithPositionTrait, Partial<WithPinsTrait>, Partial<WithSizeTrait>, Partial<WithSizeConstraintsTrait>, Partial<WithRotationTrait>, Partial<WithZIndexTrait>, Partial<WithLinkTrait>, Partial<WithOverflowTrait>, Partial<WithTextTruncationTrait>, Partial<WithFontTrait<TraitVariantData>>, Partial<WithInlineTextStyleTrait<TraitVariantData>>, Partial<WithGridItemTrait> {
     [classKey]: "TextNode";
 }
+/**
+ * A text layer on the canvas. Use {@link TextNode.setText | setText} and
+ * {@link TextNode.getText | getText} to work with plain text, or
+ * {@link TextNode.setHTML | setHTML} and {@link TextNode.getHTML | getHTML}
+ * for rich text content.
+ *
+ * @example
+ * ```ts
+ * const selection = await framer.getSelection()
+ * for (const node of selection) {
+ *   if (isTextNode(node)) {
+ *     node.setText("Hello!")
+ *   }
+ * }
+ * ```
+ */
 declare class TextNode extends NodeMethods implements EditableTextNodeAttributes {
     #private;
     readonly [classKey]: TextNodeData[ClassKey];
@@ -2730,6 +3654,10 @@ interface EditableSVGNodeAttributes extends DrawableNode, WithPositionTrait, Wit
 interface SVGNodeData extends CommonNodeData, Partial<DrawableNode>, WithPositionTrait, Partial<WithPinsTrait>, Partial<WithSizeTrait>, WithSVGTrait, Partial<WithRotationTrait> {
     [classKey]: "SVGNode";
 }
+/**
+ * An SVG graphic layer on the canvas. Contains the raw SVG string and
+ * supports positioning, sizing, rotation, and visibility.
+ */
 declare class SVGNode extends NodeMethods implements EditableSVGNodeAttributes {
     readonly [classKey]: SVGNodeData[ClassKey];
     readonly name: string | null;
@@ -2754,6 +3682,7 @@ interface EditableVectorSetItemNodeAttributes extends WithNameTrait, WithVisible
 interface VectorSetItemNodeData extends CommonNodeData, Partial<WithNameTrait>, Partial<WithVisibleTrait>, Partial<WithLockedTrait>, Partial<WithPinsTrait>, Partial<WithSizeTrait> {
     [classKey]: "VectorSetItemNode";
 }
+/** An individual item within a VectorSet node. */
 declare class VectorSetItemNode extends NodeMethods implements EditableVectorSetItemNodeAttributes {
     #private;
     readonly [classKey]: VectorSetItemNodeData[ClassKey];
@@ -2776,6 +3705,21 @@ interface EditableComponentInstanceNodeAttributes extends DrawableNode, WithPosi
 interface ComponentInstanceNodeData extends CommonNodeData, Partial<DrawableNode>, WithPositionTrait, Partial<WithPinsTrait>, Partial<WithSizeTrait>, Partial<WithSizeConstraintsTrait>, Partial<WithAspectRatioTrait>, Partial<WithControlAttributesTrait>, Partial<WithTypedControlsTrait>, WithRequiredComponentInfoTrait, Partial<WithNullableComponentInfoTrait>, Partial<WithRotationTrait> {
     [classKey]: "ComponentInstanceNode";
 }
+/**
+ * An instance of a code or design component on the canvas. Component
+ * instances are identified by their {@link ComponentInstanceNode.componentIdentifier | componentIdentifier}
+ * and can have their control properties updated via
+ * {@link NodeMethods.setAttributes | setAttributes}.
+ *
+ * @example
+ * ```ts
+ * if (isCodeComponentNode(selection)) {
+ *   selection.setAttributes({
+ *     controls: { radius: 10 }
+ *   })
+ * }
+ * ```
+ */
 declare class ComponentInstanceNode extends NodeMethods implements EditableComponentInstanceNodeAttributes, WithComponentInfoTrait {
     #private;
     readonly [classKey]: ComponentInstanceNodeData[ClassKey];
@@ -2816,6 +3760,11 @@ type EditableWebPageNodeAttributes = object;
 interface WebPageNodeData extends CommonNodeData, Partial<WithWebPageInfoTrait> {
     [classKey]: "WebPageNode";
 }
+/**
+ * A web page in the project's site map. Web pages have a
+ * {@link WebPageNode.path | path} and may be associated with a CMS
+ * collection when used as a detail page.
+ */
 declare class WebPageNode extends NodeMethods implements EditableWebPageNodeAttributes, WithWebPageInfoTrait {
     #private;
     readonly [classKey]: WebPageNodeData[ClassKey];
@@ -2854,6 +3803,11 @@ type EditableComponentNodeAttributes = WithNameTrait;
 interface ComponentNodeData extends CommonNodeData, Partial<WithNameTrait>, WithRequiredComponentInfoTrait, Partial<WithNullableComponentInfoTrait> {
     [classKey]: "ComponentNode";
 }
+/**
+ * A reusable design component definition. Component nodes contain
+ * variants, gesture states, and variables. They can be inserted as
+ * instances via their module URL.
+ */
 declare class ComponentNode extends NodeMethods implements EditableComponentNodeAttributes, WithComponentInfoTrait {
     #private;
     readonly [classKey]: ComponentNodeData[ClassKey];
@@ -2920,6 +3874,7 @@ type EditableVectorSetNodeAttributes = WithNameTrait;
 interface VectorSetNodeData extends CommonNodeData, Partial<WithNameTrait> {
     [classKey]: "VectorSetNode";
 }
+/** A container node for a set of vector icons. */
 declare class VectorSetNode extends NodeMethods implements EditableVectorSetNodeAttributes {
     readonly [classKey]: VectorSetNodeData[ClassKey];
     readonly name: string | null;
@@ -2929,6 +3884,7 @@ type EditableDesignPageNodeAttributes = WithNameTrait;
 interface DesignPageNodeData extends CommonNodeData, Partial<WithNameTrait> {
     [classKey]: "DesignPageNode";
 }
+/** A design page (non-web canvas) in the project. */
 declare class DesignPageNode extends NodeMethods implements EditableDesignPageNodeAttributes {
     readonly [classKey]: DesignPageNodeData[ClassKey];
     readonly name: string | null;
@@ -2937,6 +3893,11 @@ declare class DesignPageNode extends NodeMethods implements EditableDesignPageNo
 interface UnknownNodeData extends CommonNodeData {
     [classKey]: "UnknownNode";
 }
+/**
+ * A node whose type is not recognized by the current plugin API version.
+ * Unknown nodes cannot be cloned, have their attributes set, or return
+ * children.
+ */
 declare class UnknownNode extends NodeMethods {
     readonly [classKey]: UnknownNodeData[ClassKey];
     constructor(rawData: UnknownNodeData, engine: PluginEngine);
@@ -2989,27 +3950,37 @@ interface ApiVersion1User {
     /** Hashed user id */
     id: string;
 }
+/** Information about a Framer user. */
 interface User extends ApiVersion1User {
     /** Hashed user id served by API version 1, use for migration only */
     apiVersion1Id: string;
+    /** URL to the user's avatar image, if available. */
     avatarUrl?: string | undefined;
-    /** For when there is no avatar. */
+    /** Initials of the user's name, for use when no avatar is available. */
     initials: string;
 }
 
 interface CodeExportCommon {
+    /** The export name. */
     name: string;
+    /** Whether this is the default export of the file. */
     isDefaultExport: boolean;
 }
+/** A component export from a code file. */
 interface CodeFileComponentExport extends CodeExportCommon {
+    /** URL that can be used with `addComponentInstance` to insert this export onto the canvas. */
     insertURL: string;
+    /** Discriminator indicating this is a component export. */
     type: "component";
 }
+/** An override export from a code file. */
 interface CodeFileOverrideExport extends CodeExportCommon {
+    /** Discriminator indicating this is an override export. */
     type: "override";
 }
 declare function isCodeFileComponentExport(exportItem: CodeFileExport): exportItem is CodeFileComponentExport;
 declare function isCodeFileOverrideExport(exportItem: CodeFileExport): exportItem is CodeFileOverrideExport;
+/** Union of possible code file export types: component or override. */
 type CodeFileExport = CodeFileComponentExport | CodeFileOverrideExport;
 /** @alpha */
 type ShowProgressOnInstancesAttributes = Pick<ComponentInstancePlaceholderAttributes, "title" | "codePreview">;
@@ -3026,44 +3997,103 @@ interface CodeFileVersionData extends Pick<CodeFileData, "id" | "name"> {
     createdAt: string;
     createdBy: User;
 }
+/**
+ * A saved version (snapshot) of a code file.
+ */
 declare class CodeFileVersion {
     #private;
+    /** The unique identifier of the version. */
     get id(): string;
+    /** The file name at this version. */
     get name(): string;
+    /** The ISO 8601 timestamp of when the version was created. */
     get createdAt(): string;
+    /** The user who created this version. */
     get createdBy(): Readonly<User>;
     constructor(data: CodeFileVersionData, engine: PluginEngine);
+    /**
+     * Retrieve the source code content of this version.
+     *
+     * @example
+     * ```ts
+     * const previousContent = await version.getContent()
+     * ```
+     *
+     * @returns The file content as a string.
+     */
     getContent(): Promise<string>;
 }
+/**
+ * Represents a code file in the Framer project, such as a code component
+ * or code override.
+ */
 declare class CodeFile implements Navigable {
     #private;
+    /** The unique identifier of the code file. */
     get id(): string;
+    /** The name of the code file (e.g., `"MyComponent.tsx"`). */
     get name(): string;
+    /** The file system path of the code file within the project. */
     get path(): string;
+    /** The current source code content of the file. */
     get content(): string;
+    /** The array of exports available in this code file (components and overrides). */
     get exports(): readonly CodeFileExport[];
     get versionId(): string;
     constructor(data: CodeFileData, engine: PluginEngine);
     /**
-     * Set the content of this code file.
+     * Set the content of this code file. Creates a new version.
+     *
+     * @example
+     * ```ts
+     * const updatedFile = await codeFile.setFileContent(
+     * 	`export default function MyComponent() {
+     * 	  return <div>Hello World</div>
+     * 	}`
+     * )
+     * ```
      *
      * Use `"CodeFile.setFileContent"` to check if this method is allowed.
+     *
+     * @param code - The new source code content.
+     * @returns The updated CodeFile instance.
      */
     setFileContent(code: string): Promise<CodeFile>;
     /**
      * Rename this code file.
      *
+     * @example
+     * ```ts
+     * const renamedFile = await codeFile.rename("NewComponentName.tsx")
+     * ```
+     *
      * Use `"CodeFile.rename"` to check if this method is allowed.
+     *
+     * @param newName - The new name for the file.
+     * @returns The updated CodeFile instance.
      */
     rename(newName: string): Promise<CodeFile>;
     /**
-     * Remove this code file.
+     * Remove this code file from the project.
+     *
+     * @example
+     * ```ts
+     * await codeFile.remove()
+     * ```
      *
      * Use `"CodeFile.remove"` to check if this method is allowed.
      */
     remove(): Promise<void>;
     /**
-     * Get all versions of this code file.
+     * Get all versions (history) of this code file.
+     *
+     * @example
+     * ```ts
+     * const versions = await codeFile.getVersions()
+     * console.log(`File has ${versions.length} versions`)
+     * ```
+     *
+     * @returns An array of CodeFileVersion instances.
      */
     getVersions(): Promise<readonly CodeFileVersion[]>;
     /** @alpha */
@@ -3074,18 +4104,41 @@ declare class CodeFile implements Navigable {
      * @deprecated The implementation of this method was removed. The method will always return an empty array. The method will be removed in the near future.
      */
     lint(_rules: LintConfig): Promise<LintDiagnostic[]>;
+    /**
+     * Run TypeScript type checking on this code file.
+     *
+     * @example
+     * ```ts
+     * const typeErrors = await codeFile.typecheck({
+     * 	strict: true
+     * })
+     * ```
+     *
+     * @param compilerOptions - Optional TypeScript compiler options. See the TypeScript
+     * CompilerOptions reference for all available options.
+     * @returns An array of `TypecheckDiagnostic` results.
+     */
     typecheck(compilerOptions?: ts.server.protocol.CompilerOptions): Promise<TypecheckDiagnostic[]>;
     /**
-     * Navigate to this code file. May switch modes to reveal the relevant view.
+     * Navigate to this code file in the Code Editor. May switch modes to
+     * reveal the relevant view.
+     *
+     * @example
+     * ```ts
+     * await codeFile.navigateTo()
+     * ```
      */
     navigateTo(): Promise<void>;
 }
 
+/** Where in the HTML document the custom code is injected. */
 type CustomCodeLocation = "headStart" | "headEnd" | "bodyStart" | "bodyEnd";
+/** Options for setting custom HTML code on the site. A plugin can only set custom code once per location. */
 interface SetCustomCodeOptions {
     html: string | null;
     location: CustomCodeLocation;
 }
+/** Custom HTML code settings for all injection locations, including disabled state. */
 type CustomCode = Record<CustomCodeLocation, {
     disabled: boolean;
     html: string | null;
@@ -3118,6 +4171,16 @@ interface DetachedComponentLayersDragData extends WithOptionalName$1, WithOption
     layout?: boolean;
     attributes?: Partial<EditableComponentInstanceNodeAttributes>;
 }
+/**
+ * Data describing what is being dragged onto the canvas. Different types
+ * of drag data result in different canvas insertions.
+ *
+ * Supported drag types:
+ * - `"image"` - An image with an optional preview image, alt text, and resolution.
+ * - `"svg"` - An SVG string with an optional preview image. Use `invertInDarkMode` to invert the drag preview in dark mode.
+ * - `"componentInstance"` - A component instance identified by its module URL.
+ * - `"detachedComponentLayers"` - Detached layers from a component designed in Framer. Use `layout: true` to insert as a layout block.
+ */
 type DragData = SvgDragData | ImageDragData | ComponentInstanceDragData | DetachedComponentLayersDragData;
 interface Point {
     x: number;
@@ -3146,16 +4209,37 @@ type DragEndInfo = DragSessionId & {
 interface DragCompleteSuccess {
     /** Whether the drag was successful or not. */
     status: "success";
-    /** The inserted node id. */
+    /** The ID of the node that was inserted. Only available when the drag succeeded. */
     nodeId: NodeId;
 }
 interface DragCompleteError {
     /** Whether the drag was successful or not. */
     status: "error";
-    /** Reason for the error, if available. */
+    /** The reason why the drag failed. Only available when the drag failed. */
     reason?: string;
 }
+/**
+ * The result of a drag operation, indicating success or failure.
+ *
+ * @example
+ * ```ts
+ * onDragComplete={(result) => {
+ *   if (result.status === "error") {
+ *     framer.notify(result.reason ?? "Unknown error");
+ *     return;
+ *   }
+ *
+ *   framer.notify("Image uploaded successfully");
+ * }}
+ * ```
+ */
 type DragCompleteResult = DragCompleteSuccess | DragCompleteError;
+/**
+ * Callback invoked when a drag operation completes. Receives a
+ * {@link DragCompleteResult} indicating whether the drag was successful
+ * or not, including the inserted node ID on success or an error reason
+ * on failure.
+ */
 type DragCompleteCallback = (result: DragCompleteResult) => void;
 
 declare const publish: unique symbol;
@@ -3198,14 +4282,29 @@ interface VectorSetItemVariable {
     id: string;
     name: string;
 }
+/**
+ * A set of vector icons available in the project.
+ *
+ * @alpha
+ */
 declare class VectorSet {
     #private;
     id: string;
     name: string;
     owner: Ownership;
     constructor(data: VectorSetData, engine: PluginEngine);
+    /**
+     * Get all vector items in this set.
+     *
+     * @returns An array of VectorSetItem instances.
+     */
     getItems(): Promise<VectorSetItem[]>;
 }
+/**
+ * An individual vector icon within a VectorSet.
+ *
+ * @alpha
+ */
 declare class VectorSetItem {
     #private;
     id: string;
@@ -3213,6 +4312,11 @@ declare class VectorSetItem {
     insertUrl: string;
     iconUrl: string;
     constructor(data: VectorSetItemData, engine: PluginEngine);
+    /**
+     * Get the customizable variables (e.g. color, stroke width) for this vector item.
+     *
+     * @returns An array of variable definitions.
+     */
     getVariables(): Promise<VectorSetItemVariable[]>;
 }
 
@@ -3527,25 +4631,65 @@ interface UpdateRedirect extends Partial<RedirectAttributes>, Partial<WithToFiel
     id: string;
 }
 type RedirectInput = Prettify<CreateRedirect | UpdateRedirect>;
+/**
+ * A URL redirect configured in the project. Redirects are applied when
+ * the site is published.
+ */
 declare class Redirect {
     #private;
-    /** The id of the redirect. */
+    /** A unique identifier for the redirect. */
     get id(): string;
-    /** The source path to redirect from. */
+    /** The source path of the redirect. */
     get from(): string;
-    /** The destination path to redirect to. */
+    /**
+     * The destination path of the redirect.
+     *
+     * When a redirect points to an existing page, the `to` value will
+     * always point to that page. This property will be set to `null` if
+     * the page it points to was removed.
+     */
     get to(): string | null;
-    /** Whether to expand the redirect to all locales. */
+    /**
+     * Whether the redirect is expanded to all locales. When enabled, the
+     * redirect will apply not only in the base locale, but also in all
+     * other locales in the project.
+     *
+     * For example, for a project with a Spanish locale, the following
+     * would redirect both `/business` to `/enterprise`, and
+     * `/es/business` to `/es/enterprise`.
+     *
+     * @example
+     * ```ts
+     * await framer.addRedirects([
+     *   { from: "/business", to: "/enterprise", expandToAllLocales: true }
+     * ])
+     * ```
+     */
     get expandToAllLocales(): boolean;
     constructor(data: RedirectData, engine: PluginEngine);
     /**
      * Remove the redirect.
+     *
+     * @returns A promise that resolves when the redirect is removed.
+     *
+     * @example
+     * ```ts
+     * await redirect.remove()
+     * ```
      */
     remove(): Promise<void>;
     /**
-     * Update the redirect attributes.
+     * Set the attributes of a redirect.
      *
+     * @param attributes - The updated attributes and their new values.
      * @returns The updated redirect, or `null` if the redirect was not found.
+     * @throws When the current user does not have permission to edit Site Settings, a `FramerPluginError` is thrown.
+     * @throws When the current project is not on a plan that includes redirects, a `FramerPluginError` is thrown.
+     *
+     * @example
+     * ```ts
+     * await redirect.setAttributes({ from: "/new-url" })
+     * ```
      */
     setAttributes(attributes: Partial<CreateRedirect>): Promise<Redirect | null>;
 }
@@ -3679,9 +4823,11 @@ type InitialState = {
     intent: "collection/add";
 };
 
+/** A visual separator between menu items. */
 interface SeparatorMenuItem {
     type: "separator";
 }
+/** An actionable menu item with a label and optional submenu. */
 interface NormalMenuItem {
     type?: never;
     label: string;
@@ -3692,6 +4838,7 @@ interface NormalMenuItem {
     submenu?: MenuItem[];
     onAction?: () => void;
 }
+/** A menu item, either a normal action item or a separator. */
 type MenuItem = NormalMenuItem | SeparatorMenuItem;
 type NormalMenuItemSerializable = Omit<NormalMenuItem, "onAction" | "submenu"> & {
     actionId?: number;
@@ -3701,6 +4848,7 @@ type MenuItemSerializable = NormalMenuItemSerializable | SeparatorMenuItem;
 type MenuPlacementVertical = "top" | "bottom";
 type MenuPlacementHorizontal = "left" | "right";
 type MenuPlacement = MenuPlacementVertical | MenuPlacementHorizontal | `${MenuPlacementVertical}-${MenuPlacementHorizontal}`;
+/** Configuration for positioning and sizing a context menu. */
 interface ContextMenuConfig {
     /**
      * Coordinates of the anchor point.
@@ -3725,6 +4873,7 @@ interface NotifyOptionsBase {
     variant?: NotificationVariant;
     durationMs?: number;
 }
+/** Options for customizing a notification. */
 interface NotifyOptions extends NotifyOptionsBase {
     /** A button to be displayed on the notification */
     button?: {
@@ -3740,10 +4889,12 @@ interface NotifyOptionsData extends NotifyOptionsBase {
     buttonText?: string;
     notificationId: string;
 }
+/** A handle to an active notification, allowing it to be closed programmatically. */
 interface Notification {
     close: () => Promise<void>;
 }
 type NotificationCloseReason = "timeoutReachedOrDismissed" | "actionButtonClicked";
+/** Function signature for displaying a notification message. */
 type Notify = (message: string, options?: NotifyOptions) => Notification;
 
 /**
@@ -3751,7 +4902,8 @@ type Notify = (message: string, options?: NotifyOptions) => Notification;
  */
 interface NavigableOptions {
     /**
-     * Selects the item after navigation (e.g., opens the editor for a CollectionItem or selects it on the canvas).
+     * Selects the item after navigation. Selects the item on the canvas or opens
+     * the editor sidebar on a collection item.
      * @default true
      */
     select?: boolean | undefined;
@@ -3800,7 +4952,19 @@ interface AiServiceInfo {
 declare class FramerPluginAPI {
     #private;
     constructor(engine: PluginEngine);
-    /** Get the current mode. A plugin can launch in a special mode where only a subset of the API is allowed. */
+    /**
+     * Get the current mode. A plugin can launch in a special mode where only a
+     * subset of the API is allowed. The mode is set when the plugin launches
+     * and never changes while the plugin is active.
+     *
+     * @example
+     * ```ts
+     * if (framer.mode === "image" || framer.mode === "editImage") {
+     *   // Do image mode specific logic
+     *   return
+     * }
+     * ```
+     */
     get mode(): Mode;
     /**
      * Find out if user's permissions allow them to execute all of `methods`:
@@ -3810,8 +4974,18 @@ declare class FramerPluginAPI {
      * if (framer.isAllowedTo("Collection.setItemOrder")) await collection.setItemOrder(...)
      * ```
      *
+     * For class instance methods (e.g., `CollectionItem.remove`), prefix with
+     * the class name. Multiple methods can be checked at once; the result is
+     * `true` only if all are allowed.
+     *
      * Note that when the result of the permission check affects the UI, it's better to use the
      * `subscribeToIsAllowedTo` method, or `useIsAllowedTo` if using React.
+     *
+     * A `FramerPluginError` is thrown if a protected method is called without
+     * sufficient permissions.
+     *
+     * @param methods - The methods to check, at least one.
+     * @returns `true` if all of `methods` can be executed, `false` otherwise.
      */
     isAllowedTo(...methods: [ProtectedMethod, ...ProtectedMethod[]]): boolean;
     /**
@@ -3825,21 +4999,80 @@ declare class FramerPluginAPI {
      * ```
      *
      * Refer to `useIsAllowedTo` for a React hook version of this.
+     *
+     * @param methods - The methods to check, at least one.
+     * @param callback - Called every time the isAllowed result changes, where `isAllowed` is `true` if all of `methods` can be executed.
+     * @returns A function to call to unsubscribe.
      */
     subscribeToIsAllowedTo(...args: [...methods: [ProtectedMethod, ...ProtectedMethod[]], callback: (isAllowed: boolean) => void]): Unsubscribe$1;
-    /** Show the plugin UI. */
+    /**
+     * Show the plugin window.
+     *
+     * @param options - The options for how to show the UI.
+     *
+     * @example
+     * ```ts
+     * framer.showUI({
+     *   position: "center",
+     *   height: 300,
+     *   width: 220
+     * })
+     * ```
+     */
     showUI(options?: UIOptions): Promise<void>;
-    /** Hide the plugin window, without stopping the plugin. */
+    /**
+     * Hide the plugin window, without stopping the plugin.
+     *
+     * The plugin continues to run in the background after hiding. Use
+     * `setBackgroundMessage` to communicate status while hidden.
+     *
+     * @example
+     * ```ts
+     * framer.hideUI()
+     * ```
+     */
     hideUI(): Promise<void>;
-    /** Update the background status text shown while the plugin UI is hidden. */
+    /**
+     * Update the background status text shown while the plugin UI is hidden.
+     * This allows plugins running in the background to communicate their current
+     * status to users.
+     *
+     * Set to `null` to clear the message.
+     *
+     * @param status - The message to display, or `null` to clear.
+     *
+     * @example
+     * ```ts
+     * await framer.hideUI()
+     * await framer.setBackgroundMessage("Syncing data...")
+     *
+     * // Clear the status message
+     * await framer.setBackgroundMessage(null)
+     * ```
+     */
     setBackgroundMessage(status: string | null): Promise<void>;
     /**
-     * Stop the plugin. Throws `FramerPluginClosedError`, which should be ignored.
+     * Close and terminate the plugin. Throws `FramerPluginClosedError`, which should be ignored.
+     *
      * @param message - Optional message to show in the notification (ignored if options.silent is true)
      * @param options - Options to control the close behaviour
+     *
+     * @example
+     * ```ts
+     * await framer.closePlugin("Synchronization successful", {
+     *     variant: "success",
+     * })
+     * ```
      */
     closePlugin(message?: string, options?: ClosePluginOptions): never;
-    /** Get the current user info like name and id. */
+    /**
+     * Get information about the user that's interacting with the plugin.
+     *
+     * @example
+     * ```ts
+     * const user = await framer.getCurrentUser();
+     * ```
+     */
     getCurrentUser(): Promise<User>;
     /** Get the project info like name and id. */
     getProjectInfo(): Promise<ProjectInfo>;
@@ -3853,9 +5086,33 @@ declare class FramerPluginAPI {
     getCanvasRoot(): Promise<CanvasRootNode>;
     /** Subscribe to canvas root changes */
     subscribeToCanvasRoot(rootUpdate: (root: CanvasRootNode) => void): Unsubscribe$1;
-    /** Get the current publish info. */
+    /**
+     * Get information about the published website, such as the time of the most
+     * recent deploy, or the URL of the current page. Provides information about
+     * both `staging` and `production` environments (either may be `null` if the
+     * site has never been published).
+     *
+     * @returns The current publish info for both staging and production.
+     */
     getPublishInfo(): Promise<PublishInfo>;
-    /** Subscribe to publish info changes. */
+    /**
+     * Subscribe to publish info changes. The callback is called whenever
+     * publish info is updated (e.g., after a new deployment).
+     *
+     * @param publishInfoUpdate - Called when publish info changes.
+     * @returns A function to unsubscribe from updates.
+     *
+     * @example
+     * ```ts
+     * function usePublishInfo() {
+     *   const [publishInfo, setPublishInfo] = useState<PublishInfo>()
+     *   useEffect(() => {
+     *     return framer.subscribeToPublishInfo(setPublishInfo)
+     *   }, [])
+     *   return publishInfo
+     * }
+     * ```
+     */
     subscribeToPublishInfo(publishInfoUpdate: (info: PublishInfo) => void): Unsubscribe$1;
     /** Create a new node on the canvas. */
     createFrameNode(attributes: Partial<EditableFrameNodeAttributes>, parentId?: string): Promise<FrameNode | null>;
@@ -3873,7 +5130,21 @@ declare class FramerPluginAPI {
     getChildren(nodeId: NodeId): Promise<CanvasNode[]>;
     /** Get the rect of a node */
     getRect(nodeId: NodeId): Promise<Rect$1 | null>;
-    /** Pans and zooms the viewport to center a single or group of nodes. */
+    /**
+     * Pans and zooms the viewport to center a single or group of nodes.
+     *
+     * @param nodeIds - Node ID or array of node IDs to zoom into.
+     * @param options - Options like `maxZoom` and `skipIfVisible`.
+     *
+     * @example
+     * ```ts
+     * // Scroll and zoom the viewport to show a specific node.
+     * await framer.zoomIntoView("node-id")
+     *
+     * // Scroll and zoom to fit multiple nodes into the viewport.
+     * await framer.zoomIntoView(["node-id-1", "node-id-2"])
+     * ```
+     */
     zoomIntoView(nodeIds: NodeId | Iterable<NodeId>, options?: ZoomIntoViewOptions): Promise<void>;
     /** Set the attributes of a node. */
     setAttributes(nodeId: NodeId, attributes: Partial<AnyEditableAttributes>): Promise<AnyNode | null>;
@@ -3891,13 +5162,23 @@ declare class FramerPluginAPI {
     getNodesWithAttribute<T extends NodeAttributeKey, Node = NodeWithAttribute<T>>(attribute: T): Promise<Node[]>;
     /** Get all nodes with a certain attribute which value is set. */
     getNodesWithAttributeSet<T extends NodeAttributeKey, Node = NodeWithAttribute<T>>(attribute: T): Promise<Node[]>;
-    /** Get the image of the current selection or null if there is no image. */
+    /**
+     * Get the image of the current selection or `null` if there is no image.
+     *
+     * In `editImage` mode, this returns the image the user already has set,
+     * which your plugin can then modify.
+     */
     getImage(): Promise<ImageAsset | null>;
     /** Subscribe to single image selection changes. */
     subscribeToImage(imageUpdate: (image: ImageAsset | null) => void): Unsubscribe$1;
     /** Upload an image, and insert on the canvas. */
     addImage(image: NamedImageAssetInput | File): Promise<void>;
-    /** Upload an image, and set on the selected node. */
+    /**
+     * Upload an image and set it on the selected node.
+     *
+     * In `image` or `editImage` mode, this is the primary method to send the
+     * selected or edited image back to Framer.
+     */
     setImage(image: NamedImageAssetInput | File): Promise<void>;
     /** Upload an image without assigning it to a property. */
     uploadImage(image: NamedImageAssetInput | File): Promise<ImageAsset>;
@@ -3911,7 +5192,14 @@ declare class FramerPluginAPI {
     uploadFiles(files: readonly NamedFileAssetInput[]): Promise<FileAsset[]>;
     /** Add an SVG, replacing the selected SVG, or insert on the canvas. */
     addSVG(svg: SVGData): Promise<void>;
-    /** Add a component instance by module URL. */
+    /**
+     * Add a component instance by module URL.
+     *
+     * @param url - The component module URL. Can be copied from the components panel.
+     * @param attributes - Optional component attributes.
+     *
+     * @returns The newly created component instance node.
+     */
     addComponentInstance({ url, attributes, parentId, }: AddComponentInstanceOptions): Promise<ComponentInstanceNode>;
     /** Adds the layers of a component by module URL. */
     addDetachedComponentLayers({ url, layout, attributes }: AddDetachedComponentLayersOptions): Promise<FrameNode>;
@@ -3926,13 +5214,50 @@ declare class FramerPluginAPI {
     /** Add a new text node to the canvas. */
     addText(text: string, options?: AddTextOptions): Promise<void>;
     /**
-     * Set Custom HTML to be loaded in the document. A plugin can only set custom HTML once per
-     * location.
+     * Install a custom code snippet in the user's website via `<script>` tags.
+     * A plugin can only set custom HTML once per location. Custom code should be
+     * valid HTML. Setting `html` to `null` clears the installed code snippet.
+     *
+     * @param options - The custom code options including `html` and `location`.
+     *
+     * @example
+     * ```ts
+     * framer.setCustomCode({
+     *   html: '<script src="https://example.com/script.js"></script>',
+     *   location: "bodyEnd"
+     * })
+     * ```
      */
     setCustomCode(options: SetCustomCodeOptions): Promise<void>;
-    /** Get custom HTML settings set by the plugin. */
+    /**
+     * Get custom code settings set by the plugin. Your plugin can detect if
+     * custom code was set and whether the user has disabled it.
+     *
+     * @example
+     * ```ts
+     * const customCode = await framer.getCustomCode()
+     * if (customCode.bodyStart.disabled) {
+     *   // Custom code was disabled by the user in settings
+     * }
+     * ```
+     */
     getCustomCode(): Promise<CustomCode>;
-    /** Subscribe to custom HTML changes set by the plugin. */
+    /**
+     * Subscribe to custom code changes. Called when custom code is registered
+     * or when changes to the settings are made.
+     *
+     * @param callback - Called when custom code settings change.
+     * @returns A function to unsubscribe from updates.
+     *
+     * @example
+     * ```ts
+     * function useCustomCode() {
+     *   const [customCode, setCustomCode] = useState<CustomCode | null>(null)
+     *   useEffect(() => framer.subscribeToCustomCode(setCustomCode), [])
+     *   return customCode
+     * }
+     * ```
+     */
     subscribeToCustomCode(callback: (customHTML: CustomCode) => void): Unsubscribe$1;
     /** Subscribe to the current text selection. */
     subscribeToText(callback: (text: string | null) => void): Unsubscribe$1;
@@ -3942,23 +5267,75 @@ declare class FramerPluginAPI {
      * all of the added listeners.
      */
     makeDraggable(element: HTMLElement, getDragData: () => DragData, onDragComplete?: DragCompleteCallback): Cleanup;
-    /** Get the managed collection that is currently active and selected in the UI. */
+    /**
+     * Retrieve the currently active managed Collection from the UI.
+     *
+     * - Only applies when the Plugin is operating in a mode that supports managed Collections.
+     *
+     * @example
+     * ```ts
+     * const collection = await framer.getActiveManagedCollection();
+     * ```
+     */
     getActiveManagedCollection(): Promise<ManagedCollection>;
     /** @deprecated Use `getActiveManagedCollection` */
     getManagedCollection(): Promise<ManagedCollection>;
-    /** Get all collections managed by your plugin. */
+    /**
+     * Retrieve Collections that are managed by the current Plugin.
+     *
+     * - Only Collections created or controlled by your Plugin appear in this list.
+     * - These Collections can be modified without the restrictions placed on user-created Collections.
+     *
+     * @example
+     * ```ts
+     * const managedCollections = await framer.getManagedCollections();
+     * ```
+     */
     getManagedCollections(): Promise<ManagedCollection[]>;
     /** Get a collection by its id. */
     getCollection(id: NodeId): Promise<Collection | null>;
-    /** Get the collection that is currently selected in the UI. */
+    /**
+     * Retrieve the Collection currently active (selected) in the Framer UI.
+     *
+     * - If the active Collection is managed by a Plugin, you may want to use `getActiveManagedCollection()` instead.
+     * - The selection may change if the user interacts with the UI.
+     *
+     * @returns The active Collection or `null` if none is selected.
+     *
+     * @example
+     * ```ts
+     * const collection = await framer.getActiveCollection();
+     * ```
+     */
     getActiveCollection(): Promise<Collection | null>;
     /**
-     * Get all collections in the project. This includes collections created by the user or a
-     * plugin.
+     * Get all Collections in the project, both managed and unmanaged.
+     *
+     * @example
+     * ```ts
+     * const collections = await framer.getCollections()
+     * ```
      */
     getCollections(): Promise<Collection[]>;
     /**
      * Display a notification message. The message will be truncated if longer than 120 characters.
+     *
+     * @param message - The message to display. Truncated if longer than 120 characters.
+     * @param options - Options like `variant` (`"info"`, `"success"`, `"warning"`, `"error"`), `durationMs`, `button`, and `onDisappear`.
+     *
+     * @returns A Notification handle that can be used to close the notification programmatically.
+     *
+     * @example
+     * ```ts
+     * const notification = framer.notify("An action was completed", {
+     *     button: { text: "Undo", onClick: handleUndo },
+     *     durationMs: 3000,
+     *     variant: "info",
+     * })
+     *
+     * // Close the notification programmatically
+     * notification.close()
+     * ```
      */
     notify: Notify;
     /** Get plugin data by key. */
@@ -3983,43 +5360,226 @@ declare class FramerPluginAPI {
     createTextStyle(attributes: TextStyleAttributes): Promise<TextStyle>;
     /** Fired when a text style is added, edited or removed. */
     subscribeToTextStyles(callback: (styles: TextStyle[]) => void): Unsubscribe$1;
-    /** Get a specific font via it's family name, and optionally weight and style. */
+    /**
+     * Get a specific font from a family by name. This is not case sensitive.
+     * By default, returns a font with normal weight and style. Returns `null`
+     * if the font does not exist or lacks the requested weight/style combination.
+     *
+     * Note: Custom fonts are not available to plugins.
+     *
+     * @param family - The font family name (e.g., `"Noto Sans"`).
+     * @param attributes - Optional weight and style attributes.
+     * @returns The matched font or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * // Get Noto Sans with default weight (400) and normal style
+     * const font = await framer.getFont("Noto Sans")
+     *
+     * // Get Noto Sans with a specific weight and style
+     * const font = await framer.getFont("Noto Sans", {
+     *   weight: 800,
+     *   style: "italic"
+     * })
+     * ```
+     */
     getFont(family: string, attributes?: FontAttributes): Promise<Font | null>;
-    /** Get all available fonts. */
+    /**
+     * Get all available fonts. Unlike the Font Picker which groups fonts by
+     * typeface, this lists individual fonts for each weight and style (each
+     * representing a separate font file).
+     *
+     * Note: Custom fonts are not available to plugins.
+     *
+     * @returns An array of all available fonts.
+     *
+     * @example
+     * ```ts
+     * const fonts = await framer.getFonts()
+     * ```
+     */
     getFonts(): Promise<Font[]>;
-    /** Get all locales in the current Project */
+    /**
+     * Get all Locales in the project.
+     *
+     * Does not include the default Locale. See `getDefaultLocale`.
+     *
+     * @example
+     * ```ts
+     * const locales = await framer.getLocales()
+     * ```
+     */
     getLocales(): Promise<readonly Locale[]>;
-    /** Get the default locale of the current Project */
+    /**
+     * Get the default locale of the project.
+     *
+     * @example
+     * ```ts
+     * const defaultLocale = await framer.getDefaultLocale()
+     * ```
+     */
     getDefaultLocale(): Promise<Locale>;
     /**
      * Get the currently active locale.
      *
      * - In "localization" mode, the active locale is the locale selected in the Localizations panel.
      * - In "canvas" mode, the active locale is the locale selected in the toolbar.
-     * - Otherwise, the active locale is null.
+     * - Otherwise, the active locale is `null`.
+     *
+     * @example
+     * ```ts
+     * const activeLocale = await framer.getActiveLocale()
+     * ```
      */
     getActiveLocale(): Promise<Locale | null>;
-    /** Get all localization groups in the current Project */
+    /**
+     * Get all Localization Groups in the project.
+     *
+     * @example
+     * ```ts
+     * const groups = await framer.getLocalizationGroups()
+     *
+     * for (const group of groups) {
+     *     console.log(`Group: ${group.name}`)
+     *
+     *     for (const source of group.sources) {
+     *         console.log(`Source: ${source.value}`)
+     *     }
+     * }
+     * ```
+     */
     getLocalizationGroups(): Promise<readonly LocalizationGroup[]>;
-    /** Update localization data */
+    /**
+     * Update localization data.
+     *
+     * @param update - An object representing the localization update.
+     *
+     * @example
+     * ```ts
+     * await framer.setLocalizationData({
+     *     valuesBySource: {
+     *         [titleSourceId]: {
+     *             [dutchLocaleId]: { action: "set", value: "Hallo Wereld" }
+     *         }
+     *     },
+     *     statusByLocaleByGroup: {
+     *         [blogPostGroupId]: {
+     *             [dutchLocaleId]: "ready",
+     *             [frenchLocaleId]: "excluded"
+     *         }
+     *     }
+     * })
+     * ```
+     */
     setLocalizationData(update: LocalizationData): Promise<SetLocalizationDataResult>;
-    /** Get all redirects in the project */
+    /**
+     * Get all Redirects in the project.
+     *
+     * @returns All of the Redirects in the project.
+     *
+     * @example
+     * ```ts
+     * const redirects = await framer.getRedirects()
+     * ```
+     */
     getRedirects(): Promise<readonly Redirect[]>;
-    /** Add new redirects or update existing ones if their IDs match */
+    /** Subscribe to redirect changes. */
     subscribeToRedirects(callback: (redirects: Redirect[]) => void): Unsubscribe$1;
-    /** Add new redirects or update existing ones if their IDs match */
+    /**
+     * Add new redirects or update existing ones if their IDs match
+     *
+     * `from` paths can contain wildcards (`*`) which match any string, and
+     * captured groups can be referenced in the `to` path using `:1`, `:2`,
+     * etc.
+     *
+     * Throws a `FramerPluginError` when the user lacks Site Settings permissions,
+     * when the project plan does not include Redirects, or when the maximum
+     * redirect count (2500) is reached.
+     *
+     * @param redirects - An array of redirect objects to add.
+     * @returns The added Redirects.
+     *
+     * @example
+     * ```ts
+     * await framer.addRedirects([
+     *   { from: "/business", to: "/enterprise", expandToAllLocales: true },
+     *   { from: "/posts/*", to: "/blog/:1", expandToAllLocales: false },
+     * ])
+     * ```
+     */
     addRedirects(redirects: RedirectInput[]): Promise<Redirect[]>;
-    /** Remove a redirect from the project */
+    /**
+     * Remove Redirects from the project. Unknown Redirect IDs are ignored.
+     *
+     * Throws a `FramerPluginError` when the user lacks Site Settings permissions
+     * or when the project plan does not include Redirects.
+     *
+     * @param redirectIds - An array of Redirect IDs to remove.
+     *
+     * @example
+     * ```ts
+     * await framer.removeRedirects([aboutPageRedirect.id, blogPageRedirect.id])
+     * ```
+     */
     removeRedirects(redirectIds: string[]): Promise<void>;
-    /** Set the order of redirects */
+    /**
+     * Set the order of Redirects in the list. Unknown Redirect IDs are ignored.
+     *
+     * Throws a `FramerPluginError` when the user lacks Site Settings permissions
+     * or when the project plan does not include Redirects.
+     *
+     * @param redirectIds - An array of Redirect IDs representing the desired order.
+     *
+     * @example
+     * ```ts
+     * await framer.setRedirectOrder([aboutPageRedirect.id, blogPageRedirect.id])
+     * ```
+     */
     setRedirectOrder(redirectIds: string[]): Promise<void>;
-    /** Create a new code file */
+    /**
+     * Create a new code file in the project.
+     *
+     * @param name - The name of the code file (including extension).
+     * @param code - The initial content of the code file.
+     * @param options - Optional settings. `editViaPlugin`: when `true`, the "Edit Code" UI action will open the plugin which created the code file.
+     * @returns The newly created code file instance.
+     *
+     * @example
+     * ```ts
+     * const newFile = await framer.createCodeFile(
+     *   "MyComponent",
+     *   `export default function MyComponent() {
+     *     return <div>Hello World</div>
+     *   }`
+     * )
+     * ```
+     */
     createCodeFile(name: string, code: string, options?: {
         editViaPlugin?: boolean;
     }): Promise<CodeFile>;
-    /** Get an array of all code files  */
+    /**
+     * Get all code files in the project.
+     *
+     * @returns An array of all CodeFile instances.
+     *
+     * @example
+     * ```ts
+     * const allFiles = await framer.getCodeFiles()
+     * console.log(`Project has ${allFiles.length} code files`)
+     * ```
+     */
     getCodeFiles(): Promise<readonly CodeFile[]>;
-    /** Get a specific code file */
+    /**
+     * Get a specific code file by its ID.
+     *
+     * @param id - The unique identifier of the code file.
+     * @returns The CodeFile instance or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const codeFile = await framer.getCodeFile("code-file-id")
+     * ```
+     */
     getCodeFile(id: string): Promise<CodeFile | null>;
     /**
      * Lint a code file and return the diagnostics.
@@ -4041,17 +5601,77 @@ declare class FramerPluginAPI {
      */
     typecheckCode(fileName: string, content: string, compilerOptions?: ts.server.protocol.CompilerOptions, sessionId?: string): Promise<TypecheckDiagnostic[]>;
     /**
-     * Subscribe to changes in code files.
-     * This will be called when code files are added, removed, or updated and will return an array of
-     * all code files in the project.
+     * Subscribe to changes in code files across the project. The callback is
+     * called when code files are added, removed, or updated, and receives an
+     * array of all code files in the project.
+     *
+     * @param callback - Function called when code files change.
+     * @returns A function to stop listening to changes.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = framer.subscribeToCodeFiles((codeFiles) => {
+     *   console.log(`Code files updated: ${codeFiles.length} total files`)
+     * })
+     *
+     * // Later, stop listening
+     * unsubscribe()
+     * ```
      */
     subscribeToCodeFiles(callback: (codeFiles: readonly CodeFile[]) => void): Unsubscribe$1;
     /**
      * Set the plugin's menu, which is shown in the plugin window header.
+     *
+     * @param items - The entries to add to the menu.
+     *
+     * @example
+     * ```ts
+     * await framer.setMenu([
+     *     {
+     *         label: "New",
+     *         onAction: newFile,
+     *     },
+     *     {
+     *         type: "separator",
+     *     },
+     *     {
+     *         label: "Log Out",
+     *         onAction: logOut,
+     *     },
+     * ])
+     * ```
      */
     setMenu(menuItems: MenuItem[]): Promise<void>;
     /**
      * Show a context menu at the given location.
+     *
+     * Placement is relative to the location.
+     *
+     * @param menuItems - The entries to add to the context menu.
+     * @param config - Configuration for positioning the context menu.
+     *
+     * @example
+     * ```ts
+     * await framer.showContextMenu(
+     *   [
+     *     {
+     *       label: "Edit",
+     *       enabled: item.isEditable,
+     *       onAction: () => editItem(item)
+     *     },
+     *     { type: "separator" },
+     *     {
+     *       label: "Remove",
+     *       onAction: () => removeItem(item),
+     *     },
+     *   ],
+     *   {
+     *     location: { x: event.clientX, y: event.clientY },
+     *     placement: "bottom-left",
+     *     width: 220,
+     *   }
+     * )
+     * ```
      */
     showContextMenu(menuItems: MenuItem[], config: ContextMenuConfig): Promise<void>;
     /**
@@ -4062,18 +5682,37 @@ declare class FramerPluginAPI {
      */
     unstable_ensureMinimumDependencyVersion(packageName: string, version: string): Promise<void>;
     /**
-     * Navigate to a node by ID with optional selection and zoom behaviour.
+     * Navigate the Framer UI to a target by its ID. When the target isn't in the
+     * current mode, it might terminate or restart the plugin in the new mode.
      *
      * @param nodeId - The ID of the node to navigate to.
      * @param opts - The options for the navigation.
      * @returns A promise that resolves when the navigation is complete.
+     *
+     * @example
+     * ```ts
+     * await framer.navigateTo(nodeId, opts)
+     * ```
      */
     navigateTo(nodeId: string, opts?: NavigableOptions): Promise<void>;
     /**
-     * Subscribe to the currently open code file in the Code Editor.
+     * Subscribe to changes in the Code Editor's active file. This function is
+     * primarily useful when the plugin's mode is `"code"`.
+     *
+     * @param callback - Function called when the active code file changes.
+     * @returns A function to stop listening to changes.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = framer.subscribeToOpenCodeFile((codeFile) => {
+     *   if (codeFile) {
+     *     console.log(`Currently open code file: ${codeFile.id}`)
+     *   }
+     * })
      *
-     * @param callback - The callback to call when the code file changes.
-     * @returns A function to unsubscribe from the subscription.
+     * // Later, stop listening
+     * unsubscribe()
+     * ```
      */
     subscribeToOpenCodeFile(callback: (codeFile: CodeFile | null) => void): Unsubscribe$1;
     /**
@@ -4081,6 +5720,8 @@ declare class FramerPluginAPI {
      *
      * If you want to open the newly created design page, you can `.navigateTo()` the page after creation.
      *
+     * @param pageName - The name for the new design page.
+     *
      * @example
      * ```ts
      * const designPage = await framer.createDesignPage("About")
@@ -4093,6 +5734,8 @@ declare class FramerPluginAPI {
      *
      * If you want to open the newly created web page, you can `.navigateTo()` the page after creation.
      *
+     * @param pagePath - The path for the new web page (e.g., "/about").
+     *
      * @example
      * ```ts
      * const webPage = await framer.createWebPage("/about")
@@ -4102,17 +5745,39 @@ declare class FramerPluginAPI {
     createWebPage(pagePath: string): Promise<WebPageNode>;
     /**
      * Create a new collection.
+     *
+     * @param name - The name to give the new collection.
      */
     createCollection(name: string): Promise<Collection>;
     /**
-     * Create a new managed collection.
+     * Add a new plugin-managed CMS Collection.
+     *
+     * If a name is provided which matches an existing Collection, the promise will reject.
+     *
+     * @param name - The name to give the new collection.
+     *
+     * @example
+     * ```ts
+     * const newCollection = await framer.createManagedCollection(name)
+     * ```
      */
     createManagedCollection(name: string): Promise<ManagedCollection>;
     /**
-     * Set a warning message to show when the user attempts to close the plugin. Set to false to disable.
-     * - `string` to enable with a custom message.
-     * - `false` to disable.
-     * */
+     * When enabled, a modal confirmation will appear before close to confirm the action.
+     *
+     * Pass `false` to disable the warning.
+     *
+     * @param message - The message to show when attempting to close the plugin. `false` disables the warning.
+     *
+     * @example
+     * ```ts
+     * // Show a close warning when the user attempts to close the plugin
+     * await framer.setCloseWarning("Are you sure?")
+     *
+     * // Remove the close warning
+     * await framer.setCloseWarning(false)
+     * ```
+     */
     setCloseWarning(message: string | false): Promise<void>;
     /**
      * Initial state data passed from Vekter during handshake.
@@ -4581,6 +6246,7 @@ declare const fileAssetDiscriminator: "FileAsset";
 interface FileAssetData extends AssetIdentifier, FileAssetDataFields {
     [classKey]: typeof fileAssetDiscriminator;
 }
+/** A file asset uploaded to the Framer project. */
 declare class FileAsset implements AssetIdentifier, FileAssetDataFields {
     readonly id: AssetId;
     readonly url: string;
@@ -4620,6 +6286,10 @@ interface Size {
      */
     height: number;
 }
+/**
+ * An image that has been uploaded to the Framer project. Provides methods
+ * to access image data, measure dimensions, and load as bitmap or HTML element.
+ */
 declare class ImageAsset implements ImageDataFields, AssetIdentifier {
     #private;
     readonly id: AssetId;
@@ -4631,11 +6301,14 @@ declare class ImageAsset implements ImageDataFields, AssetIdentifier {
     static [$framerInternal.unmarshal](engine: PluginEngine, data: ImageAssetData): ImageAsset;
     [$framerInternal.marshal](): ImageAssetData;
     /**
-     * Clone this image, optionally overriding its attributes.
+     * Clone this image asset, optionally overriding `altText` or `resolution`.
+     * The clone shares the same underlying image data.
      */
     cloneWithAttributes({ altText, resolution, }: Prettify<Partial<Pick<ImageAssetData, "altText" | "resolution">>>): ImageAsset;
     /**
-     * Measure this image.
+     * Measure this image's natural dimensions.
+     *
+     * @returns The width and height in pixels. Warning: values may be zero.
      */
     measure(): Promise<Size>;
     /**