@fluid-app/fluid-cli-portal 0.1.61 → 0.1.63

package/dist/index.d.mts

@@ -1284,761 +1284,909 @@ declare const versionCommand: Command;
 declare const doctorCommand: Command;
 //#endregion
 //#region ../../portal/definition-schema/src/generated/types.d.ts
+/** JSON scalar value. */
 type JsonPrimitive = string | number | boolean | null;
+/** Serializable value accepted by portal resources and widget props. */
 type JsonValue = JsonPrimitive | JsonValue[] | JsonObject | PortalWidgetNode;
+/** Serializable object with arbitrary string keys. */
 interface JsonObject {
+  /** Serializable value stored at this key. */
   readonly [key: string]: JsonValue;
 }
+/** Semantic color token accepted by widget properties. */
 type ColorOption = "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+/** Data-source configuration attached to a widget node. */
 interface PortalDataSourceConfig {
+  /** Ordered data-source definitions evaluated for the widget. */
   readonly sources: JsonObject[];
+  /** Loading presentation settings. */
   readonly loading?: {
     readonly showSkeleton?: boolean;
   };
+  /** Failure fallback and retry settings. */
   readonly error?: {
     readonly fallback?: JsonObject;
     readonly retryCount?: number;
     readonly retryDelay?: number;
   };
 }
+/** Fields shared by built-in and third-party widget nodes. */
 interface PortalWidgetNodeBase {
+  /** Stable node identifier within the screen. */
   readonly id: string;
+  /** Registered widget type. */
   readonly type: string;
+  /** Widget-owned serializable properties. */
   readonly props: JsonObject;
+  /** Optional configuration that populates widget props. */
   readonly dataSource?: PortalDataSourceConfig;
+  /** Zero-based parent layout column. */
   readonly columnIndex?: number;
 }
+/** Portal node for the AlertWidget built-in widget. */
 interface AlertWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "AlertWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    title?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleFontWeight?: "normal" | "medium" | "semibold" | "bold";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    titleAlignment?: "left" | "center" | "right";
-    description?: string;
-    descriptionFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    descriptionFontWeight?: "normal" | "medium" | "semibold" | "bold";
-    descriptionColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    descriptionAlignment?: "left" | "center" | "right";
+    /** Enable the title displayed above the text */titleEnabled?: boolean; /** The title */
+    title?: string; /** Font size for the title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Font weight for the title */
+    titleFontWeight?: "normal" | "medium" | "semibold" | "bold"; /** The color of the title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Text alignment for the title */
+    titleAlignment?: "left" | "center" | "right"; /** The text message */
+    description?: string; /** Font size for the text */
+    descriptionFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Font weight for the text */
+    descriptionFontWeight?: "normal" | "medium" | "semibold" | "bold"; /** The color of the text */
+    descriptionColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Text alignment for the description */
+    descriptionAlignment?: "left" | "center" | "right"; /** Background for the text container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
+    }; /** The padding of the text container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** The border radius of the text container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** The border width of the text container */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** The border color of the text container */
     borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
   };
 }
+/** Portal node for the BulletListWidget built-in widget. */
 interface BulletListWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "BulletListWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    title?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    listType?: "unordered" | "ordered";
-    items?: string[];
-    itemFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    itemColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+    /** Enable the title displayed above the list */titleEnabled?: boolean; /** The title */
+    title?: string; /** Font size for the title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** The color of the title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Ordered (numbered) or unordered (bullets) */
+    listType?: "unordered" | "ordered"; /** Add or remove list items */
+    items?: string[]; /** Font size for list items */
+    itemFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** The color of list items */
+    itemColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Background for the list container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+    }; /** The padding of the list container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** The border radius of the list container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Gap between list items */
     gapSize?: "none" | "xs" | "sm" | "md" | "lg" | "xl";
   };
 }
+/** Portal node for the CalendarWidget built-in widget. */
 interface CalendarWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "CalendarWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    titleText?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+    /** Enable the title displayed above the calendar */titleEnabled?: boolean; /** Title text displayed above the calendar */
+    titleText?: string; /** Font size for the widget title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the widget title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Background for the calendar container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    showYearEyebrow?: boolean;
-    showTodayButton?: boolean;
-    showEventDensity?: boolean;
+    }; /** Default text color for calendar content */
+    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Drives today highlight, event dots, Today pill, and selected day */
+    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Padding around the calendar container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Border radius for the calendar container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the calendar container */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the calendar container */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Small uppercase year label above the month (e.g. '2026 / November'). */
+    showYearEyebrow?: boolean; /** Show a 'Today' pill when viewing a different month. */
+    showTodayButton?: boolean; /** Show 1–3 dots per day based on event count (off = single dot). */
+    showEventDensity?: boolean; /** Subtly dim the Sun/Sat day-of-week headers for visual rhythm. */
     weekendDim?: boolean;
   };
 }
+/** Portal node for the CardWidget built-in widget. */
 interface CardWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "CardWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    headerEnabled?: boolean;
-    title?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    headerBackground?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    footerEnabled?: boolean;
-    footerContent?: string;
-    footerColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    footerBackground?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+    /** Toggle header visibility */headerEnabled?: boolean; /** Card title text */
+    title?: string; /** Font size for the title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Background color for the header */
+    headerBackground?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Toggle footer visibility */
+    footerEnabled?: boolean; /** Footer content text */
+    footerContent?: string; /** Color for the footer text */
+    footerColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Background color for the footer */
+    footerBackground?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Background for the card */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    gapSize?: "none" | "xs" | "sm" | "md" | "lg" | "xl";
+    }; /** Card padding */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Card border radius */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Card border width */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Card border color */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Gap between child widgets */
+    gapSize?: "none" | "xs" | "sm" | "md" | "lg" | "xl"; /** Child widget nodes rendered inside this container. */
     children?: Array<PortalWidgetNode | null>;
   };
 }
+/** Portal node for the CarouselWidget built-in widget. */
 interface CarouselWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "CarouselWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    editorialFrame?: boolean;
-    frameColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    headerSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    headerColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    textSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+    /** Premium dark canvas with layered shadow and gradient stack. Turn off for a classic transparent carousel. */editorialFrame?: boolean; /** Surface color of the carousel canvas. Drives the frame and gradient overlay. */
+    frameColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Font size for the slide header */
+    headerSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Headline color. Also drives eyebrow, controls and progress bar. */
+    headerColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Font size for the slide text */
+    textSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color variant for the slide text */
+    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Alignment of the carousel content */
     align?: {
       vertical?: "top" | "center" | "bottom";
       horizontal?: "left" | "center" | "right";
-    };
-    textWidth?: string;
-    carouselHeight?: string;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    overlayEnabled?: boolean;
-    overlayType?: "solid" | "gradient";
-    overlayIntensity?: number;
-    showButton?: boolean;
-    buttonColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    buttonSize?: "sm" | "default" | "lg" | "xl";
-    enableAutoScroll?: boolean;
-    autoScrollInterval?: number;
+    }; /** Maximum width for slide content */
+    textWidth?: string; /** Height of the carousel */
+    carouselHeight?: string; /** Rounded corners for the carousel */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the carousel container */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the carousel container */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Inner padding around slide content */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Add background overlay to slide content */
+    overlayEnabled?: boolean; /** Overlay style (only applies when editorial frame is off) */
+    overlayType?: "solid" | "gradient"; /** Opacity of the overlay (0-100) */
+    overlayIntensity?: number; /** Global show/hide for all slide CTAs. Per-slide button content is set on each item under the Data tab (custom sources only). */
+    showButton?: boolean; /** Color variant for the slide button */
+    buttonColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Size of the slide button */
+    buttonSize?: "sm" | "default" | "lg" | "xl"; /** Automatically advance to the next slide. Progress bar fills at this rate and pauses on hover. */
+    enableAutoScroll?: boolean; /** Time between automatic slide transitions */
+    autoScrollInterval?: number; /** Slides rendered by the carousel, usually supplied by a data source. */
     slides?: JsonValue;
   };
 }
+/** Portal node for the CatchUpWidget built-in widget. */
 interface CatchUpWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "CatchUpWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    titleText?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+    /** Enable the title displayed above the catch ups */titleEnabled?: boolean; /** Title text displayed above the catch ups */
+    titleText?: string; /** Font size for the widget title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the widget title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Background for the container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    maxItems?: number;
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
+    }; /** Default text color for catch up items */
+    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Color used for count display and icons */
+    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Maximum number of catch ups to display */
+    maxItems?: number; /** Padding around the container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Border radius for the container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
     borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
   };
 }
+/** Portal node for the ChartWidget built-in widget. */
 interface ChartWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "ChartWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    title?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    description?: string;
-    descriptionFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    descriptionColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    chartType?: "bar" | "line" | "area" | "pie";
-    showLegend?: boolean;
-    showTooltip?: boolean;
-    showGrid?: boolean;
-    width?: string;
-    height?: string;
+    /** Enable the title displayed above the chart */titleEnabled?: boolean; /** The chart title */
+    title?: string; /** Font size for the chart title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the chart title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** The chart description */
+    description?: string; /** Font size for the chart description */
+    descriptionFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the chart description */
+    descriptionColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Type of chart to display */
+    chartType?: "bar" | "line" | "area" | "pie"; /** Display chart legend */
+    showLegend?: boolean; /** Display tooltip on hover */
+    showTooltip?: boolean; /** Display background grid lines */
+    showGrid?: boolean; /** Width of the chart container (CSS value, e.g., 100%, 600px) */
+    width?: string; /** Height of the chart */
+    height?: string; /** Background for the chart container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    dataKey?: "value";
-    xAxisKey?: "name";
-    data?: JsonValue;
+    }; /** Padding for the chart container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Border radius for the chart container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Key in the data to use for chart values */
+    dataKey?: "value"; /** Key in the data to use for X-axis labels */
+    xAxisKey?: "name"; /** Records plotted by the chart, usually supplied by a data source. */
+    data?: JsonValue; /** Series labels, colors, and value mappings for the chart data. */
     chartConfig?: JsonValue;
   };
 }
+/** Portal node for the ContainerWidget built-in widget. */
 interface ContainerWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "ContainerWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    gapSize?: "none" | "xs" | "sm" | "md" | "lg" | "xl";
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
+    /** Gap between widgets */gapSize?: "none" | "xs" | "sm" | "md" | "lg" | "xl"; /** Padding for the container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Background for the container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
+    }; /** Child widget nodes rendered inside this container. */
     children?: Array<PortalWidgetNode | null>;
   };
 }
+/** Portal node for the EmbedWidget built-in widget. */
 interface EmbedWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "EmbedWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    url?: string;
-    title?: string;
-    displayMode?: "inline" | "cover";
-    coverResource?: string | null | JsonObject;
-    coverUseCustomUrl?: boolean;
-    coverImageUrl?: string;
-    coverHeight?: string;
-    coverShowHeader?: boolean;
-    coverHeaderIcon?: "GraduationCap" | "Video" | "BookOpen" | "Globe" | "User" | "Star" | "Heart" | "Trophy" | "Sparkles" | "Zap" | "Gift" | "ShoppingBag" | "Bell" | "Calendar" | "Bookmark";
-    coverHeaderIconColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    coverTitle?: string;
-    coverMeta?: string;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    fullScreen?: boolean;
-    height?: string;
-    allowFullscreen?: boolean;
+    /** The URL of the external site to embed */url?: string; /** Describes the embed for screen readers and assistive tech. Not visible on the page. */
+    title?: string; /** Inline: iframe renders directly. Cover: shows a card that opens the embed in a full-screen modal. */
+    displayMode?: "inline" | "cover"; /** Select the image shown before the embed opens */
+    coverResource?: string | null | JsonObject; /** Enter a custom image URL instead of selecting media */
+    coverUseCustomUrl?: boolean; /** Direct URL to the cover image */
+    coverImageUrl?: string; /** Height of the cover image area */
+    coverHeight?: string; /** Show the header with icon, title, and action buttons */
+    coverShowHeader?: boolean; /** Icon displayed in the colored badge on the left */
+    coverHeaderIcon?: "GraduationCap" | "Video" | "BookOpen" | "Globe" | "User" | "Star" | "Heart" | "Trophy" | "Sparkles" | "Zap" | "Gift" | "ShoppingBag" | "Bell" | "Calendar" | "Bookmark"; /** Background color of the icon badge */
+    coverHeaderIconColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Title shown in the card header and modal (falls back to the widget Title if empty). Available even when the card header is hidden so the modal still has a meaningful title. */
+    coverTitle?: string; /** Small uppercase meta line below the title (e.g. 'APR 16 · COACHING THE HOSTESS') */
+    coverMeta?: string; /** Border radius for the embed container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Inline mode: fill the available space instead of a fixed height */
+    fullScreen?: boolean; /** Height of the inline embed iframe */
+    height?: string; /** Allow embedded video/content to use fullscreen mode and show the inline expand control when available */
+    allowFullscreen?: boolean; /** When to load the embedded content (inline mode only) */
     loading?: "lazy" | "eager";
   };
 }
+/** Portal node for the ImageWidget built-in widget. */
 interface ImageWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "ImageWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    resource?: string | null | JsonObject;
-    useCustomUrl?: boolean;
-    src?: string;
-    alt?: string;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    verticalSizing?: "auto" | "fixed";
-    fixedHeight?: string;
-    displayFit?: "cover" | "contain";
-    focusPoint?: string;
-    linkType?: "url" | "screen" | "share";
-    href?: string;
-    openInNewTab?: boolean;
-    screenSlug?: string;
-    shareSource?: "resource" | "url";
-    shareResource?: string | null | JsonObject;
+    /** Browse and select an image */resource?: string | null | JsonObject; /** Enter a custom image URL instead of selecting media */
+    useCustomUrl?: boolean; /** The source URL of the image */
+    src?: string; /** Alternative text for the image (for accessibility) */
+    alt?: string; /** Border radius for the container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** How the image height is determined */
+    verticalSizing?: "auto" | "fixed"; /** Fixed height of the image container */
+    fixedHeight?: string; /** How the image fills its container */
+    displayFit?: "cover" | "contain"; /** The focal point of the image within its container */
+    focusPoint?: string; /** Choose whether this link opens a URL, screen, or share action */
+    linkType?: "url" | "screen" | "share"; /** The destination URL */
+    href?: string; /** Whether to open the link in a new tab */
+    openInNewTab?: boolean; /** Select a screen to navigate to */
+    screenSlug?: string; /** Choose whether the share action uses a resource or URL */
+    shareSource?: "resource" | "url"; /** Select content to share */
+    shareResource?: string | null | JsonObject; /** The URL to share */
     shareUrl?: string;
   };
 }
+/** Portal node for the LayoutWidget built-in widget. */
 interface LayoutWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "LayoutWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    sectionLayout?: "single-column" | "2c-equal" | "2c-left-wider" | "2c-right-wider" | "2c-left-narrow" | "2c-right-narrow" | "3c-equal" | "3c-middle-wider";
-    gapSize?: "none" | "xs" | "sm" | "md" | "lg" | "xl";
+    /** Column layout configuration */sectionLayout?: "single-column" | "2c-equal" | "2c-left-wider" | "2c-right-wider" | "2c-left-narrow" | "2c-right-narrow" | "3c-equal" | "3c-middle-wider"; /** Gap between columns and widgets */
+    gapSize?: "none" | "xs" | "sm" | "md" | "lg" | "xl"; /** Background for the layout container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+    }; /** Padding for the layout container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Border radius for the layout container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Child widget nodes rendered inside this container. */
     children?: Array<PortalWidgetNode | null>;
   };
 }
+/** Portal node for the LinkWidget built-in widget. */
 interface LinkWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "LinkWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    linkType?: "url" | "screen" | "share";
-    text?: string;
-    href?: string;
-    openInNewTab?: boolean;
-    screenSlug?: string;
-    shareSource?: "resource" | "url";
-    shareResource?: string | null | JsonObject;
-    shareUrl?: string;
-    variant?: "default" | "outline" | "secondary" | "ghost" | "destructive";
-    size?: "sm" | "default" | "lg" | "xl";
-    fontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    underline?: boolean;
-    alignment?: "left" | "center" | "right";
-    fullWidth?: boolean;
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadiusTL?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderRadiusTR?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderRadiusBL?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderRadiusBR?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
+    /** Choose whether this button opens a URL, screen, or share action */linkType?: "url" | "screen" | "share"; /** The button label text */
+    text?: string; /** The destination URL */
+    href?: string; /** Whether to open the link in a new tab */
+    openInNewTab?: boolean; /** Select a screen to navigate to */
+    screenSlug?: string; /** Choose whether the share action uses a resource or URL */
+    shareSource?: "resource" | "url"; /** Select content to share */
+    shareResource?: string | null | JsonObject; /** The URL to share */
+    shareUrl?: string; /** The visual style of the button */
+    variant?: "default" | "outline" | "secondary" | "ghost" | "destructive"; /** The size of the button */
+    size?: "sm" | "default" | "lg" | "xl"; /** The font size of the button text */
+    fontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Underline the button text */
+    underline?: boolean; /** Horizontal alignment of the button */
+    alignment?: "left" | "center" | "right"; /** Makes the button stretch to full container width */
+    fullWidth?: boolean; /** Outer container padding */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Corner radius of the link button (borderRadiusTL corner). */
+    borderRadiusTL?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Corner radius of the link button (borderRadiusTR corner). */
+    borderRadiusTR?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Corner radius of the link button (borderRadiusBL corner). */
+    borderRadiusBL?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Corner radius of the link button (borderRadiusBR corner). */
+    borderRadiusBR?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
     borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
   };
 }
+/** Portal node for the ListWidget built-in widget. */
 interface ListWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "ListWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    title?: string;
-    titleSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl";
+    /** Enable the title displayed above the list */titleEnabled?: boolean; /** Header text for the list */
+    title?: string; /** Size of the list title */
+    titleSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the list title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Padding inside the container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Rounded corners for the container and images */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Spacing between items */
+    gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl"; /** Background color or image for the widget */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    listType?: "unordered" | "ordered";
-    maxItems?: number;
-    imageAspectRatio?: "square" | "landscape" | "portrait";
-    showBadge?: boolean;
-    showMetaText?: boolean;
-    columns?: number;
-    scrollAxis?: "horizontal" | "vertical";
-    numberColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    numberSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    itemTitleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    itemTitleSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    descriptionColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    descriptionSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    priceColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    priceSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    originalPriceColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    metaTextColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    metaTextSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    showFeaturedSection?: boolean;
-    featuredAsset?: string | null | JsonObject;
-    featuredTitle?: string;
-    featuredSubtitle?: string;
-    featuredButtonText?: string;
-    featuredButtonUrl?: string;
-    featuredSubtitleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    featuredSubtitleSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
+    }; /** Type of list layout */
+    listType?: "unordered" | "ordered"; /** Maximum number of items to display */
+    maxItems?: number; /** Aspect ratio for item images (unordered list — ordered layouts use a fixed ratio per axis) */
+    imageAspectRatio?: "square" | "landscape" | "portrait"; /** Display discount badge on images */
+    showBadge?: boolean; /** Display QV and CV values */
+    showMetaText?: boolean; /** Number of columns in the grid (unordered list only) */
+    columns?: number; /** Direction for ordered list scrolling */
+    scrollAxis?: "horizontal" | "vertical"; /** Color for ordered list numbers */
+    numberColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Size of ordered list numbers (vertical scroll only — horizontal uses a fixed editorial size) */
+    numberSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for item titles */
+    itemTitleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Size of item titles */
+    itemTitleSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for descriptions */
+    descriptionColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Size of descriptions */
+    descriptionSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for prices */
+    priceColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Size of prices */
+    priceSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for crossed-out original prices */
+    originalPriceColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Color for QV/CV text */
+    metaTextColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Size of QV/CV text */
+    metaTextSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Display a featured content section */
+    showFeaturedSection?: boolean; /** Select a single image or video resource for the featured section */
+    featuredAsset?: string | null | JsonObject; /** Title for featured section */
+    featuredTitle?: string; /** Subtitle for featured section */
+    featuredSubtitle?: string; /** Text for featured section button */
+    featuredButtonText?: string; /** URL for featured section button */
+    featuredButtonUrl?: string; /** Color for featured subtitle */
+    featuredSubtitleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Size of featured subtitle */
+    featuredSubtitleSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Items rendered by the list, usually supplied by a data source. */
     items?: JsonValue;
   };
 }
+/** Portal node for the MySiteWidget built-in widget. */
 interface MySiteWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "MySiteWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    showPreview?: boolean;
-    showAnalytics?: boolean;
-    showLiveBadge?: boolean;
-    showQR?: boolean;
+    /** Show the live iframe preview of the storefront */showPreview?: boolean; /** Visitors and Leads grid in the footer */
+    showAnalytics?: boolean; /** Small 'Live' chip in the preview corner */
+    showLiveBadge?: boolean; /** Show a scannable QR code in the card footer */
+    showQR?: boolean; /** Background for the widget container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+    }; /** Primary text, hairline, and neutral chip color */
+    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Drives the Live dot, conversion ring, and Visit CTA */
+    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Corner radius for the widget and inner chips */
     borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
   };
 }
+/** Portal node for the NestedWidget built-in widget. */
 interface NestedWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "NestedWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    resource?: string | null | JsonObject;
-    titleEnabled?: boolean;
-    titleText?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    primaryMediaHeight?: string;
+    /** Select the primary media displayed in the large panel */resource?: string | null | JsonObject; /** Enable the title displayed over the primary media */
+    titleEnabled?: boolean; /** Main title displayed over the primary media */
+    titleText?: string; /** Font size for the widget title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the widget title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Height of the primary media container */
+    primaryMediaHeight?: string; /** Alignment of the content inside the primary media */
     titleAlignment?: {
       vertical?: "top" | "center" | "bottom";
       horizontal?: "left" | "center" | "right";
-    };
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    overlayEnabled?: boolean;
-    overlayType?: "solid" | "gradient";
-    overlayIntensity?: number;
-    gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl";
-    nestedTextColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+    }; /** Padding used throughout the widget */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Rounded corners for the widget */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Add a dark overlay to the primary media for better text readability */
+    overlayEnabled?: boolean; /** Type of overlay effect */
+    overlayType?: "solid" | "gradient"; /** Opacity of the overlay (0-100) */
+    overlayIntensity?: number; /** Gap between nested media items */
+    gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl"; /** Color for nested media labels */
+    nestedTextColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Background color for nested media container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
+    }; /** Shareable records rendered in the nested content region. */
     shareables?: JsonValue;
   };
 }
+/** Portal node for the PointsWidget built-in widget. */
 interface PointsWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "PointsWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    title?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    balanceColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    historyEnabled?: boolean;
-    historyTitle?: string;
+    /** Toggle title visibility */titleEnabled?: boolean; /** Title text displayed above the balance. Leave blank to use the company's configured points label. */
+    title?: string; /** Font size for the title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Color for the points balance number */
+    balanceColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Show a collapsible history dropdown below the balance */
+    historyEnabled?: boolean; /** Title for the history dropdown */
+    historyTitle?: string; /** Background for the widget */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
+    }; /** Default text color */
+    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Color for positive points amounts */
+    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Widget padding */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Widget border radius */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Widget border width */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Widget border color */
     borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
   };
 }
+/** Portal node for the QuickLinksWidget built-in widget. */
 interface QuickLinksWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "QuickLinksWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    title?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    link1Label?: string;
-    link1Url?: string;
-    link1Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles";
-    link1Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    link2Enabled?: boolean;
-    link2Label?: string;
-    link2Url?: string;
-    link2Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles";
-    link2Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    link3Enabled?: boolean;
-    link3Label?: string;
-    link3Url?: string;
-    link3Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles";
-    link3Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    link4Enabled?: boolean;
-    link4Label?: string;
-    link4Url?: string;
-    link4Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles";
-    link4Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    link5Enabled?: boolean;
-    link5Label?: string;
-    link5Url?: string;
-    link5Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles";
-    link5Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    link6Enabled?: boolean;
-    link6Label?: string;
-    link6Url?: string;
-    link6Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles";
-    link6Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    link7Enabled?: boolean;
-    link7Label?: string;
-    link7Url?: string;
-    link7Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles";
-    link7Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    link8Enabled?: boolean;
-    link8Label?: string;
-    link8Url?: string;
-    link8Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles";
-    link8Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    layout?: "cards" | "list";
-    iconRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    showChevron?: boolean;
-    openInNewTab?: boolean;
+    /** Small heading shown above the link list */titleEnabled?: boolean; /** Heading shown above the links */
+    title?: string; /** Font size for the widget title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the widget title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Text shown on the link */
+    link1Label?: string; /** Where the link points (use '#' for a placeholder). Click a chip below to insert a user variable (e.g. `{{username}}`, `{{replicated_url}}`, `{{external_id}}`); append `|| /fallback` to set a fallback path. */
+    link1Url?: string; /** Icon displayed in the colored badge */
+    link1Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles"; /** Color of the icon badge */
+    link1Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Display link slot 2 */
+    link2Enabled?: boolean; /** Text shown on the link */
+    link2Label?: string; /** Where the link points (use '#' for a placeholder). Click a chip below to insert a user variable (e.g. `{{username}}`, `{{replicated_url}}`, `{{external_id}}`); append `|| /fallback` to set a fallback path. */
+    link2Url?: string; /** Icon displayed in the colored badge */
+    link2Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles"; /** Color of the icon badge */
+    link2Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Display link slot 3 */
+    link3Enabled?: boolean; /** Text shown on the link */
+    link3Label?: string; /** Where the link points (use '#' for a placeholder). Click a chip below to insert a user variable (e.g. `{{username}}`, `{{replicated_url}}`, `{{external_id}}`); append `|| /fallback` to set a fallback path. */
+    link3Url?: string; /** Icon displayed in the colored badge */
+    link3Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles"; /** Color of the icon badge */
+    link3Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Display link slot 4 */
+    link4Enabled?: boolean; /** Text shown on the link */
+    link4Label?: string; /** Where the link points (use '#' for a placeholder). Click a chip below to insert a user variable (e.g. `{{username}}`, `{{replicated_url}}`, `{{external_id}}`); append `|| /fallback` to set a fallback path. */
+    link4Url?: string; /** Icon displayed in the colored badge */
+    link4Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles"; /** Color of the icon badge */
+    link4Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Display link slot 5 */
+    link5Enabled?: boolean; /** Text shown on the link */
+    link5Label?: string; /** Where the link points (use '#' for a placeholder). Click a chip below to insert a user variable (e.g. `{{username}}`, `{{replicated_url}}`, `{{external_id}}`); append `|| /fallback` to set a fallback path. */
+    link5Url?: string; /** Icon displayed in the colored badge */
+    link5Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles"; /** Color of the icon badge */
+    link5Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Display link slot 6 */
+    link6Enabled?: boolean; /** Text shown on the link */
+    link6Label?: string; /** Where the link points (use '#' for a placeholder). Click a chip below to insert a user variable (e.g. `{{username}}`, `{{replicated_url}}`, `{{external_id}}`); append `|| /fallback` to set a fallback path. */
+    link6Url?: string; /** Icon displayed in the colored badge */
+    link6Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles"; /** Color of the icon badge */
+    link6Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Display link slot 7 */
+    link7Enabled?: boolean; /** Text shown on the link */
+    link7Label?: string; /** Where the link points (use '#' for a placeholder). Click a chip below to insert a user variable (e.g. `{{username}}`, `{{replicated_url}}`, `{{external_id}}`); append `|| /fallback` to set a fallback path. */
+    link7Url?: string; /** Icon displayed in the colored badge */
+    link7Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles"; /** Color of the icon badge */
+    link7Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Display link slot 8 */
+    link8Enabled?: boolean; /** Text shown on the link */
+    link8Label?: string; /** Where the link points (use '#' for a placeholder). Click a chip below to insert a user variable (e.g. `{{username}}`, `{{replicated_url}}`, `{{external_id}}`); append `|| /fallback` to set a fallback path. */
+    link8Url?: string; /** Icon displayed in the colored badge */
+    link8Icon?: "Link" | "User" | "Share2" | "ShoppingBag" | "Video" | "Mail" | "MessageCircle" | "Globe" | "Calendar" | "Bell" | "Heart" | "Star" | "Zap" | "Gift" | "Phone" | "MapPin" | "Play" | "Package" | "ExternalLink" | "Bookmark" | "Trophy" | "Sparkles"; /** Color of the icon badge */
+    link8Color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Cards: separated tiles. List: grouped rows with dividers. */
+    layout?: "cards" | "list"; /** Corner radius for the colored icon badge */
+    iconRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Right-aligned chevron indicating each row is a link */
+    showChevron?: boolean; /** Open links in a new tab instead of the same window */
+    openInNewTab?: boolean; /** Background for the widget container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
+    }; /** Label + chevron color, and the base for row backgrounds (via opacity) */
+    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Padding around the widget */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Widget border radius (also drives row corners in cards layout) */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Widget border width */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Widget border color */
     borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
   };
 }
+/** Portal node for the QuickShareWidget built-in widget. */
 interface QuickShareWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "QuickShareWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    shareableResource?: string | null | JsonObject;
-    titleEnabled?: boolean;
-    titleText?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    showResourceType?: boolean;
-    showShareActions?: boolean;
-    showDomainPrefix?: boolean;
-    showBuyButton?: boolean;
-    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    overlayEnabled?: boolean;
-    overlayType?: "gradient" | "solid";
-    overlayIntensity?: number;
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
+    /** Select the content to generate a share link for */shareableResource?: string | null | JsonObject; /** Display a title on the hero */
+    titleEnabled?: boolean; /** Custom title text (defaults to the resource title if empty) */
+    titleText?: string; /** Font size for the title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Display a small type eyebrow chip (Product · Page · Media…) */
+    showResourceType?: boolean; /** Show Email, Text, and native Share buttons under the link chip */
+    showShareActions?: boolean; /** Include the domain in the link chip (dimmed) with the path emphasized */
+    showDomainPrefix?: boolean; /** Display the Buy button (only shown for Product resources) */
+    showBuyButton?: boolean; /** Default text color for widget content (over the hero) */
+    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Drives the price chip, primary button, and copy-success flash */
+    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Add editorial gradient stack for legibility over the hero */
+    overlayEnabled?: boolean; /** Gradient only (recommended) or gradient + solid wash (heavier) */
+    overlayType?: "gradient" | "solid"; /** Opacity of the overlay (0-100) */
+    overlayIntensity?: number; /** Padding around the widget content */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Border radius for the widget container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget container */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget container */
     borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
   };
 }
+/** Portal node for the RecentActivityWidget built-in widget. */
 interface RecentActivityWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "RecentActivityWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    titleText?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    showEyebrow?: boolean;
-    showCountChip?: boolean;
-    maxItemsToShow?: number;
-    showRelativeTime?: boolean;
+    /** Display the title and eyebrow above the feed */titleEnabled?: boolean; /** Title text displayed above the activity feed */
+    titleText?: string; /** Font size for the widget title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the widget title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Small uppercase label above the title */
+    showEyebrow?: boolean; /** Accent pill next to the title showing how many updates */
+    showCountChip?: boolean; /** Maximum number of activity items to display */
+    maxItemsToShow?: number; /** Show 'now / 2m / 1h / 3d' instead of absolute times */
+    showRelativeTime?: boolean; /** Background for the widget container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
+    }; /** Default text color for activity content */
+    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Drives the count chip, type badge, initials avatar, and empty-state icon */
+    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Padding around the widget container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Border radius for the widget container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget container */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget container */
     borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
   };
 }
+/** Portal node for the SeparatorWidget built-in widget. */
 interface SeparatorWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "SeparatorWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    orientation?: "horizontal" | "vertical";
-    color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    thickness?: string;
-    width?: string;
-    marginTop?: 0 | 2 | 4 | 6 | 8 | 10;
+    /** Direction of the separator line */orientation?: "horizontal" | "vertical"; /** Color of the separator line */
+    color?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Thickness of the separator line */
+    thickness?: string; /** Width of the separator */
+    width?: string; /** Space above the separator */
+    marginTop?: 0 | 2 | 4 | 6 | 8 | 10; /** Space below the separator */
     marginBottom?: 0 | 2 | 4 | 6 | 8 | 10;
   };
 }
+/** Portal node for the ShopWidget built-in widget. */
 interface ShopWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "ShopWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    title?: string;
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    showSearch?: boolean;
-    showSort?: boolean;
-    columns?: 2 | 3 | 4 | 5 | 6;
+    /** Enable the heading shown above the grid */titleEnabled?: boolean; /** Heading text shown above the grid */
+    title?: string; /** Color of the heading text */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Display the search input above the grid */
+    showSearch?: boolean; /** Display the sort menu above the grid */
+    showSort?: boolean; /** Max columns at the largest breakpoint. Narrow widgets show 2 columns; wider containers scale up smoothly to the chosen maximum. */
+    columns?: 2 | 3 | 4 | 5 | 6; /** Container background */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    cardBackground?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    cardTextColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    useDataSource?: boolean;
-    pageSize?: number;
+    }; /** Inner spacing around the grid */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Container corner radius */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Override the card background color. Leave unset to use the theme's card color. */
+    cardBackground?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Override title + price color inside each card. Leave unset to use the theme's foreground color. */
+    cardTextColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Off shows all products from the catalog. On replaces the catalog with a data source — disables search and sort. */
+    useDataSource?: boolean; /** Up to 10 acts as a hard cap. Above 10 the grid switches to infinite scroll (products load in batches of 10 as you scroll). */
+    pageSize?: number; /** Products rendered in the shop grid, usually supplied by a data source. */
     products?: JsonValue;
   };
 }
+/** Portal node for the SpacerWidget built-in widget. */
 interface SpacerWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "SpacerWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    customHeight?: string;
+    /** Height of the spacer */customHeight?: string;
   };
 }
+/** Portal node for the TableWidget built-in widget. */
 interface TableWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "TableWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    titleText?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+    /** Enable the title displayed above the table */titleEnabled?: boolean; /** Title text displayed above the table */
+    titleText?: string; /** Font size for the widget title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the widget title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Background for the table container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    alternatingColorEnabled?: boolean;
-    headerBackgroundColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    headerTextColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    filterEnabled?: boolean;
-    sortingEnabled?: boolean;
-    paginationEnabled?: boolean;
-    maxRowsPerPage?: number;
-    data?: JsonValue;
+    }; /** Enable alternating colors for table rows */
+    alternatingColorEnabled?: boolean; /** Background color for the table header */
+    headerBackgroundColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Default text color for table content */
+    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Text color for the table header */
+    headerTextColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Padding around the table container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Border radius for the table container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Show global search and column filters */
+    filterEnabled?: boolean; /** Allow sorting by clicking column headers */
+    sortingEnabled?: boolean; /** Split data into pages */
+    paginationEnabled?: boolean; /** Maximum number of rows to display per page */
+    maxRowsPerPage?: number; /** Rows rendered by the table, usually supplied by a data source. */
+    data?: JsonValue; /** Column definitions used to label and read values from each row. */
     columns?: JsonValue;
   };
 }
+/** Portal node for the TextWidget built-in widget. */
 interface TextWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "TextWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    title?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleFontWeight?: "normal" | "medium" | "semibold" | "bold";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    titleAlignment?: "left" | "center" | "right";
-    description?: string;
-    descriptionFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    descriptionFontWeight?: "normal" | "medium" | "semibold" | "bold";
-    descriptionColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    descriptionAlignment?: "left" | "center" | "right";
+    /** Enable the title displayed above the text */titleEnabled?: boolean; /** The title */
+    title?: string; /** Font size for the title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Font weight for the title */
+    titleFontWeight?: "normal" | "medium" | "semibold" | "bold"; /** The color of the title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Text alignment for the title */
+    titleAlignment?: "left" | "center" | "right"; /** The text message */
+    description?: string; /** Font size for the text */
+    descriptionFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Font weight for the text */
+    descriptionFontWeight?: "normal" | "medium" | "semibold" | "bold"; /** The color of the text */
+    descriptionColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Text alignment for the description */
+    descriptionAlignment?: "left" | "center" | "right"; /** Background for the text container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
+    }; /** The padding of the text container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** The border radius of the text container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** The border width of the text container */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** The border color of the text container */
     borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
   };
 }
+/** Portal node for the ToDoWidget built-in widget. */
 interface ToDoWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "ToDoWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    titleEnabled?: boolean;
-    titleText?: string;
-    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs";
-    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
+    /** Enable the title displayed above the todo list */titleEnabled?: boolean; /** Title text displayed above the todo list */
+    titleText?: string; /** Font size for the widget title */
+    titleFontSize?: "2xl" | "xl" | "lg" | "md" | "sm" | "xs"; /** Color for the widget title */
+    titleColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Background for the widget container */
     background?: string | {
       type: "solid" | "image";
       color?: ColorOption;
       resource?: string | null | JsonObject;
-    };
-    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    maxItems?: number;
-    padding?: 0 | 2 | 4 | 6 | 8 | 10;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
+    }; /** Default text color for todo items */
+    textColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Color used for count badge and icon */
+    accentColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Maximum number of todo items to display */
+    maxItems?: number; /** Padding around the widget container */
+    padding?: 0 | 2 | 4 | 6 | 8 | 10; /** Border radius for the widget container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
     borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
   };
 }
+/** Portal node for the VideoWidget built-in widget. */
 interface VideoWidgetNode extends PortalWidgetNodeBase {
+  /** Registered built-in widget type. */
   readonly type: "VideoWidget";
+  /** Properties accepted by this widget. */
   readonly props: {
-    resource?: string | null | JsonObject;
-    useCustomUrl?: boolean;
-    src?: string;
-    poster?: string;
-    displayMode?: "inline" | "card";
-    title?: string;
-    tagline?: string;
-    eyebrow?: string;
-    tag?: string;
-    duration?: string;
-    author?: string;
-    date?: string;
-    editorialFrame?: boolean;
-    frameColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    showFullscreenPill?: boolean;
-    primaryCtaText?: string;
-    primaryCtaLink?: string;
-    secondaryCtaText?: string;
-    secondaryCtaLink?: string;
-    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
-    borderWidth?: "none" | "thin" | "medium" | "thick";
-    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent";
-    verticalSizing?: "auto" | "fixed";
-    fixedHeight?: string;
-    displayFit?: "cover" | "contain";
-    focusPoint?: string;
-    controls?: boolean;
-    autoplay?: boolean;
-    loop?: boolean;
+    /** Browse and select a video */resource?: string | null | JsonObject; /** Enter a custom video URL instead of selecting media. */
+    useCustomUrl?: boolean; /** Direct video URL for inline mode. Card mode supports YouTube, Vimeo, and direct video URLs. */
+    src?: string; /** Thumbnail shown before play. Card mode can auto-derive YouTube thumbnails; add a poster for Vimeo URLs. */
+    poster?: string; /** Inline: native player embedded in the page. Card: premium thumbnail that opens a modal. */
+    displayMode?: "inline" | "card"; /** Headline on the card thumbnail (card mode only). */
+    title?: string; /** Short body line under the title. */
+    tagline?: string; /** Small label above the card (e.g. 'Training · Fluid Academy'). */
+    eyebrow?: string; /** Optional pill label. */
+    tag?: string; /** Runtime (e.g. '4:52' or '1:09:30'). Shown as a chip. */
+    duration?: string; /** Meta line author. */
+    author?: string; /** Meta line date (e.g. 'Apr 12'). */
+    date?: string; /** Premium dark canvas with layered shadow and dual gradient overlays. */
+    editorialFrame?: boolean; /** Surface color for the card and modal. */
+    frameColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** Show the 'Full screen' hover hint on the card. */
+    showFullscreenPill?: boolean; /** Primary button in the modal footer (optional). */
+    primaryCtaText?: string; /** URL for the primary CTA. */
+    primaryCtaLink?: string; /** Secondary (ghost) button in the modal footer (optional). */
+    secondaryCtaText?: string; /** URL for the secondary CTA. */
+    secondaryCtaLink?: string; /** Border radius for the video container */
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full"; /** Border width for the widget */
+    borderWidth?: "none" | "thin" | "medium" | "thick"; /** Border color for the widget */
+    borderColor?: "background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "border" | "destructive" | "transparent"; /** How the video height is determined (inline mode only) */
+    verticalSizing?: "auto" | "fixed"; /** Fixed height of the video container */
+    fixedHeight?: string; /** How the video fills its container */
+    displayFit?: "cover" | "contain"; /** The focal point of the video within its container */
+    focusPoint?: string; /** Display video playback controls (inline mode only — card mode always shows controls in the modal). */
+    controls?: boolean; /** Automatically start playing the video */
+    autoplay?: boolean; /** Repeat the video when it ends */
+    loop?: boolean; /** Start with audio muted */
     muted?: boolean;
   };
 }
+/** Any registered built-in portal widget node. */
 type PortalBuiltinWidgetNode = AlertWidgetNode | BulletListWidgetNode | CalendarWidgetNode | CardWidgetNode | CarouselWidgetNode | CatchUpWidgetNode | ChartWidgetNode | ContainerWidgetNode | EmbedWidgetNode | ImageWidgetNode | LayoutWidgetNode | LinkWidgetNode | ListWidgetNode | MySiteWidgetNode | NestedWidgetNode | PointsWidgetNode | QuickLinksWidgetNode | QuickShareWidgetNode | RecentActivityWidgetNode | SeparatorWidgetNode | ShopWidgetNode | SpacerWidgetNode | TableWidgetNode | TextWidgetNode | ToDoWidgetNode | VideoWidgetNode;
+/** Portal node supplied by a company or Droplet widget package. */
+/** Exact consent grant for third-party widget network access. */
 interface PortalNetworkAccessGrant {
+  /** Canonical package identifier approved for network access. */
   readonly packageId: string;
+  /** Exact package version approved for network access. */
   readonly packageVersion: string;
+  /** Exact network capability contract version approved. */
   readonly capabilityVersion: string;
 }
 interface PortalThirdPartyWidgetNode extends PortalWidgetNodeBase {
+  /** Namespaced owner, package key, and widget name. */
   readonly type: `company.${string}.${string}` | `droplet.${string}.${string}`;
+  /** Package-defined serializable widget properties. */
   readonly props: JsonObject;
+  /** Placement-specific consent grants for third-party capabilities. */
   readonly capabilityGrants?: {
     readonly networkAccess?: PortalNetworkAccessGrant;
   };
 }
+/** Any built-in or third-party portal widget node. */
 type PortalWidgetNode = PortalBuiltinWidgetNode | PortalThirdPartyWidgetNode;
+/** Portal screen resource. */
 interface PortalScreen {
+  /** Versioned schema URL. */
   readonly $schema?: string;
+  /** Human-readable screen name. */
   readonly name: string;
+  /** Zero or one root widget nodes. */
   readonly component_tree: PortalWidgetNode[];
 }
+/** Base and foreground OKLCH colors for a semantic theme role. */
 interface PortalThemeColor {
+  /** Base OKLCH color. */
   readonly base: {
     readonly l: number;
     readonly c: number;
     readonly h: number;
   };
+  /** Foreground OKLCH color. */
   readonly foreground: {
     readonly l: number;
     readonly c: number;
     readonly h: number;
   };
 }
+/** Complete structured portal theme configuration. */
 interface PortalThemeConfig {
+  /** Stable theme configuration identifier. */
   readonly id: string;
+  /** Human-readable configuration name. */
   readonly name: string;
+  /** Required light-mode semantic colors. */
   readonly light: Readonly<Record<"background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "destructive", PortalThemeColor>>;
+  /** Optional dark-mode semantic color overrides. */
   readonly dark: Readonly<Partial<Record<"background" | "foreground" | "primary" | "secondary" | "accent" | "muted" | "destructive", {
     readonly base?: PortalThemeColor["base"];
     readonly foreground?: PortalThemeColor["foreground"];
   }>>>;
+  /** Named font-size tokens. */
   readonly fontSizes: Readonly<Record<"extraSmall" | "small" | "regular" | "large" | "extraLarge" | "giant", string>>;
+  /** Heading and body font families. */
   readonly fontFamilies: Readonly<Record<"header" | "body", string>>;
+  /** Base spacing token. */
   readonly spacing: string;
+  /** Named border-radius tokens. */
   readonly radii: Readonly<Record<"small" | "medium" | "large" | "extraLarge", string>>;
+  /** Whether Fluid brand colors update semantic colors. */
   readonly syncWithBrandColors?: boolean;
 }
+/** Portal theme resource. */
 interface PortalTheme {
+  /** Versioned schema URL. */
   readonly $schema?: string;
+  /** Human-readable theme name. */
   readonly name: string;
+  /** Complete structured theme configuration. */
   readonly config: PortalThemeConfig;
+  /** Whether the theme is active. */
   readonly active: boolean;
 }
+/** Navigation entry that can contain nested entries. */
 interface PortalNavigationItem {
+  /** Remote item identifier, when assigned. */
   readonly id?: number;
+  /** Display icon identifier. */
   readonly icon: string | null;
+  /** Display label. */
   readonly label: string | null;
+  /** Referenced screen resource slug. */
   readonly screen: string | null;
+  /** Stable navigation item slug. */
   readonly slug: string | null;
+  /** Fluid navigation source classification. */
   readonly source: string;
+  /** Item ordering position. */
   readonly position: number | null;
+  /** Parent item identifier, or null at the root. */
   readonly parent_id: number | null;
+  /** Nested navigation entries. */
   readonly children: PortalNavigationItem[];
 }
+/** Web or mobile navigation resource. */
 interface PortalNavigation {
+  /** Versioned schema URL. */
   readonly $schema?: string;
+  /** Human-readable navigation name. */
   readonly name: string;
+  /** Platform that uses this navigation. */
   readonly platform: "web" | "mobile";
+  /** Ordered top-level navigation entries. */
   readonly navigation_items: PortalNavigationItem[];
 }
+/** Portal member profile resource. */
 interface PortalProfile {
+  /** Versioned schema URL. */
   readonly $schema?: string;
+  /** Human-readable profile name. */
   readonly name: string;
+  /** Whether this is the fallback profile. */
   readonly default: boolean;
+  /** Web navigation resource slug. */
   readonly navigation: string | null;
+  /** Mobile navigation resource slug. */
   readonly mobile_navigation: string | null;
+  /** Theme resource slugs available to this profile. */
   readonly themes: string[];
+  /** Member attributes used for profile matching. */
   readonly permissions: {
     readonly ranks: number[];
     readonly roles: string[];