@codefluss/base-types 0.0.2-alpha.1 → 0.0.2-alpha.2

package/src/plugin-system.ts

@@ -4,454 +4,1030 @@
  * Core types for the headless plugin architecture.
  * These types define the contract between plugins and the Context Panel UI.
  *
+ * The plugin system uses a **headless** approach: plugins declare metadata
+ * (properties, capabilities, UI config) and the host application renders
+ * appropriate controls automatically in the Context Panel.
+ *
+ * @see {@link PluginConfig} — Top-level plugin definition
+ * @see {@link PropertyDefinition} — How plugins declare editable properties
+ * @see {@link PluginCapabilities} — How plugins declare structural behavior
+ *
  * @package @codefluss/base-types
  * @version 1.0.0
  */
 
-import type { ComponentType } from "react";
-import type { PluginDesignSystem, PluginUtils } from "./dependencies";
+import type { ComponentType } from 'react';
+import type { PluginDesignSystem, PluginUtils } from './dependencies';
 
 /**
- * Property control type
- * Defines which UI control to render in Context Panel
+ * Property control type — determines which UI widget the Context Panel
+ * renders for a given property.
+ *
+ * Each value maps to a specific editor control component.
+ * The control's behavior is further configured via the corresponding
+ * field in {@link PropertyUIConfig}.
+ *
+ * @see {@link PropertyUIConfig} for per-control configuration
+ *
+ * @example
+ * ```typescript
+ * // A slider control for font size
+ * const property: PropertyDefinition = {
+ *   key: 'style.fontSize',
+ *   type: 'range',
+ *   label: 'Font Size',
+ *   default: 16,
+ *   ui: {
+ *     control: 'slider',
+ *     slider: { min: 8, max: 72, step: 1, unit: 'px' },
+ *   },
+ * };
+ * ```
  */
 export type PropertyControlType =
-  | "input"
-  | "slider"
-  | "select"
-  | "color-picker"
-  | "toggle"
-  | "textarea"
-  | "number-input"
-  | "number-with-unit" // Container-specific
-  | "box-model"
-  | "spacing" // Combined margin + padding control
-  | "spacing-combined" // Combined margin + padding control (UI variant)
-  | "grid" // Container-specific
-  | "typography-toolbar"
-  | "gradient-editor"
-  | "border-editor"
-  | "font-preset-select" // Design System font presets
-  | "color-preset-select" // Design System color presets
-  | "text-align-toggle" // Horizontal text alignment toggle buttons
-  | "vertical-align-toggle"; // Vertical alignment toggle buttons (align-self)
-
-/**
- * Property type
- * Semantic type of the property value
+  | 'input'
+  | 'slider'
+  | 'select'
+  | 'color-picker'
+  | 'toggle'
+  | 'textarea'
+  | 'number-input'
+  | 'number-with-unit' // Container-specific
+  | 'box-model'
+  | 'spacing' // Combined margin + padding control
+  | 'spacing-combined' // Combined margin + padding control (UI variant)
+  | 'grid' // Container-specific
+  | 'typography-toolbar'
+  | 'gradient-editor'
+  | 'border-editor'
+  | 'font-preset-select' // Design System font presets
+  | 'color-preset-select' // Design System color presets
+  | 'text-align-toggle' // Horizontal text alignment toggle buttons
+  | 'vertical-align-toggle'; // Vertical alignment toggle buttons (align-self)
+
+/**
+ * Semantic type of a property value.
+ *
+ * While {@link PropertyControlType} determines the *UI widget*,
+ * `PropertyType` describes the *semantic meaning* of the stored value.
+ * A single `PropertyType` may be rendered by different controls depending
+ * on the plugin's UI configuration.
+ *
+ * @see {@link PropertyControlType} for the UI control counterpart
+ * @see {@link PropertyDefinition.type}
  */
 export type PropertyType =
-  | "text"
-  | "number"
-  | "range"
-  | "select"
-  | "color"
-  | "toggle"
-  | "multiLangText"
-  | "boxModel"
-  | "box-model"
-  | "spacing" // Combined margin + padding
-  | "spacing-combined" // Combined margin + padding (UI variant)
-  | "grid"
-  | "toolbar"
-  | "gradient"
-  | "border";
+  | 'text'
+  | 'number'
+  | 'range'
+  | 'select'
+  | 'color'
+  | 'toggle'
+  | 'multiLangText'
+  | 'boxModel'
+  | 'box-model'
+  | 'spacing' // Combined margin + padding
+  | 'spacing-combined' // Combined margin + padding (UI variant)
+  | 'grid'
+  | 'toolbar'
+  | 'gradient'
+  | 'border';
 
 /**
- * Property category for organization
+ * Organizational category for properties in the Context Panel.
+ *
+ * Properties are grouped into collapsible sections by category,
+ * providing a consistent editing experience across all plugins.
+ *
+ * - `'content'` — Text, media, and data properties (shown first)
+ * - `'style'` — Visual appearance: colors, typography, backgrounds
+ * - `'layout'` — Spacing, positioning, grid/flexbox settings
+ * - `'advanced'` — CSS classes, ARIA labels, HTML tags, z-index
+ *
+ * @see {@link PropertyDefinition.category}
  */
-export type PropertyCategory = "content" | "style" | "layout" | "advanced";
+export type PropertyCategory = 'content' | 'style' | 'layout' | 'advanced';
 
 /**
- * Slider control configuration
+ * Configuration for slider UI controls.
+ *
+ * @see {@link PropertyUIConfig.slider}
+ *
+ * @example
+ * ```typescript
+ * const sliderConfig: SliderConfig = {
+ *   min: 0,
+ *   max: 100,
+ *   step: 1,
+ *   showValue: true,
+ *   unit: 'px',
+ * };
+ * ```
  */
 export interface SliderConfig {
+  /** Minimum allowed value */
   min: number;
+
+  /** Maximum allowed value */
   max: number;
+
+  /** Increment step between values */
   step: number;
+
+  /**
+   * Whether to display the current numeric value next to the slider
+   * @default false
+   */
   showValue?: boolean;
+
+  /**
+   * Unit label displayed after the value (e.g., `'px'`, `'%'`, `'em'`)
+   * @default undefined
+   */
   unit?: string; // 'px', '%', 'em', etc.
+
+  /**
+   * Discrete labeled positions on the slider track
+   * @default undefined
+   */
   marks?: Array<{ value: number; label: string }>;
 }
 
 /**
- * Number input control configuration
+ * Configuration for numeric input controls.
+ *
+ * All fields are optional — unset fields inherit sensible browser defaults.
+ *
+ * @see {@link PropertyUIConfig.number}
+ *
+ * @example
+ * ```typescript
+ * const numberConfig: NumberConfig = {
+ *   min: 0,
+ *   max: 9999,
+ *   step: 1,
+ *   unit: 'px',
+ * };
+ * ```
  */
 export interface NumberConfig {
+  /** Minimum allowed value */
   min?: number;
+
+  /** Maximum allowed value */
   max?: number;
+
+  /** Increment step */
   step?: number;
+
+  /**
+   * Unit label displayed after the value (e.g., `'px'`, `'%'`, `'em'`)
+   * @default undefined
+   */
   unit?: string; // 'px', '%', 'em', etc.
 }
 
 /**
- * Number with unit control configuration (Container-specific)
+ * Configuration for number-with-unit controls (primarily used by containers).
+ *
+ * Unlike {@link NumberConfig}, this control lets the user **switch between
+ * multiple CSS units** via a dropdown alongside the numeric input.
+ *
+ * @see {@link PropertyUIConfig.numberWithUnit}
+ *
+ * @example
+ * ```typescript
+ * // Container max-width control
+ * const config: NumberWithUnitConfig = {
+ *   min: 0,
+ *   max: 9999,
+ *   step: 10,
+ *   units: ['px', '%', 'rem', 'ch', 'vw', 'auto'],
+ *   defaultUnit: 'px',
+ *   allowEmpty: true,
+ * };
+ * ```
  */
 export interface NumberWithUnitConfig {
+  /** Minimum allowed value */
   min?: number;
+
+  /** Maximum allowed value */
   max?: number;
+
+  /** Increment step */
   step?: number;
+
+  /**
+   * Available CSS units the user can select
+   * @default undefined
+   * @example ['px', '%', 'em', 'rem', 'vw', 'vh']
+   */
   units?: string[]; // ['px', '%', 'em', 'rem', 'vw', 'vh']
+
+  /**
+   * Initially selected unit
+   * @default undefined
+   */
   defaultUnit?: string;
+
+  /**
+   * Whether the field accepts empty / null values.
+   * Typically `true` for container properties like `minHeight` or `maxWidth`
+   * where "auto" or no value is meaningful.
+   * @default undefined
+   */
   allowEmpty?: boolean; // Allow empty/null values (container-specific)
 }
 
 /**
- * Select control configuration
+ * Configuration for select / dropdown controls.
+ *
+ * @see {@link PropertyUIConfig.select}
+ *
+ * @example
+ * ```typescript
+ * const selectConfig: SelectConfig = {
+ *   options: [
+ *     { value: 'flexbox', label: 'Flexbox' },
+ *     { value: 'grid', label: 'Grid' },
+ *   ],
+ *   searchable: false,
+ * };
+ * ```
  */
 export interface SelectConfig {
+  /** Available options for the dropdown */
   options: Array<{ value: string; label: string; icon?: ComponentType }>;
+
+  /**
+   * Enable type-ahead search filtering for long option lists
+   * @default false
+   */
   searchable?: boolean;
 }
 
 /**
- * Text input control configuration
+ * Configuration for single-line text input controls.
+ *
+ * @see {@link PropertyUIConfig.input}
  */
 export interface InputConfig {
+  /**
+   * Placeholder text shown when the input is empty
+   * @example 'e.g., custom-class my-style'
+   */
   placeholder?: string;
+
+  /** Regex pattern for client-side validation */
   pattern?: RegExp;
+
+  /** Message shown when validation fails */
   validationMessage?: string;
 }
 
 /**
- * Color picker control configuration
+ * Configuration for color picker controls.
+ *
+ * @see {@link PropertyUIConfig.colorPicker}
+ *
+ * @example
+ * ```typescript
+ * const colorConfig: ColorPickerConfig = {
+ *   format: 'hex',
+ *   alpha: true,
+ *   presets: ['#ff0000', '#00ff00', '#0000ff'],
+ * };
+ * ```
  */
 export interface ColorPickerConfig {
-  format?: "hex" | "rgb" | "hsl";
+  /**
+   * Output color format
+   * @default 'hex'
+   */
+  format?: 'hex' | 'rgb' | 'hsl';
+
+  /**
+   * Whether to allow alpha (transparency) channel
+   * @default false
+   */
   alpha?: boolean;
+
+  /** Preset color swatches shown for quick selection */
   presets?: string[];
 }
 
 /**
- * Textarea control configuration
+ * Configuration for multi-line textarea controls.
+ *
+ * @see {@link PropertyUIConfig.textarea}
+ *
+ * @example
+ * ```typescript
+ * const textareaConfig: TextareaConfig = {
+ *   rows: 1,
+ *   autoResize: true,
+ * };
+ * ```
  */
 export interface TextareaConfig {
+  /**
+   * Initial number of visible text rows
+   * @default 3
+   */
   rows?: number;
+
+  /**
+   * Automatically grow the textarea height to fit content
+   * @default false
+   */
   autoResize?: boolean;
+
+  /** Placeholder text shown when empty */
   placeholder?: string;
 }
 
 /**
- * Box model control configuration
+ * Configuration for box-model (margin/padding) controls.
+ *
+ * Renders a four-sided input (top, right, bottom, left) with
+ * optional linked-sides mode.
+ *
+ * @see {@link PropertyUIConfig.boxModel}
+ * @see {@link SpacingConfig} for the combined margin + padding variant
  */
 export interface BoxModelConfig {
+  /** Minimum value per side */
   min?: number;
+
+  /** Maximum value per side */
   max?: number;
+
+  /**
+   * CSS unit for all sides
+   * @default 'px'
+   */
   unit?: string;
+
+  /**
+   * Whether all four sides are linked (same value) by default
+   * @default false
+   */
   linkedByDefault?: boolean;
 }
 
 /**
- * Spacing control configuration (combined margin + padding)
+ * Configuration for the combined spacing control (margin + padding in one UI).
+ *
+ * @see {@link PropertyUIConfig.spacing}
+ * @see {@link BoxModelConfig} for individual margin or padding controls
  */
 export interface SpacingConfig {
+  /** Minimum padding value per side */
   paddingMin?: number;
+
+  /** Maximum padding value per side */
   paddingMax?: number;
+
+  /** Minimum margin value per side (can be negative) */
   marginMin?: number;
+
+  /** Maximum margin value per side */
   marginMax?: number;
+
+  /**
+   * CSS unit for all values
+   * @default 'px'
+   */
   unit?: string;
 }
 
 /**
- * Typography toolbar control configuration
+ * Configuration for the typography toolbar control.
+ *
+ * Toggles visibility of individual formatting buttons (bold, italic, etc.).
+ *
+ * @see {@link PropertyUIConfig.typographyToolbar}
  */
 export interface TypographyToolbarConfig {
+  /** Show bold toggle button @default true */
   showBold?: boolean;
+
+  /** Show italic toggle button @default true */
   showItalic?: boolean;
+
+  /** Show underline toggle button @default true */
   showUnderline?: boolean;
+
+  /** Show text alignment buttons @default true */
   showAlignment?: boolean;
+
+  /** Show font size control @default true */
   showFontSize?: boolean;
+
+  /** Show color picker @default true */
   showColor?: boolean;
 }
 
 /**
- * Gradient editor control configuration
+ * Configuration for gradient editor controls.
+ *
+ * @see {@link PropertyUIConfig.gradientEditor}
+ *
+ * @example
+ * ```typescript
+ * const gradientConfig: GradientEditorConfig = {
+ *   allowLinear: true,
+ *   allowRadial: true,
+ *   maxStops: 5,
+ *   colorFormat: 'hex',
+ * };
+ * ```
  */
 export interface GradientEditorConfig {
+  /**
+   * Allow linear gradient type
+   * @default true
+   */
   allowLinear?: boolean;
+
+  /**
+   * Allow radial gradient type
+   * @default true
+   */
   allowRadial?: boolean;
+
+  /**
+   * Maximum number of color stops
+   * @default undefined (unlimited)
+   */
   maxStops?: number;
-  colorFormat?: "hex" | "rgb" | "hsl";
+
+  /**
+   * Output color format for gradient stops
+   * @default 'hex'
+   */
+  colorFormat?: 'hex' | 'rgb' | 'hsl';
 }
 
 /**
- * Border editor control configuration
+ * Configuration for border editor controls.
+ *
+ * @see {@link PropertyUIConfig.borderEditor}
  */
 export interface BorderEditorConfig {
+  /**
+   * Allow editing each border side independently
+   * @default false
+   */
   allowIndividualSides?: boolean;
+
+  /**
+   * Show border-radius control
+   * @default true
+   */
   allowRadius?: boolean;
+
+  /**
+   * Maximum border width in pixels
+   * @default 20
+   */
   maxWidth?: number;
 }
 
 /**
- * Font preset select control configuration
- * Shows typography presets from Design System
+ * Configuration for the font preset select control.
+ *
+ * Displays typography presets from the Design System as a dropdown.
+ * The presets are sourced from {@link PluginDesignSystem.fonts}.
+ *
+ * @see {@link PropertyUIConfig.fontPresetSelect}
  */
 export interface FontPresetSelectConfig {
-  /** Filter fonts by category (e.g., "heading", "body") */
+  /**
+   * Filter fonts by category (e.g., `"heading"`, `"body"`)
+   * @default undefined (show all fonts)
+   */
   category?: string;
-  /** Placeholder text */
+
+  /** Placeholder text when no preset is selected */
   placeholder?: string;
 }
 
 /**
- * Color preset select control configuration
- * Shows color presets from Design System (no free text)
+ * Configuration for the color preset select control.
+ *
+ * Displays color presets from the Design System as a dropdown with
+ * optional color swatches. Unlike `color-picker`, this control only
+ * allows preset selection — no free-form color input.
+ *
+ * @see {@link PropertyUIConfig.colorPresetSelect}
  */
 export interface ColorPresetSelectConfig {
-  /** Filter colors by category */
+  /**
+   * Filter colors by category
+   * @default undefined (show all colors)
+   */
   category?: string;
-  /** Placeholder text */
+
+  /** Placeholder text when no preset is selected */
   placeholder?: string;
-  /** Show color preview swatch */
+
+  /**
+   * Show a colored swatch preview next to each option
+   * @default true
+   */
   showSwatch?: boolean;
-  /** Allow "None" option for transparent/no color */
+
+  /**
+   * Allow a "None" option for transparent / no color
+   * @default false
+   */
   allowNone?: boolean;
 }
 
 /**
- * Alignment toggle control configuration
- * Icon-based toggle buttons for text-align or align-self
+ * Configuration for icon-based alignment toggle buttons.
+ *
+ * Used for both horizontal text alignment (`text-align-toggle`)
+ * and vertical alignment (`vertical-align-toggle`).
+ *
+ * @see {@link PropertyUIConfig.alignmentToggle}
  */
 export interface AlignmentToggleConfig {
-  /** Include justify option for horizontal alignment */
+  /**
+   * Include "justify" option (horizontal alignment only)
+   * @default false
+   */
   includeJustify?: boolean;
-  /** Include stretch option for vertical alignment */
+
+  /**
+   * Include "stretch" option (vertical alignment only)
+   * @default false
+   */
   includeStretch?: boolean;
-  /** Include auto/inherit option */
+
+  /**
+   * Include "auto" / "inherit" option
+   * @default false
+   */
   includeAuto?: boolean;
 }
 
 /**
- * Display mode configuration
+ * Display and layout configuration for a property control in the Context Panel.
+ *
+ * Controls how and when a property is visible, its layout arrangement,
+ * and conditional visibility based on sibling property values.
+ *
+ * @see {@link PropertyUIConfig.display}
+ *
+ * @example
+ * ```typescript
+ * // Show this property only when layout mode is 'flexbox'
+ * const display: DisplayConfig = {
+ *   layout: 'grid-2',
+ *   condition: {
+ *     when: 'layout.mode',
+ *     equals: 'flexbox',
+ *   },
+ * };
+ * ```
  */
 export interface DisplayConfig {
   /**
-   * Show in tooltip on hover vs always visible in panel
+   * Where this property's control is rendered
+   * @default 'panel'
    */
-  mode?: "tooltip" | "panel" | "both";
+  mode?: 'tooltip' | 'panel' | 'both';
 
   /**
-   * Collapsible section
+   * Whether this property section can be collapsed
+   * @default false
    */
   collapsible?: boolean;
 
   /**
-   * Default collapsed state
+   * Initial collapsed state (only relevant when `collapsible` is `true`)
+   * @default false
    */
   defaultCollapsed?: boolean;
 
   /**
-   * Layout mode for property controls in panel (container-specific)
-   * Determines how controls are arranged (single column, 2-column grid, etc.)
+   * Layout arrangement for controls within the panel section.
+   * - `'single'` — one control per row (default)
+   * - `'grid-2'` — two controls side by side
+   * - `'grid-3'` — three controls per row
+   *
+   * Primarily used by container plugins to create compact property grids.
    */
-  layout?: "grid-2" | "grid-3" | "single" | string;
+  layout?: 'grid-2' | 'grid-3' | 'single' | string;
 
   /**
-   * Conditional visibility based on other property values
-   * @example { when: 'layout.mode', equals: 'flexbox' }
+   * Conditional visibility: show/hide this property based on another
+   * property's current value.
+   *
+   * @example
+   * ```typescript
+   * // Show only when layout mode is 'grid'
+   * { when: 'layout.mode', equals: 'grid' }
+   *
+   * // Show only when border style is NOT 'none'
+   * { when: 'border.style', notEquals: 'none' }
+   * ```
    */
   condition?: {
-    when: string; // Property key to watch
-    equals?: unknown; // Show when equals this value
-    notEquals?: unknown; // Show when not equals this value
+    /** Property key (dot-notation) to observe */
+    when: string;
+    /** Show this control when the observed property equals this value */
+    equals?: unknown;
+    /** Show this control when the observed property does NOT equal this value */
+    notEquals?: unknown;
   };
 }
 
 /**
- * UI configuration for property
- * This is the metadata that tells Context Panel HOW to render
+ * UI configuration metadata for a property.
+ *
+ * Tells the Context Panel **how** to render a property's editor control.
+ * Each property specifies a `control` type and then provides the
+ * matching configuration object (e.g., `slider` config for a `'slider'` control).
+ *
+ * @see {@link PropertyDefinition.ui}
+ * @see {@link PropertyControlType} for the list of available controls
+ *
+ * @example
+ * ```typescript
+ * const ui: PropertyUIConfig = {
+ *   control: 'slider',
+ *   slider: { min: 0, max: 100, step: 1, unit: 'px' },
+ *   display: { layout: 'grid-2' },
+ * };
+ * ```
  */
 export interface PropertyUIConfig {
+  /** Which UI control widget to render in the Context Panel */
   control: PropertyControlType;
+
+  /** Configuration when `control` is `'slider'` @see {@link SliderConfig} */
   slider?: SliderConfig;
+
+  /** Configuration when `control` is `'number-input'` @see {@link NumberConfig} */
   number?: NumberConfig;
+
+  /** Configuration when `control` is `'number-with-unit'` @see {@link NumberWithUnitConfig} */
   numberWithUnit?: NumberWithUnitConfig; // Container-specific
+
+  /** Configuration when `control` is `'select'` @see {@link SelectConfig} */
   select?: SelectConfig;
+
+  /** Configuration when `control` is `'input'` @see {@link InputConfig} */
   input?: InputConfig;
+
+  /** Configuration when `control` is `'textarea'` @see {@link TextareaConfig} */
   textarea?: TextareaConfig;
+
+  /** Configuration when `control` is `'color-picker'` @see {@link ColorPickerConfig} */
   colorPicker?: ColorPickerConfig;
+
+  /** Configuration when `control` is `'box-model'` @see {@link BoxModelConfig} */
   boxModel?: BoxModelConfig;
+
+  /** Configuration when `control` is `'spacing'` or `'spacing-combined'` @see {@link SpacingConfig} */
   spacing?: SpacingConfig; // Combined margin + padding control
+
+  /** Configuration when `control` is `'typography-toolbar'` @see {@link TypographyToolbarConfig} */
   typographyToolbar?: TypographyToolbarConfig;
+
+  /** Configuration when `control` is `'gradient-editor'` @see {@link GradientEditorConfig} */
   gradientEditor?: GradientEditorConfig;
+
+  /** Configuration when `control` is `'border-editor'` @see {@link BorderEditorConfig} */
   borderEditor?: BorderEditorConfig;
+
+  /** Configuration when `control` is `'font-preset-select'` @see {@link FontPresetSelectConfig} */
   fontPresetSelect?: FontPresetSelectConfig; // Design System font presets
+
+  /** Configuration when `control` is `'color-preset-select'` @see {@link ColorPresetSelectConfig} */
   colorPresetSelect?: ColorPresetSelectConfig; // Design System color presets
+
+  /** Configuration when `control` is `'text-align-toggle'` or `'vertical-align-toggle'` @see {@link AlignmentToggleConfig} */
   alignmentToggle?: AlignmentToggleConfig; // Alignment toggle buttons
+
+  /** Layout, visibility, and conditional display settings @see {@link DisplayConfig} */
   display?: DisplayConfig;
 }
 
 /**
- * Property validation rules
+ * Validation rules for a property value.
+ *
+ * Applied client-side when the user edits properties in the Context Panel.
+ *
+ * @see {@link PropertyDefinition.validation}
+ *
+ * @example
+ * ```typescript
+ * const validation: PropertyValidation = {
+ *   min: 0,
+ *   max: 100,
+ *   message: 'Value must be between 0 and 100',
+ * };
+ * ```
  */
 export interface PropertyValidation {
+  /** Regex pattern the string value must match */
   pattern?: RegExp;
+
+  /** Minimum numeric value */
   min?: number;
+
+  /** Maximum numeric value */
   max?: number;
+
+  /** Error message shown when validation fails */
   message?: string;
+
+  /**
+   * Custom validation function.
+   * Return `true` for valid, or a string error message for invalid.
+   */
   custom?: (value: unknown) => boolean | string;
 }
 
 /**
- * Property priority for progressive disclosure
- * Determines visual hierarchy and default visibility in Context Panel
+ * Property priority for progressive disclosure in the Context Panel.
+ *
+ * Controls visual hierarchy and default visibility:
+ * - `'quick'` — Always visible at the top, no accordion (most important properties)
+ * - `'common'` — Collapsible section, expanded by default (frequently used)
+ * - `'advanced'` — Collapsible section, collapsed by default (rarely used)
+ *
+ * @default 'common'
+ * @see {@link PropertyDefinition.priority}
  */
-export type PropertyPriority = "quick" | "common" | "advanced";
+export type PropertyPriority = 'quick' | 'common' | 'advanced';
 
 /**
- * Property definition (headless metadata)
+ * Property definition — the core metadata interface for plugin properties.
+ *
+ * Each plugin declares an array of `PropertyDefinition` objects that describe
+ * its editable properties. The Context Panel reads these definitions and
+ * auto-generates the appropriate editor controls.
+ *
+ * Properties support:
+ * - **Dot-notation keys** for nested data structures (`'style.fontSize'`)
+ * - **Design System integration** via `useGlobal` / `globalKey`
+ * - **Progressive disclosure** via `priority`
+ * - **Conditional visibility** via `ui.display.condition`
+ *
+ * @see {@link PluginConfig.properties}
+ * @see {@link PropertyUIConfig} for UI control configuration
+ * @see {@link PropertyCategory} for organizational grouping
  *
- * This is the core interface that plugins use to define their properties.
- * The Context Panel UI reads this and auto-generates appropriate controls.
+ * @example
+ * ```typescript
+ * const fontSizeProperty: PropertyDefinition = {
+ *   key: 'style.fontSize',
+ *   type: 'range',
+ *   label: 'Font Size',
+ *   default: 16,
+ *   category: 'style',
+ *   priority: 'quick',
+ *   useGlobal: true,
+ *   globalKey: 'fonts.body.size',
+ *   ui: {
+ *     control: 'slider',
+ *     slider: { min: 8, max: 72, step: 1, unit: 'px', showValue: true },
+ *   },
+ * };
+ * ```
  */
 export interface PropertyDefinition {
   /**
-   * Property key (dot notation for nested properties)
-   * @example 'style.fontSize', 'layout.padding.top'
+   * Property key using dot notation for nested data structures.
+   *
+   * This key maps directly to the path in the plugin's `data` object.
+   *
+   * @example 'style.fontSize', 'layout.padding.top', 'contentI18n'
    */
   key: string;
 
   /**
-   * Property type (semantic)
+   * Semantic type of the property value.
+   * @see {@link PropertyType}
    */
   type: PropertyType;
 
   /**
-   * Display label for UI
+   * Human-readable label displayed in the Context Panel
    */
   label: string;
 
   /**
-   * Default value (null = use global default if applicable)
+   * Default value for new plugin instances.
+   * Set to `null` to inherit from the Design System global default
+   * (when `useGlobal` is `true`).
    */
   default: unknown;
 
   /**
-   * Description shown in UI
+   * Help text / tooltip shown below or beside the control in the UI
    */
   description?: string;
 
   /**
-   * Property category for organization
+   * Organizational category — determines which panel section this property
+   * appears in.
+   *
+   * @default 'style'
+   * @see {@link PropertyCategory}
    */
   category?: PropertyCategory;
 
   /**
-   * Whether property is required
+   * Whether a value is required before the element can be saved
+   * @default false
    */
   required?: boolean;
 
   /**
-   * Property priority for progressive disclosure (optional)
-   * - quick: Always visible, no accordion (most important)
-   * - common: Collapsible, default open (frequently used)
-   * - advanced: Collapsible, default closed (rarely used)
-   * Defaults to 'common' if not specified
+   * Controls progressive disclosure and default visibility.
+   *
+   * @default 'common'
+   * @see {@link PropertyPriority}
    */
   priority?: PropertyPriority;
 
   /**
-   * Design System integration
-   * If true, shows "Use Global Default" toggle
+   * Enable Design System integration for this property.
+   * When `true`, the UI shows a "Use Global Default" toggle that
+   * lets the user fall back to the design system value specified
+   * by {@link globalKey}.
+   *
+   * @default false
    */
   useGlobal?: boolean;
 
   /**
-   * Design System key to reference
+   * Dot-notation path into the Design System to read the global default.
+   * Only used when `useGlobal` is `true`.
+   *
    * @example 'fonts.body.size', 'colors.text-primary'
    */
   globalKey?: string;
 
   /**
-   * UI control configuration (headless)
+   * UI control configuration — tells the Context Panel which widget
+   * to render and how to configure it.
+   *
+   * @see {@link PropertyUIConfig}
    */
   ui?: PropertyUIConfig;
 
   /**
-   * Validation rules
+   * Client-side validation rules applied when the user edits this property.
+   * @see {@link PropertyValidation}
    */
   validation?: PropertyValidation;
 }
 
 /**
- * Plugin metadata
+ * Optional metadata about a plugin, shown in plugin listings and documentation.
+ *
+ * @see {@link PluginConfig.meta}
+ *
+ * @example
+ * ```typescript
+ * const meta: PluginMeta = {
+ *   description: 'Semantic heading component (h1-h6) for page structure and SEO',
+ *   tags: ['heading', 'h1', 'title', 'semantic', 'seo'],
+ *   thumbnail: '/plugins/base-heading/thumbnail.png',
+ *   documentation: 'https://docs.codefluss.com/plugins/base-heading',
+ * };
+ * ```
  */
 export interface PluginMeta {
+  /** Short description of what the plugin does */
   description?: string;
+
+  /** Search / filter tags for plugin discovery in the editor toolbar */
   tags?: string[];
+
+  /** Path or URL to a thumbnail image for the plugin browser */
   thumbnail?: string;
+
+  /** URL to external documentation */
   documentation?: string;
 }
 
 /**
- * Plugin Capabilities - PLUGIN-DRIVEN ARCHITECTURE
+ * Plugin capabilities — declares **what** a plugin can do structurally.
+ *
+ * This is the core of the **plugin-driven architecture**: each plugin
+ * declares its own capabilities (container vs leaf, allowed children, etc.)
+ * and the application reads these to determine valid operations (drag-drop
+ * constraints, nesting rules, toolbar options).
+ *
+ * @see {@link PluginConfig.capabilities}
+ *
+ * @example
+ * ```typescript
+ * // Container plugin (e.g., base-container)
+ * const containerCaps: PluginCapabilities = {
+ *   supportsChildren: true,
+ *   isRootComponent: true,
+ *   requiresParent: false,
+ *   childrenType: 'nested',
+ *   allowedChildPlugins: [],   // any child allowed
+ *   maxChildren: null,         // unlimited
+ *   minChildren: 0,
+ * };
  *
- * Declares what the plugin can do and how it should be handled by the app.
- * This is the core of the plugin-driven architecture:
- * The plugin ITSELF defines its capabilities, not the app.
+ * // Leaf plugin (e.g., base-heading)
+ * const headingCaps: PluginCapabilities = {
+ *   supportsChildren: false,
+ *   isRootComponent: false,
+ *   requiresParent: true,
+ *   childrenType: null,
+ *   allowedChildPlugins: [],
+ *   maxChildren: null,
+ *   minChildren: 0,
+ * };
+ * ```
  */
 export interface PluginCapabilities {
   /**
-   * Can this plugin contain child components?
-   * true = container/layout component
-   * false = leaf component (text, image, button, etc.)
+   * Whether this plugin can contain child components.
+   *
+   * - `true` — container/layout component (e.g., `base-container`, `form-container`)
+   * - `false` — leaf component (e.g., `base-heading`, `base-image`, `base-button`)
    */
   supportsChildren: boolean;
 
   /**
-   * Is this a root component?
-   * true = can be placed at canvas/section level (containers, sections)
-   * false = must be inside another component (text, buttons, images)
+   * Whether this plugin can be placed at the canvas / section root level.
+   *
+   * - `true` — can be placed directly on the canvas (containers, sections)
+   * - `false` — must be inside another component (text, buttons, images)
    */
   isRootComponent: boolean;
 
   /**
-   * Does this plugin require a parent container?
-   * true = cannot exist at top level, must be inside a container
-   * false = can be placed directly on canvas
+   * Whether this plugin must be nested inside a parent container.
    *
-   * @example Text component: requiresParent = true (must be in container)
-   * @example Container component: requiresParent = false (can be at top level)
+   * - `true` — cannot exist at top level, must be inside a container
+   * - `false` — can be placed directly on the canvas
+   *
+   * @example
+   * // Text: requiresParent = true (must be in a container)
+   * // Container: requiresParent = false (can be at top level)
    */
   requiresParent: boolean;
 
   /**
-   * Children architecture type
-   * 'nested' = NESTED architecture with direct children arrays (RECOMMENDED)
-   * 'flat' = FLAT architecture with parentId references (DEPRECATED)
-   * null = does not support children
+   * Children architecture type (only relevant when `supportsChildren` is `true`).
+   *
+   * - `'nested'` — Children stored as direct arrays in the parent's data (**recommended**)
+   * - `'flat'` — Children reference parent via `parentId` (**deprecated**)
+   * - `null` — Does not support children
    */
-  childrenType: "nested" | "flat" | null;
+  childrenType: 'nested' | 'flat' | null;
 
   /**
-   * Allowed child plugin IDs
-   * Empty array = all plugins allowed as children
-   * ['text', 'image'] = only specific plugins allowed
-   * Only applicable if supportsChildren = true
+   * Restricts which plugins may be added as children.
+   *
+   * - Empty array `[]` — all plugins allowed as children
+   * - `['base-text', 'base-image']` — only listed plugin IDs allowed
+   *
+   * Only applicable when `supportsChildren` is `true`.
    */
   allowedChildPlugins: string[];
 
   /**
-   * Allowed parent plugin IDs
-   * Empty array = can be child of any container
-   * ['base-container'] = can only be inside specific containers
-   * Only applicable if requiresParent = true
+   * Restricts which container plugins this plugin may be placed inside.
+   *
+   * - `undefined` or empty array `[]` — can be a child of any container
+   * - `['base-container']` — can only be inside the listed containers
+   *
+   * Only applicable when `requiresParent` is `true`.
    */
   allowedParentPlugins?: string[];
 
   /**
-   * Maximum number of children allowed
-   * null = unlimited children
-   * number = specific limit
-   * Only applicable if supportsChildren = true
+   * Maximum number of children this container can hold.
+   *
+   * - `null` — unlimited children
+   * - A positive number — enforced limit
+   *
+   * Only applicable when `supportsChildren` is `true`.
    */
   maxChildren: number | null;
 
   /**
-   * Minimum number of children required
-   * 0 = no minimum requirement
-   * Only applicable if supportsChildren = true
+   * Minimum number of children required by this container.
+   *
+   * Only applicable when `supportsChildren` is `true`.
+   * @default 0
    */
   minChildren: number;
 }
@@ -472,48 +1048,72 @@ export interface PluginCapabilities {
  */
 
 /**
- * Plugin Dependencies
+ * External dependencies injected into plugin components by the host application.
+ *
+ * Provides access to the Design System, utility functions, and optional
+ * editor callbacks. These are passed via the `dependencies` prop.
+ *
+ * **Note:** This is the simplified dependency interface used in `plugin-system.ts`.
+ * The full dependency interface (including `PluginRenderer` component and
+ * `callbacks`) is defined in `dependencies.ts`.
  *
- * External dependencies injected by host application.
- * These are provided by the web-app and contain design system,
- * utilities, and callbacks needed by plugins.
+ * @see {@link BasePluginProps.dependencies}
+ * @see {@link PluginDesignSystem} for design token access
+ * @see {@link PluginUtils} for utility functions
  */
 export interface PluginDependencies {
-	/**
-	 * Design System instance
-	 * Provides access to fonts, colors, spacing, and other design tokens
-	 */
-	designSystem: PluginDesignSystem;
-
-	/**
-	 * Utility functions
-	 * Helper functions for common operations
-	 */
-	utils: PluginUtils;
-
-	/**
-	 * Callbacks (Editor only)
-	 * Functions to update element data and properties
-	 */
-	onContentChange?: (
-		elementId: string,
-		language: string,
-		content: unknown,
-	) => void;
-	onPropertyChange?: (
-		elementId: string,
-		property: string,
-		value: unknown,
-	) => void;
+  /**
+   * Design System instance providing access to fonts, colors, spacing,
+   * breakpoints, and other design tokens.
+   *
+   * @see {@link PluginDesignSystem}
+   */
+  designSystem: PluginDesignSystem;
+
+  /**
+   * Utility functions (e.g., `cn` for class name merging)
+   * @see {@link PluginUtils}
+   */
+  utils: PluginUtils;
+
+  /**
+   * Callback invoked when the user edits text content (Editor mode only).
+   *
+   * @param elementId - Unique ID of the element being edited
+   * @param language - ISO language code of the content being changed
+   * @param content - New content value
+   */
+  onContentChange?: (
+    elementId: string,
+    language: string,
+    content: unknown
+  ) => void;
+
+  /**
+   * Callback invoked when a property value changes via the Context Panel
+   * (Editor mode only).
+   *
+   * @param elementId - Unique ID of the element being edited
+   * @param property - Dot-notation property path (e.g., `'style.fontSize'`)
+   * @param value - New property value
+   */
+  onPropertyChange?: (
+    elementId: string,
+    property: string,
+    value: unknown
+  ) => void;
 }
 
 /**
- * Base Props for ALL Plugin Components
+ * Base props required by **every** plugin component.
  *
- * Defines the minimal required props that EVERY plugin must accept.
- * Both Editor Components and Renderers should extend this interface.
+ * Both Editor Components and Renderers must accept these props.
+ * Use the generic parameter `TData` to specify the plugin's data shape.
  *
- * @template TData - Plugin-specific data type
+ * @template TData - Plugin-specific data type (defaults to `unknown`)
+ *
+ * @see {@link EditorModeProps} for additional editor-only props
+ * @see {@link RendererProps} for the minimal SSR variant
  *
  * @example
  * ```typescript
@@ -523,40 +1123,40 @@ export interface PluginDependencies {
  */
 export interface BasePluginProps<TData = unknown> {
   /**
-   * Unique element ID
-   * Used for data attributes, callbacks, and DOM references
+   * Unique element ID — used for data attributes, callbacks, and DOM references.
+   * @example 'heading-abc123'
    */
   elementId: string;
 
   /**
-   * Plugin-specific data
-   * Contains all configurable properties and content
+   * Plugin-specific data object containing all configurable properties and content.
+   * The shape is defined by the plugin's type parameter `TData`.
    */
   data: TData;
 
   /**
-   * Current language (ISO code)
-   * Used for multi-language content resolution
+   * Current language as an ISO code.
+   * Used for resolving multi-language content (`MultiLangContent`).
    * @example 'de', 'en', 'fr', 'es', 'it'
    */
   language: string;
 
   /**
-   * Injected dependencies
-   * Design system, utilities, and callbacks provided by host application
+   * Injected dependencies from the host application.
+   * @see {@link PluginDependencies}
    */
   dependencies: PluginDependencies;
 }
 
 /**
- * Editor Mode Props
+ * Additional props for Editor Components only (`'use client'`).
  *
- * Additional props needed ONLY for Editor Components.
- * These props enable interactive editing functionality.
+ * These enable interactive editing: selection highlighting, click handling,
+ * content editing, and property changes. Combine with {@link BasePluginProps}
+ * to form the full editor component props.
  *
- * Editor Components should combine:
- * - BasePluginProps<TData> (required base props)
- * - EditorModeProps (editor-specific features)
+ * @see {@link BasePluginProps}
+ * @see {@link ContainerProps} for additional container-specific props
  *
  * @example
  * ```typescript
@@ -567,52 +1167,66 @@ export interface BasePluginProps<TData = unknown> {
  */
 export interface EditorModeProps {
   /**
-   * Is component currently selected in editor?
-   * Used for visual feedback and activation of editing features
+   * Whether this component is currently selected in the editor.
+   * Used for visual feedback (selection border, handles, etc.).
+   * @default false
    */
   isSelected?: boolean;
 
   /**
-   * Click handler for component selection
-   * Called when user clicks on the component
+   * Click handler for component selection in the editor.
+   * @param elementId - ID of the clicked element
    */
   onClick?: (elementId: string) => void;
 
   /**
-   * Content change callback
-   * Called when user edits text content (contentEditable)
-   * @example onContentChange('heading-1', 'de', 'Neuer Titel')
+   * Callback for inline content editing (e.g., `contentEditable` text).
+   *
+   * @param elementId - ID of the element being edited
+   * @param language - ISO language code
+   * @param content - New content value
+   *
+   * @example
+   * ```typescript
+   * onContentChange('heading-1', 'de', 'Neuer Titel')
+   * ```
    */
   onContentChange?: (
     elementId: string,
     language: string,
-    content: unknown,
+    content: unknown
   ) => void;
 
   /**
-   * Property change callback
-   * Called when user changes properties via Context Panel
-   * @example onPropertyChange('heading-1', 'style.fontSize', '32px')
+   * Callback for property changes via the Context Panel.
+   *
+   * @param elementId - ID of the element being edited
+   * @param property - Dot-notation property path
+   * @param value - New property value
+   *
+   * @example
+   * ```typescript
+   * onPropertyChange('heading-1', 'style.fontSize', '32px')
+   * ```
    */
   onPropertyChange?: (
     elementId: string,
     property: string,
-    value: unknown,
+    value: unknown
   ) => void;
 }
 
 /**
- * Renderer Props (View/SSR Mode)
+ * Props for Renderer (SSR / view-mode) components.
  *
- * Minimal props for Server-Side Rendering components.
- * These components do NOT use 'use client' and should work in Node.js environment.
+ * Renderers are **server-safe**: they do NOT use `'use client'`, contain
+ * no React hooks, and receive no editor callbacks. Only the Design System
+ * and utility functions are injected as dependencies.
  *
- * Key differences from BasePluginProps:
- * - No callbacks (onContentChange, onPropertyChange)
- * - Minimal dependencies (only designSystem and utils, no callbacks)
- * - Should use pure functions, no React hooks
+ * @template TData - Plugin-specific data type (defaults to `unknown`)
  *
- * @template TData - Plugin-specific data type
+ * @see {@link BasePluginProps} for the full editor variant
+ * @see {@link ContainerProps} for container children
  *
  * @example
  * ```typescript
@@ -628,35 +1242,34 @@ export interface EditorModeProps {
  */
 export interface RendererProps<TData = unknown> {
   /**
-   * Unique element ID
-   * Used for data attributes and DOM references
+   * Unique element ID for data attributes and DOM references
    */
   elementId: string;
 
   /**
-   * Plugin-specific data
-   * Contains all configurable properties and content
+   * Plugin-specific data containing all properties and content
    */
   data: TData;
 
   /**
-   * Current language (ISO code)
-   * Used for multi-language content resolution
+   * Current language (ISO code) for multi-language content resolution
    */
   language: string;
 
   /**
-   * Minimal dependencies (design system and utils only)
-   * No callbacks since renderers are read-only
+   * Minimal dependencies — design system and utilities only.
+   * No callbacks since renderers are read-only.
    */
-  dependencies: Pick<PluginDependencies, "designSystem" | "utils">;
+  dependencies: Pick<PluginDependencies, 'designSystem' | 'utils'>;
 }
 
 /**
- * Container Props
+ * Props for plugins that support children (containers / layout components).
  *
- * Additional props for plugins that support children (containers, layouts).
- * Used by both Editor Components and Renderers when the plugin has supportsChildren = true.
+ * Used by both Editor Components and Renderers when the plugin has
+ * `capabilities.supportsChildren = true`.
+ *
+ * @see {@link PluginCapabilities.supportsChildren}
  *
  * @example
  * ```typescript
@@ -674,112 +1287,171 @@ export interface RendererProps<TData = unknown> {
  */
 export interface ContainerProps {
   /**
-   * Child components (rendered recursively)
-   * React nodes to be rendered inside this container
+   * Child components to render inside this container.
+   * Provided as React nodes by the recursive element renderer.
    */
   children?: React.ReactNode;
 
   /**
-   * Drop event handler (Editor only)
-   * Called when user drops an element into this container
+   * Drop event handler (Editor mode only).
+   * Called when the user drags and drops an element into this container.
    *
-   * @param targetId - Container element ID
-   * @param droppedId - Dragged element ID
-   * @param position - Drop position ('before', 'after', 'inside')
+   * @param targetId - Container element ID receiving the drop
+   * @param droppedId - ID of the element being dropped
+   * @param position - Where to insert relative to existing children
    */
   onDrop?: (
     targetId: string,
     droppedId: string,
-    position: "before" | "after" | "inside",
+    position: 'before' | 'after' | 'inside'
   ) => void;
 }
 
 /**
- * Plugin configuration (headless)
+ * Complete plugin configuration — the top-level definition object.
+ *
+ * Every plugin registers a `PluginConfig` that describes its component,
+ * editable properties, capabilities, defaults, and metadata. The editor
+ * and runtime use this to render, configure, and constrain plugin instances.
  *
- * Complete plugin definition with component, properties, and metadata.
+ * @see {@link PropertyDefinition} for how properties are declared
+ * @see {@link PluginCapabilities} for structural capabilities
+ * @see {@link PluginMeta} for optional metadata
+ *
+ * @example
+ * ```typescript
+ * const headingConfig: PluginConfig = {
+ *   id: 'base-heading',
+ *   name: 'Heading',
+ *   version: '0.1.0',
+ *   category: 'basic',
+ *   icon: Heading1,
+ *   component: HeadingComponent,
+ *   properties: [ ... ],
+ *   defaults: { contentI18n: { en: 'Heading Text', de: 'Überschrift' } },
+ *   locales: headingLocales,
+ *   ssr: true,
+ *   responsive: true,
+ *   capabilities: {
+ *     supportsChildren: false,
+ *     isRootComponent: false,
+ *     requiresParent: true,
+ *     childrenType: null,
+ *     allowedChildPlugins: [],
+ *     maxChildren: null,
+ *     minChildren: 0,
+ *   },
+ *   meta: { description: 'Semantic heading (h1-h6)', tags: ['heading'] },
+ * };
+ * ```
  */
 export interface PluginConfig {
   /**
-   * Unique plugin identifier
+   * Unique plugin identifier used for registration and lookups.
+   * Convention: `'base-heading'`, `'form-input'`, `'blog-title'`.
    */
   id: string;
 
   /**
-   * Display name
+   * Human-readable display name shown in the editor toolbar and plugin browser.
+   * @example 'Heading', 'Container', 'Form Input'
    */
   name: string;
 
   /**
-   * Semantic version
+   * Semantic version string
+   * @example '0.1.0'
    */
   version: string;
 
   /**
-   * Plugin category
+   * Plugin category — determines which toolbar section the plugin appears in.
+   *
+   * - `'basic'` — Common components (text, heading, image, button, container)
+   * - `'layout'` — Layout-focused components
+   * - `'forms'` — Form-related components (inputs, selects, form container)
+   * - `'advanced'` — Specialized or complex components
    */
-  category: "basic" | "layout" | "advanced";
+  category: 'basic' | 'layout' | 'forms' | 'advanced';
 
   /**
-   * Project types this plugin is available for.
-   * - undefined or [] = available for ALL project types (default, backward-compatible)
-   * - ['landing'] = only available for landing page projects
-   * - ['blog'] = only available for blog projects
-   * - ['landing', 'blog'] = available for both
+   * Restricts which project types can use this plugin.
+   *
+   * - `undefined` or `[]` — available for ALL project types (default, backward-compatible)
+   * - `['landing']` — only landing page projects
+   * - `['blog']` — only blog projects
+   * - `['landing', 'blog']` — both types
+   *
+   * @default undefined
    */
   projectTypes?: string[];
 
   /**
    * Semantic context for dynamic data binding.
-   * - 'static' = content defined at design time (default for most plugins)
-   * - 'dynamic' = content bound to collection entry at runtime (blog, shop items)
+   *
+   * - `'static'` — Content defined at design time (default for most plugins)
+   * - `'dynamic'` — Content bound to a collection entry at runtime (blog posts, shop items)
+   *
+   * @default 'static'
    */
-  contentBinding?: "static" | "dynamic";
+  contentBinding?: 'static' | 'dynamic';
 
   /**
-   * Icon component (optional)
+   * Icon component rendered in the editor toolbar and plugin browser.
+   * Typically a Lucide icon.
    */
   icon?: ComponentType;
 
   /**
-   * React component to render
+   * React component to render for this plugin.
+   * Must accept props compatible with {@link BasePluginProps}.
    */
   component: ComponentType<any>;
 
   /**
-   * Property definitions
+   * Array of property definitions describing editable properties.
+   * The Context Panel auto-generates UI controls from these definitions.
+   *
+   * @see {@link PropertyDefinition}
    */
   properties: PropertyDefinition[];
 
   /**
-   * Default values for new instances
+   * Default values applied when creating a new instance of this plugin.
+   * Keys correspond to top-level data paths; nested objects are supported.
    */
   defaults: Record<string, unknown>;
 
   /**
-   * Localized strings for UI
+   * Localized UI strings keyed by locale code (e.g., `{ de: {...}, en: {...} }`).
+   * Used for translating property labels and descriptions in the Context Panel.
    */
   locales: Record<string, unknown>;
 
   /**
-   * Server-side rendering support
+   * Whether this plugin supports server-side rendering.
+   * When `true`, the plugin should provide a Renderer component
+   * that works without `'use client'`.
    */
   ssr: boolean;
 
   /**
-   * Responsive design support
+   * Whether this plugin adapts to different viewport sizes.
+   * When `true`, the plugin uses responsive values from the Design System.
    */
   responsive: boolean;
 
   /**
-   * PLUGIN-DRIVEN ARCHITECTURE:
-   * Plugin capabilities define what the plugin can do
-   * The app reads these to understand how to handle the plugin
+   * Structural capabilities of this plugin — determines nesting rules,
+   * container behavior, and allowed children.
+   *
+   * @see {@link PluginCapabilities}
    */
   capabilities: PluginCapabilities;
 
   /**
-   * Plugin metadata
+   * Optional metadata for plugin listings and documentation.
+   * @see {@link PluginMeta}
    */
   meta?: PluginMeta;
 }