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

package/dist/dependencies.d.ts

@@ -1,486 +1,925 @@
 /**
  * Dependency Injection Types
  *
- * These types define the external dependencies that the plugin requires
- * from the host application. All dependencies must be injected via props.
+ * Defines the external dependencies that plugins require from the host
+ * application. All dependencies are injected via props — plugins never
+ * import host-application code directly.
+ *
+ * The **plugin-driven architecture** ensures plugins are self-contained:
+ * the host provides Design System tokens, utility functions, a renderer
+ * component, and optional callbacks through these interfaces.
+ *
+ * @see {@link PluginDependencies} — Top-level dependency container
+ * @see {@link PluginDesignSystem} — Design token access API
+ * @see {@link PluginUtils} — Shared utility functions
+ * @see {@link PluginCallbacks} — Host communication callbacks
  *
  * @package @codefluss/base-types
  * @version 1.0.0
  */
 import type { ComponentType } from 'react';
 /**
- * Responsive font size values for different breakpoints
+ * Responsive font size values for different viewport breakpoints.
+ *
+ * Each value is a CSS font-size string (e.g., `'1rem'`, `'16px'`).
+ *
+ * @see {@link DesignSystemFont.responsive}
+ *
+ * @example
+ * ```typescript
+ * const sizes: ResponsiveFontSizes = {
+ *   mobile: '1rem',
+ *   tablet: '1.25rem',
+ *   desktop: '1.5rem',
+ * };
+ * ```
  */
 export interface ResponsiveFontSizes {
+    /** Font size on mobile viewports */
     mobile: string;
+    /** Font size on tablet viewports */
     tablet: string;
+    /** Font size on desktop viewports */
     desktop: string;
 }
 /**
- * Responsive line height values for different breakpoints
+ * Responsive line height values for different viewport breakpoints.
+ *
+ * Values are unitless multipliers (e.g., `1.4` means 140% of font size).
+ *
+ * @see {@link DesignSystemFont.responsiveLineHeight}
  */
 export interface ResponsiveLineHeights {
+    /** Line height on mobile viewports */
     mobile: number;
+    /** Line height on tablet viewports */
     tablet: number;
+    /** Line height on desktop viewports */
     desktop: number;
 }
 /**
- * Design System Font Configuration
+ * Design System font configuration for a single typography preset.
+ *
+ * Each preset defines a complete typographic style — family, size, weight,
+ * line-height, and optional responsive overrides.
+ *
+ * @see {@link PluginDesignSystem.fonts}
+ *
+ * @example
+ * ```typescript
+ * const heading1: DesignSystemFont = {
+ *   family: '"Inter", sans-serif',
+ *   size: '2.5rem',
+ *   weight: '700',
+ *   lineHeight: '1.2',
+ *   element: 'h1',
+ *   responsive: { mobile: '1.75rem', tablet: '2rem', desktop: '2.5rem' },
+ * };
+ * ```
  */
 export interface DesignSystemFont {
+    /** CSS `font-family` value (e.g., `'"Inter", sans-serif'`) */
     family: string;
+    /** CSS `font-size` value — desktop default (e.g., `'2.5rem'`) */
     size: string;
+    /** CSS `font-weight` value (e.g., `'700'`, `'bold'`) */
     weight: string;
+    /** CSS `line-height` value (e.g., `'1.2'`, `'28px'`) */
     lineHeight: string;
+    /**
+     * Recommended HTML element for this preset (e.g., `'h1'`, `'h2'`, `'p'`).
+     * Used by heading/paragraph plugins to pick the semantic element.
+     */
     element?: string;
+    /**
+     * Per-viewport font size overrides.
+     * When provided, the plugin should apply these sizes at each breakpoint.
+     * @see {@link ResponsiveFontSizes}
+     */
     responsive?: ResponsiveFontSizes;
+    /**
+     * Per-viewport line-height overrides.
+     * @see {@link ResponsiveLineHeights}
+     */
     responsiveLineHeight?: ResponsiveLineHeights;
 }
 /**
- * Design System Color Configuration
+ * Design System color configuration for a single color preset.
+ *
+ * @see {@link PluginDesignSystem.colors}
+ *
+ * @example
+ * ```typescript
+ * const primary: DesignSystemColor = { value: '#3b82f6', label: 'Primary' };
+ * ```
  */
 export interface DesignSystemColor {
+    /** CSS color value (hex, rgb, hsl, or CSS variable) */
     value: string;
+    /** Human-readable label displayed in color pickers */
     label: string;
 }
 /**
- * Box Model Value - Single side values
+ * Four-sided box model value for spacing (padding / margin / gap).
+ *
+ * @see BoxModelValue in `common-types.ts` for the canonical definition.
+ * This is a parallel declaration required by the dependencies module.
  */
 export interface BoxModelValue {
+    /** Top spacing in pixels */
     top: number;
+    /** Right spacing in pixels */
     right: number;
+    /** Bottom spacing in pixels */
     bottom: number;
+    /** Left spacing in pixels */
     left: number;
 }
 /**
- * Grid Preset Values (Container-specific)
- * Clean camelCase naming
+ * Grid preset values for container grid layout configuration.
+ *
+ * Defines the complete grid parameters: columns, rows, gaps, and alignment.
+ * Uses clean camelCase naming.
+ *
+ * @see {@link DesignSystemGrid}
+ *
+ * @example
+ * ```typescript
+ * const defaultGrid: GridPresetValues = {
+ *   columns: 3,
+ *   rows: 1,
+ *   columnGap: 16,
+ *   rowGap: 16,
+ *   maxWidth: 1200,
+ *   margin: 'auto',
+ *   alignmentHorizontal: 'stretch',
+ *   alignmentVertical: 'start',
+ *   alignmentContent: 'start',
+ * };
+ * ```
  */
 export interface GridPresetValues {
+    /** Number of grid columns */
     columns: number;
+    /** Number of grid rows */
     rows: number;
+    /** Horizontal gap between columns in pixels */
     columnGap: number;
+    /** Vertical gap between rows in pixels */
     rowGap: number;
+    /** Maximum grid width in pixels */
     maxWidth: number;
+    /** Horizontal margin — number (px) or CSS string (e.g., `'auto'`) */
     margin: number | string;
+    /** CSS `justify-items` value (e.g., `'stretch'`, `'center'`) */
     alignmentHorizontal: string;
+    /** CSS `align-items` value (e.g., `'start'`, `'center'`, `'stretch'`) */
     alignmentVertical: string;
+    /** CSS `align-content` value (e.g., `'start'`, `'stretch'`) */
     alignmentContent: string;
 }
 /**
- * Responsive spacing values for different breakpoints
- * Only 3 viewports: mobile, tablet, desktop
+ * Responsive box model values — spacing for each viewport breakpoint.
+ *
+ * @see {@link BoxModelValue}
+ *
+ * @example
+ * ```typescript
+ * const padding: ResponsiveBoxValues = {
+ *   mobile:  { top: 8, right: 8, bottom: 8, left: 8 },
+ *   tablet:  { top: 16, right: 16, bottom: 16, left: 16 },
+ *   desktop: { top: 24, right: 24, bottom: 24, left: 24 },
+ * };
+ * ```
  */
 export interface ResponsiveBoxValues {
+    /** Spacing values on mobile viewports */
     mobile: BoxModelValue;
+    /** Spacing values on tablet viewports */
     tablet: BoxModelValue;
+    /** Spacing values on desktop viewports */
     desktop: BoxModelValue;
 }
 /**
- * Spacing Preset - Combined margin + padding with responsive values
+ * Spacing preset — combined margin and padding with responsive values.
+ *
+ * Presets are managed in the Design System and referenced by ID.
+ * Plugins use `spacingPresetId` to apply a preset, with optional per-element overrides.
+ *
+ * @see {@link DesignSystemSpacing.getPreset}
+ *
+ * @example
+ * ```typescript
+ * const preset: SpacingPreset = {
+ *   presetId: 'spacing-text-default',
+ *   name: 'Text Default',
+ *   margin:  { mobile: { top: 0, ... }, tablet: { ... }, desktop: { ... } },
+ *   padding: { mobile: { top: 8, ... }, tablet: { ... }, desktop: { ... } },
+ * };
+ * ```
  */
 export interface SpacingPreset {
+    /** Unique preset identifier (e.g., `'spacing-text-default'`, `'default'`) */
     presetId: string;
+    /** Human-readable preset name shown in the editor */
     name: string;
+    /** Responsive margin values (per-viewport) */
     margin: ResponsiveBoxValues;
+    /** Responsive padding values (per-viewport) */
     padding: ResponsiveBoxValues;
 }
 /**
- * Responsive spacing scale entry
+ * Responsive spacing scale entry — a single token in the spacing scale.
+ *
+ * Defines a spacing value that varies by viewport.
+ *
+ * @see {@link DesignSystemSpacing.scaleResponsive}
  */
 export interface ResponsiveSpacingScale {
+    /** Spacing value on mobile viewports */
     mobile: number;
+    /** Spacing value on tablet viewports */
     tablet: number;
+    /** Spacing value on desktop viewports */
     desktop: number;
+    /** CSS unit for this scale entry (e.g., `'px'`, `'rem'`) */
     unit: string;
 }
 /**
- * Design System Spacing Configuration
- * Clean, type-safe API
+ * Design System spacing configuration — provides spacing presets and scales.
+ *
+ * @see {@link PluginDesignSystem.spacing}
  */
 export interface DesignSystemSpacing {
-    /** Spacing scale values */
+    /** Base spacing scale values (e.g., `[0, 4, 8, 12, 16, 24, 32, 48, 64]`) */
     scale: number[];
-    /** Responsive spacing scales by token */
+    /** Responsive spacing scales keyed by design token name */
     scaleResponsive: Map<string, ResponsiveSpacingScale>;
     /**
-     * Get a spacing preset by ID
-     * @param presetId - The preset identifier
-     * @returns The spacing preset (guaranteed to exist, falls back to 'default')
+     * Retrieve a spacing preset by ID.
+     *
+     * Guaranteed to return a valid preset — falls back to `'default'`
+     * if the requested ID is not found.
+     *
+     * @param presetId - The preset identifier (e.g., `'spacing-text-default'`)
+     * @returns The spacing preset with margin and padding values
      */
     getPreset(presetId: string): SpacingPreset;
 }
 /**
- * Design System Grid Configuration
- * Clean, type-safe API
+ * Design System grid configuration — provides grid layout presets.
+ *
+ * @see {@link PluginDesignSystem.grid}
  */
 export interface DesignSystemGrid {
     /**
-     * Get a grid preset by ID
-     * @param presetId - The preset identifier
-     * @returns The grid preset values (guaranteed to exist, falls back to 'default')
+     * Retrieve a grid preset by ID.
+     *
+     * Guaranteed to return valid values — falls back to `'default'`
+     * if the requested ID is not found.
+     *
+     * @param presetId - The preset identifier (e.g., `'default'`, `'narrow'`)
+     * @returns Grid preset values (columns, rows, gaps, alignment)
      */
     getPreset(presetId: string): GridPresetValues;
 }
 /**
- * Breakpoint configuration for responsive design
+ * Breakpoint configuration for a single viewport.
+ *
+ * @see {@link DesignSystemBreakpoints}
  */
 export interface BreakpointConfig {
+    /** Minimum viewport width in pixels for this breakpoint */
     minWidth: number;
+    /** Breakpoint display name (e.g., `'Mobile'`, `'Tablet'`, `'Desktop'`) */
     name: string;
 }
 /**
- * Design System Breakpoints
+ * Design System breakpoint definitions for responsive design.
+ *
+ * @see {@link PluginDesignSystem.breakpoints}
+ *
+ * @example
+ * ```typescript
+ * const breakpoints: DesignSystemBreakpoints = {
+ *   mobile:  { minWidth: 0, name: 'Mobile' },
+ *   tablet:  { minWidth: 768, name: 'Tablet' },
+ *   desktop: { minWidth: 1024, name: 'Desktop' },
+ * };
+ * ```
  */
 export interface DesignSystemBreakpoints {
+    /** Mobile breakpoint configuration */
     mobile: BreakpointConfig;
+    /** Tablet breakpoint configuration */
     tablet: BreakpointConfig;
+    /** Desktop breakpoint configuration */
     desktop: BreakpointConfig;
 }
 /**
- * Design System Layout Configuration
+ * Design System layout configuration — global layout defaults.
+ *
+ * @see {@link PluginDesignSystem.layout}
  */
 export interface DesignSystemLayout {
+    /** Maximum content width (CSS value, e.g., `'1200px'`) */
     maxWidth?: string;
+    /** Default gap between elements (CSS value) */
     gap?: string;
+    /** Default padding (CSS value) */
     padding?: string;
+    /** Default margin (CSS value) */
     margin?: string;
 }
 /**
- * Button Style Preset Configuration (Unified)
+ * Unified button style preset from the Design System.
+ *
+ * Contains all styling for a button variant: colors (per state),
+ * typography, spacing, border, effects, and animations.
+ * Matches the `design_system_button_styles` database table structure.
  *
- * Complete button style preset that replaces the separate
- * ButtonSizePreset and ButtonVariantPreset interfaces.
- * Matches design_system_button_styles table structure.
+ * @see {@link PluginDesignSystem.buttons}
+ *
+ * @example
+ * ```typescript
+ * const primary: ButtonStylePreset = {
+ *   id: 'btn-1',
+ *   presetId: 'primary',
+ *   name: 'Primary',
+ *   size: 'md',
+ *   backgroundColorPresetId: 'primary',
+ *   textColorPresetId: 'primary-foreground',
+ *   defaultTransitionDuration: 150,
+ *   hoverTransitionDuration: 150,
+ *   activeTransitionDuration: 100,
+ *   disabledOpacity: 0.5,
+ *   isDefault: true,
+ * };
+ * ```
  */
 export interface ButtonStylePreset {
+    /** Database row ID */
     id: string;
+    /** Unique preset identifier (e.g., `'primary'`, `'secondary'`, `'ghost'`) */
     presetId: string;
+    /** Human-readable name shown in the editor */
     name: string;
+    /** Size variant (e.g., `'sm'`, `'md'`, `'lg'`) */
     size: string;
+    /** Design System font preset ID for button text */
     fontSizePresetId?: string;
+    /** CSS `font-weight` value */
     fontWeight?: string;
+    /** Spacing preset ID for internal padding */
     spacingPresetId?: string;
+    /** Border radius preset ID */
     borderRadiusPresetId?: string;
+    /** Box shadow preset ID */
     shadowPresetId?: string;
+    /** Focus ring preset ID (accessibility) */
     focusRingPresetId?: string;
+    /** Entry/exit animation preset ID */
     animationPresetId?: string;
+    /** Hover animation effect preset ID */
     hoverEffectPresetId?: string;
+    /** Background color preset ID (default state) */
     backgroundColorPresetId?: string;
+    /** Text color preset ID (default state) */
     textColorPresetId?: string;
+    /** Border color preset ID (default state) */
     borderColorPresetId?: string;
+    /** Background color preset ID on hover */
     hoverBackgroundColorPresetId?: string;
+    /** Text color preset ID on hover */
     hoverTextColorPresetId?: string;
+    /** Border color preset ID on hover */
     hoverBorderColorPresetId?: string;
+    /** Background color preset ID when pressed */
     activeBackgroundColorPresetId?: string;
+    /** Text color preset ID when pressed */
     activeTextColorPresetId?: string;
+    /** Border color preset ID when pressed */
     activeBorderColorPresetId?: string;
+    /** Default state transition duration in milliseconds */
     defaultTransitionDuration: number;
+    /** Hover state transition duration in milliseconds */
     hoverTransitionDuration: number;
+    /** Active/pressed state transition duration in milliseconds */
     activeTransitionDuration: number;
+    /** Opacity applied when the button is disabled (0–1) */
     disabledOpacity: number;
+    /** CSS `text-decoration` in default state */
     defaultTextDecoration?: string;
+    /** CSS `text-decoration` on hover */
     hoverTextDecoration?: string;
+    /** CSS `text-decoration` when active/pressed */
     activeTextDecoration?: string;
+    /** CSS `text-transform` in default state */
     defaultTextTransform?: string;
+    /** CSS `text-transform` on hover */
     hoverTextTransform?: string;
+    /** CSS `text-transform` when active/pressed */
     activeTextTransform?: string;
+    /** Description of when/where to use this preset */
     usageDescription?: string;
+    /** Whether this is the default preset for new button instances */
     isDefault: boolean;
 }
 /**
- * @deprecated Use ButtonStylePreset instead
- * Legacy Button Size Preset Configuration
+ * Legacy button size preset configuration.
+ *
+ * @deprecated Use {@link ButtonStylePreset} instead — this interface
+ * will be removed in a future version.
  */
 export interface ButtonSizePreset {
+    /** Button preset ID */
     button_id: string;
+    /** Preset display name */
     name: string;
+    /** CSS padding value */
     padding: string;
+    /** CSS font-size value */
     fontSize: string;
+    /** Icon size value */
     iconSize: string;
+    /** CSS min-height value */
     minHeight: string;
+    /** CSS border-radius value */
     borderRadius?: string;
+    /** CSS font-weight value */
     fontWeight?: string;
+    /** Description of intended usage */
     usage_description?: string;
 }
 /**
- * @deprecated Use ButtonStylePreset instead
- * Legacy Button Variant Preset Configuration
+ * Legacy button variant preset configuration.
+ *
+ * @deprecated Use {@link ButtonStylePreset} instead — this interface
+ * will be removed in a future version.
  */
 export interface ButtonVariantPreset {
+    /** Background color */
     background: string;
+    /** Background color on hover */
     hoverBackground: string;
+    /** Text color */
     textColor: string;
+    /** Border color */
     borderColor: string;
 }
 /**
- * Shadow Configuration
+ * Shadow configuration with optional dark-mode variant.
+ *
+ * @see {@link PluginDesignSystem.shadows}
+ *
+ * @example
+ * ```typescript
+ * const shadow: ShadowConfig = {
+ *   value: '0 4px 6px rgba(0, 0, 0, 0.1)',
+ *   dark: '0 4px 6px rgba(0, 0, 0, 0.3)',
+ * };
+ * ```
  */
 export interface ShadowConfig {
+    /** CSS `box-shadow` value for light mode */
     value: string;
+    /** CSS `box-shadow` value for dark mode (falls back to `value` if not set) */
     dark?: string;
 }
 /**
- * Accordion Style Preset Configuration
+ * Accordion style preset from the Design System.
  *
- * Complete accordion style preset for collapsible components.
- * Matches design_system_accordion_presets table structure.
+ * Contains all styling for collapsible accordion components: header/body
+ * colors, typography, spacing, animations, and state variants.
+ * Matches the `design_system_accordion_presets` database table structure.
+ *
+ * @see {@link PluginDesignSystem.accordions}
  */
 export interface AccordionStylePreset {
+    /** Database row ID */
     id: string;
+    /** Unique preset identifier (e.g., `'default'`, `'sm'`, `'lg'`) */
     presetId: string;
+    /** Human-readable preset name */
     name: string;
+    /** CSS height for the accordion header (e.g., `'48px'`) */
     headerHeight?: string;
+    /** Font preset ID for header text */
     headerFontSizePresetId?: string;
+    /** CSS `font-weight` for header text */
     headerFontWeight?: string;
+    /** Spacing preset ID for header padding */
     headerPaddingPresetId?: string;
+    /** Background color preset ID for header (default state) */
     headerBackgroundColorPresetId?: string;
+    /** Background color preset ID for header on hover */
     headerHoverBackgroundColorPresetId?: string;
+    /** Text color preset ID for header */
     headerTextColorPresetId?: string;
+    /** Border color preset ID for header */
     headerBorderColorPresetId?: string;
+    /** Minimum height for the accordion body (e.g., `'100px'`) */
     bodyMinHeight?: string;
+    /** Spacing preset ID for body padding */
     bodyPaddingPresetId?: string;
+    /** Background color preset ID for body */
     bodyBackgroundColorPresetId?: string;
+    /** Border color preset ID for body */
     bodyBorderColorPresetId?: string;
+    /** Border radius preset ID */
     borderRadiusPresetId?: string;
+    /** Box shadow preset ID */
     shadowPresetId?: string;
+    /** Outer spacing preset ID */
     spacingPresetId?: string;
+    /** Expand/collapse transition duration in milliseconds */
     transitionDuration: number;
+    /** CSS easing function (e.g., `'ease-in-out'`) */
     transitionEasing?: string;
+    /** Background color preset ID when expanded */
     expandedBackgroundColorPresetId?: string;
+    /** Text color preset ID when expanded */
     expandedTextColorPresetId?: string;
+    /** Description of when/where to use this preset */
     usageDescription?: string;
+    /** Whether this is the default preset for new accordion instances */
     isDefault: boolean;
 }
 /**
- * Form Style Preset Configuration (Unified)
+ * Unified form style preset from the Design System.
+ *
+ * Contains all styling for form elements: input fields, labels, descriptions,
+ * error states, and submit buttons. Matches the `design_system_form_styles`
+ * database table structure.
  *
- * Complete form style preset that contains all styling for form elements.
- * Matches design_system_form_styles table structure.
+ * @see {@link PluginDesignSystem.forms}
  */
 export interface FormStylePreset {
+    /** Database row ID */
     id: string;
+    /** Unique preset identifier (e.g., `'default'`, `'outlined'`) */
     presetId: string;
+    /** Human-readable preset name */
     name: string;
+    /** Visual variant (e.g., `'filled'`, `'outlined'`, `'underlined'`) */
     variant: string;
+    /** Size variant (e.g., `'sm'`, `'md'`, `'lg'`) */
     size: string;
+    /** Font preset ID for input text */
     fontSizePresetId?: string;
+    /** Horizontal padding in pixels */
     paddingX: number;
+    /** Vertical padding in pixels */
     paddingY: number;
+    /** Border width in pixels */
     borderWidth: number;
+    /** Border radius preset ID */
     borderRadiusPresetId?: string;
+    /** Box shadow preset ID */
     shadowPresetId?: string;
+    /** Focus ring preset ID */
     focusRingPresetId?: string;
+    /** Entry/exit animation preset ID */
     animationPresetId?: string;
+    /** Hover animation effect preset ID */
     hoverEffectPresetId?: string;
+    /** Input background color preset ID */
     backgroundColorPresetId?: string;
+    /** Input text color preset ID */
     textColorPresetId?: string;
+    /** Input border color preset ID */
     borderColorPresetId?: string;
+    /** Placeholder text color preset ID */
     placeholderColorPresetId?: string;
+    /** Focus ring color preset ID */
     focusRingColorPresetId?: string;
+    /** Background color preset ID on hover */
     hoverBackgroundColorPresetId?: string;
+    /** Border color preset ID on hover */
     hoverBorderColorPresetId?: string;
+    /** Opacity applied when the input is disabled (0–1) */
     disabledOpacity: number;
+    /** Border color preset ID in error state */
     errorBorderColorPresetId?: string;
+    /** Error message text color preset ID */
     errorTextColorPresetId?: string;
+    /** Button style preset ID for the form's submit button */
     submitButtonPresetId?: string;
+    /** Background color preset ID for the form container */
     containerBackgroundColorPresetId?: string;
+    /** Spacing preset ID for the form container */
     containerSpacingPresetId?: string;
+    /** Font preset ID for field labels */
     labelFontPresetId?: string;
+    /** Color preset ID for field labels */
     labelColorPresetId?: string;
+    /** Font preset ID for help/description text */
     descriptionFontPresetId?: string;
+    /** Color preset ID for help/description text */
     descriptionColorPresetId?: string;
+    /** Vertical gap between form fields in pixels */
     fieldGap?: number;
+    /** Description of when/where to use this preset */
     usageDescription?: string;
+    /** Whether this is the default preset for new form instances */
     isDefault: boolean;
 }
 /**
- * Design System API
+ * Design System API — the unified interface for accessing design tokens.
+ *
+ * Plugins receive this via {@link PluginDependencies.designSystem}.
+ * The host application provides an implementation backed by the database
+ * or configuration files.
+ *
+ * @see {@link PluginDependencies}
  *
- * Interface for accessing global design system values.
- * The host application must provide an implementation.
+ * @example
+ * ```typescript
+ * // Inside a plugin component
+ * const { designSystem } = dependencies;
+ * const font = designSystem.fonts.getPreset('heading-1');
+ * const color = designSystem.colors.getPreset('primary');
+ * const spacing = designSystem.spacing.getPreset('default');
+ * ```
  */
 export interface PluginDesignSystem {
+    /**
+     * Typography preset system.
+     * @see {@link DesignSystemFont}
+     */
     fonts: {
+        /**
+         * Get a font preset by ID.
+         * @param presetId - Font preset identifier (e.g., `'heading-1'`, `'body'`)
+         * @returns Font configuration or `undefined` if not found
+         */
         getPreset: (presetId: string) => DesignSystemFont | undefined;
     };
+    /**
+     * Color preset system.
+     * @see {@link DesignSystemColor}
+     */
     colors: {
+        /**
+         * Get a color preset by ID.
+         * @param presetId - Color preset identifier (e.g., `'primary'`, `'foreground'`)
+         * @returns Color configuration or `undefined` if not found
+         */
         getPreset: (presetId: string) => DesignSystemColor | undefined;
     };
+    /**
+     * Spacing system with presets and scales.
+     * @see {@link DesignSystemSpacing}
+     */
     spacing: DesignSystemSpacing;
+    /**
+     * Grid layout system (optional, container-specific).
+     * @see {@link DesignSystemGrid}
+     */
     grid?: DesignSystemGrid;
+    /**
+     * Layout preset system for global layout defaults.
+     * @see {@link DesignSystemLayout}
+     */
     layout: {
+        /**
+         * Get a layout preset by ID.
+         * @param presetId - Layout preset identifier
+         * @returns Layout configuration or `undefined` if not found
+         */
         getPreset: (presetId: string) => DesignSystemLayout | undefined;
     };
+    /**
+     * Viewport breakpoint configuration.
+     * @see {@link DesignSystemBreakpoints}
+     */
     breakpoints: {
+        /**
+         * Get all breakpoint configurations.
+         * @returns Mobile, tablet, and desktop breakpoint definitions
+         */
         getConfig: () => DesignSystemBreakpoints;
     };
     /**
-     * Button System (optional)
-     * Provides unified button style presets from design system database
-     * Each preset contains colors, typography, spacing, and effects
+     * Button style preset system (optional).
+     *
+     * Provides unified button styling from the design system database.
+     * Each preset contains colors, typography, spacing, and effects.
+     *
+     * @see {@link ButtonStylePreset}
      */
     buttons?: {
         /**
-         * Get button style preset by ID
-         * @param presetId - Button preset identifier (e.g., 'primary', 'secondary', 'custom-1')
-         * @returns Button style preset or undefined if not found
+         * Get a button style preset by ID.
+         * @param presetId - Button preset identifier (e.g., `'primary'`, `'secondary'`)
+         * @returns Button style preset or `undefined` if not found
          */
         getPreset: (presetId: string) => ButtonStylePreset | undefined;
         /**
-         * List all available button style presets
-         * @returns Array of button style presets sorted by sort_order
+         * List all available button style presets.
+         * @returns Array of button style presets sorted by sort order
          */
         listPresets?: () => ButtonStylePreset[];
     };
     /**
-     * Form System (optional)
-     * Provides unified form style presets from design system database
-     * Each preset contains colors, typography, spacing, and effects for form elements
+     * Form style preset system (optional).
+     *
+     * Provides unified form element styling from the design system database.
+     *
+     * @see {@link FormStylePreset}
      */
     forms?: {
         /**
-         * Get form style preset by ID
-         * @param presetId - Form preset identifier (e.g., 'default', 'outlined', 'custom-1')
-         * @returns Form style preset or undefined if not found
+         * Get a form style preset by ID.
+         * @param presetId - Form preset identifier (e.g., `'default'`, `'outlined'`)
+         * @returns Form style preset or `undefined` if not found
          */
         getPreset: (presetId: string) => FormStylePreset | undefined;
         /**
-         * List all available form style presets
-         * @returns Array of form style presets sorted by sort_order
+         * List all available form style presets.
+         * @returns Array of form style presets sorted by sort order
          */
         listPresets?: () => FormStylePreset[];
     };
     /**
-     * Accordion System (optional)
-     * Provides unified accordion style presets from design system database
-     * Each preset contains colors, typography, spacing, and effects for accordion components
+     * Accordion style preset system (optional).
+     *
+     * Provides unified accordion styling from the design system database.
+     *
+     * @see {@link AccordionStylePreset}
      */
     accordions?: {
         /**
-         * Get accordion style preset by ID
-         * @param presetId - Accordion preset identifier (e.g., 'default', 'sm', 'lg', 'custom-1')
-         * @returns Accordion style preset or undefined if not found
+         * Get an accordion style preset by ID.
+         * @param presetId - Accordion preset identifier (e.g., `'default'`, `'sm'`, `'lg'`)
+         * @returns Accordion style preset or `undefined` if not found
          */
         getPreset: (presetId: string) => AccordionStylePreset | undefined;
         /**
-         * List all available accordion style presets
-         * @returns Array of accordion style presets sorted by sort_order
+         * List all available accordion style presets.
+         * @returns Array of accordion style presets sorted by sort order
          */
         listPresets?: () => AccordionStylePreset[];
     };
     /**
-     * Shadow System (optional)
-     * Provides shadow presets with light and dark mode variants
+     * Shadow preset system (optional).
+     *
+     * Provides box-shadow values with optional dark-mode variants.
+     *
+     * @see {@link ShadowConfig}
      */
     shadows?: {
+        /**
+         * Get a shadow preset by ID.
+         * @param presetId - Shadow preset identifier (e.g., `'sm'`, `'md'`, `'lg'`)
+         * @returns Shadow configuration (guaranteed to exist)
+         */
         getPreset: (presetId: string) => ShadowConfig;
     };
 }
 /**
- * Utility Functions API
+ * Utility functions API injected into plugins by the host application.
  *
- * Interface for utility functions required by the plugin.
- * The host application must provide implementations.
+ * @see {@link PluginDependencies.utils}
  */
 export interface PluginUtils {
     /**
-     * Class name utility (e.g., clsx, classnames, tailwind-merge)
-     * Combines multiple class names intelligently
+     * Class name utility function (e.g., `clsx`, `classnames`, `tailwind-merge`).
+     *
+     * Combines and deduplicates class names intelligently.
+     *
+     * @param inputs - Class names, arrays, objects, or falsy values
+     * @returns Merged class name string
+     *
+     * @example
+     * ```typescript
+     * const { cn } = dependencies.utils;
+     * const className = cn('base', isActive && 'active', { 'selected': isSelected });
+     * ```
      */
     cn: (...inputs: any[]) => string;
 }
 /**
- * Plugin Renderer Props
+ * Props for the `PluginRenderer` component injected by the host application.
  *
- * Props interface for the PluginRenderer component.
- * This is injected by the host application to render child plugins.
+ * Container plugins use this to recursively render their child elements.
+ * The host provides the actual implementation that resolves plugin IDs
+ * to component instances.
+ *
+ * @see {@link PluginDependencies.PluginRenderer}
  */
 export interface PluginRendererProps {
     /**
-     * Plugin ID to render (e.g., 'base-text', 'base-image')
+     * Plugin ID to render (e.g., `'base-text'`, `'base-image'`)
      */
     pluginId: string;
     /**
-     * Element ID for tracking
+     * Unique element ID for tracking and callbacks
      */
     elementId: string;
     /**
-     * Plugin data/configuration
+     * Plugin data / configuration object
      */
     data: Record<string, unknown>;
     /**
-     * Current language code
+     * Current language code (ISO) for content resolution
      */
     language: string;
     /**
-     * Is in editor mode?
+     * Whether the host is in editor mode (interactive editing enabled)
+     * @default false
      */
     isEditorMode?: boolean;
     /**
-     * Is element selected?
+     * Whether this element is currently selected in the editor
+     * @default false
      */
     isSelected?: boolean;
     /**
-     * Click handler
+     * Click handler for element selection
+     * @param id - Element ID that was clicked
      */
     onClick?: (id: string) => void;
 }
 /**
- * Plugin Callbacks
+ * Event callbacks for plugin-to-host communication.
+ *
+ * Plugins invoke these to notify the host application of user actions
+ * like content edits, child additions/removals, and layout changes.
  *
- * Event callbacks that plugins can use to communicate with the host application.
+ * @see {@link PluginDependencies.callbacks}
  */
 export interface PluginCallbacks {
     /**
-     * Called when content changes (for text, rich-text components)
-     * @param elementId - ID of the element
-     * @param language - Language code
+     * Called when text content changes (for text, rich-text components).
+     *
+     * @param elementId - ID of the element being edited
+     * @param language - ISO language code of the content
      * @param content - New content value
      */
     onContentChange?: (elementId: string, language: string, content: string) => void;
     /**
-     * Called when child element is dropped into container
-     * @param containerId - ID of the container element
+     * Called when a child element is dropped into a container.
+     *
+     * @param containerId - ID of the receiving container
      * @param droppedElementId - ID of the dropped element
-     * @param index - Optional insertion index
+     * @param index - Optional insertion index (append if omitted)
      */
     onChildAdded?: (containerId: string, droppedElementId: string, index?: number) => void;
     /**
-     * Called when child element is removed from container
-     * @param containerId - ID of the container element
+     * Called when a child element is removed from a container.
+     *
+     * @param containerId - ID of the container
      * @param removedElementId - ID of the removed element
      */
     onChildRemoved?: (containerId: string, removedElementId: string) => void;
     /**
-     * Called when container layout is changed
-     * @param containerId - ID of the container element
+     * Called when a container's layout mode changes.
+     *
+     * @param containerId - ID of the container
      * @param layoutMode - New layout mode
      */
     onLayoutChange?: (containerId: string, layoutMode: 'flexbox' | 'grid') => void;
 }
 /**
- * Complete Plugin Dependencies
+ * Complete plugin dependencies — everything a plugin receives from the host.
+ *
+ * This is the full dependency interface used by the `dependencies.ts` module.
+ * It includes the `PluginRenderer` component and optional callbacks,
+ * which are not present in the simplified version in `plugin-system.ts`.
+ *
+ * **Plugin-driven architecture:** Plugins never import host code directly.
+ * All external functionality is injected through this interface.
  *
- * All external dependencies that must be injected into the plugin.
- * PLUGIN-DRIVEN ARCHITECTURE: Plugins receive dependencies from the host app.
+ * @see {@link PluginDesignSystem} for design token access
+ * @see {@link PluginUtils} for utility functions
+ * @see {@link PluginRendererProps} for the renderer component props
+ * @see {@link PluginCallbacks} for event communication
  */
 export interface PluginDependencies {
     /**
      * Design System API for accessing global design tokens
+     * (fonts, colors, spacing, breakpoints, etc.).
+     * @see {@link PluginDesignSystem}
      */
     designSystem: PluginDesignSystem;
     /**
-     * Utility functions (e.g., cn for classnames)
+     * Utility functions (e.g., `cn` for class name merging).
+     * @see {@link PluginUtils}
      */
     utils: PluginUtils;
     /**
-     * PluginRenderer component for rendering child plugins
-     * CRITICAL: Container plugins need this to render their NESTED children
+     * Component for recursively rendering child plugins inside containers.
+     *
+     * **Critical** for container plugins with `supportsChildren = true` —
+     * they use this to render their nested children.
+     *
+     * @see {@link PluginRendererProps}
      */
     PluginRenderer: ComponentType<PluginRendererProps>;
     /**
-     * Optional callbacks for communication with host app
+     * Optional event callbacks for communicating with the host application.
+     * @see {@link PluginCallbacks}
      */
     callbacks?: PluginCallbacks;
 }