docs: clarify widget serialize vs options.serialize in types and JSDoc (#9105)

## Summary

Clarifies the two distinct `serialize` properties on widgets via
improved TypeScript types and JSDoc:

- **`IWidgetOptions.serialize`** — controls whether the widget value is
included in the **API prompt** sent for execution
- **`IBaseWidget.serialize`** — controls whether the widget value is
persisted in the **workflow JSON** (`widgets_values`)

These two properties are easily confused. This PR adds cross-linking
JSDoc, explicit `@default` tags, and a clarifying comment at the check
site in `executionUtil.ts`.

## Changes

| File | Change |
|------|--------|
| `src/lib/litegraph/src/types/widgets.ts` | Add `serialize?: boolean`
to `IWidgetOptions` with JSDoc; expand JSDoc on `IBaseWidget.serialize`
|
| `src/utils/executionUtil.ts` | Clarifying comment at the
`widget.options.serialize` check |
| `src/types/metadataTypes.ts` | Connect `ComfyMetadataTags` enum values
to their corresponding serialize properties |

## Related

- Companion doc: #9102 (`WIDGET_SERIALIZATION.md`)
- Issue: #1757

## Verification

- `vue-tsc --noEmit` passes clean
- `eslint` passes clean on all 3 files
- No runtime changes — JSDoc and types only

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-9105-docs-clarify-widget-serialize-vs-options-serialize-in-types-and-JSDoc-3106d73d36508155b618ee56cf18f969)
by [Unito](https://www.unito.io)

src/lib/litegraph/src/types/widgets.ts

@@ -47,6 +47,19 @@ export interface IWidgetOptions<TValues = unknown> {
   /** Used as a temporary override for determining the asset type in vue mode*/
   nodeType?: string
 
+  /**
+   * Whether the widget value should be included in the API prompt sent to
+   * the backend for execution. Checked by {@link executionUtil} when
+   * building the prompt payload.
+   *
+   * This is distinct from {@link IBaseWidget.serialize}, which controls
+   * whether the value is persisted in the workflow JSON file.
+   *
+   * @default true
+   * @see IBaseWidget.serialize — workflow persistence
+   */
+  serialize?: boolean
+
   values?: TValues
   /** Optional function to format values for display (e.g., hash → human-readable name) */
   getOptionLabel?: (value?: string | null) => string
@@ -349,8 +362,15 @@ export interface IBaseWidget<
   vueTrack?: () => void
 
   /**
-   * Whether the widget value should be serialized on node serialization.
+   * Whether the widget value is persisted in the workflow JSON
+   * (`widgets_values`). Checked by {@link LGraphNode.serialize} and
+   * {@link LGraphNode.configure}.
+   *
+   * This is distinct from {@link IWidgetOptions.serialize}, which controls
+   * whether the value is included in the API prompt sent for execution.
+   *
    * @default true
+   * @see IWidgetOptions.serialize — API prompt inclusion
    */
   serialize?: boolean
 

src/utils/executionUtil.ts

@@ -92,7 +92,9 @@ export const graphToPrompt = async (
     const inputs: ComfyApiWorkflow[string]['inputs'] = {}
     const { widgets } = node
 
-    // Store all widget values
+    // Store all widget values in the API prompt.
+    // Note: widget.options.serialize controls prompt inclusion (checked here).
+    // widget.serialize controls workflow persistence (checked by LGraphNode).
     if (widgets) {
       for (const [i, widget] of widgets.entries()) {
         if (!widget.name || widget.options?.serialize === false) continue