@kubb/core 5.0.0-alpha.33 → 5.0.0-alpha.35

package/src/types.ts

@@ -1,92 +1,15 @@
 import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
-import type { FileNode, ImportNode, InputNode, Node, OperationNode, Printer, SchemaNode, Visitor } from '@kubb/ast/types'
+import type { FileNode, ImportNode, InputNode, Node, OperationNode, SchemaNode, Visitor } from '@kubb/ast'
 import type { HttpMethod } from '@kubb/oas'
-import type { KubbReactNode } from '@kubb/renderer-jsx/types'
 import type { DEFAULT_STUDIO_URL, logLevel } from './constants.ts'
+import type { RendererFactory } from './createRenderer.ts'
 import type { Storage } from './createStorage.ts'
 import type { Generator } from './defineGenerator.ts'
 import type { Parser } from './defineParser.ts'
-import type { KubbEvents } from './Kubb.ts'
+import type { KubbHooks } from './Kubb.ts'
 import type { PluginDriver } from './PluginDriver.ts'
 
-export type { Printer, PrinterFactoryOptions, PrinterPartial } from '@kubb/ast/types'
-
-declare global {
-  namespace Kubb {
-    interface PluginContext {}
-    /**
-     * Registry that maps plugin names to their `PluginFactoryOptions`.
-     * Augment this interface in each plugin's `types.ts` to enable automatic
-     * typing for `getPlugin` and `requirePlugin`.
-     *
-     * @example
-     * ```ts
-     * // packages/plugin-ts/src/types.ts
-     * declare global {
-     *   namespace Kubb {
-     *     interface PluginRegistry {
-     *       'plugin-ts': PluginTs
-     *     }
-     *   }
-     * }
-     * ```
-     */
-    interface PluginRegistry {}
-  }
-}
-
-/**
- * Config used in `kubb.config.ts`
- *
- * @example
- * import { defineConfig } from '@kubb/core'
- * export default defineConfig({
- * ...
- * })
- */
-export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter'> & {
-  /**
-   * The project root directory, which can be either an absolute path or a path relative to the location of your `kubb.config.ts` file.
-   * @default process.cwd()
-   */
-  root?: string
-  /**
-   * An array of parsers used to convert generated files to strings.
-   * Each parser handles specific file extensions (e.g. `.ts`, `.tsx`).
-   *
-   * A catch-all fallback parser is always appended last for any unhandled extension.
-   *
-   * When omitted, `parserTsx` from `@kubb/parser-ts` is used automatically as the
-   * default (requires `@kubb/parser-ts` to be installed as an optional dependency).
-   * @default [parserTsx] — from `@kubb/parser-ts`
-   * @example
-   * ```ts
-   * import { parserTs, tsxParser } from '@kubb/parser-ts'
-   * export default defineConfig({
-   *   parsers: [parserTs, tsxParser],
-   * })
-   * ```
-   */
-  parsers?: Array<Parser>
-  /**
-   * Adapter that converts the input file into a `@kubb/ast` `InputNode` — the universal
-   * intermediate representation consumed by all Kubb plugins.
-   *
-   * When omitted, `adapterOas()` from `@kubb/adapter-oas` is used automatically as the
-   * default (requires `@kubb/adapter-oas` to be installed as an optional dependency).
-   *
-   * - Use `@kubb/adapter-oas` for OpenAPI / Swagger (default).
-   * - Use `@kubb/adapter-drizzle` or `@kubb/adapter-asyncapi` for other formats.
-   *
-   * @default adapterOas() — from `@kubb/adapter-oas`
-   */
-  adapter?: Adapter
-  /**
-   * An array of Kubb plugins used for generation. Each plugin may have additional configurable options (defined within the plugin itself). If a plugin relies on another plugin, an error will occur if the required dependency is missing. Refer to “pre” for more details.
-   */
-  // inject needs to be omitted because else we have a clash with the PluginDriver instance
-  plugins?: Array<Omit<UnknownUserPlugin, 'inject'>>
-}
+export type { Renderer, RendererFactory } from './createRenderer.ts'
 
 export type InputPath = {
   /**
@@ -178,6 +101,12 @@ export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptio
   getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string }) => Array<ImportNode>
 }
 
+/**
+ * Controls how `index.ts` barrel files are generated.
+ * - `'all'` — exports every generated symbol from every file.
+ * - `'named'` — exports only explicitly named exports.
+ * - `'propagate'` — propagates re-exports from nested barrel files upward.
+ */
 export type BarrelType = 'all' | 'named' | 'propagate'
 
 export type DevtoolsOptions = {
@@ -238,13 +167,14 @@ export type Config<TInput = Input> = {
    */
   adapter: Adapter
   /**
-   * You can use either `input.path` or `input.data`, depending on your specific needs.
+   * Source file or data to generate code from.
+   * Use `input.path` for a file on disk or `input.data` for an inline string or object.
    */
   input: TInput
   output: {
     /**
-     * The path where all generated files receives exported.
-     * This can be an absolute path or a path relative to the specified root option.
+     * Output directory for generated files.
+     * Accepts an absolute path or a path relative to `root`.
      */
     path: string
     /**
@@ -317,11 +247,28 @@ export type Config<TInput = Input> = {
     override?: boolean
   }
   /**
-   * An array of Kubb plugins that used in the generation.
-   * Each plugin may include additional configurable options(defined in the plugin itself).
-   * If a plugin depends on another plugin, an error is returned if the required dependency is missing. See pre for more details.
+   * An array of Kubb plugins used for code generation.
+   * Each plugin may declare additional configurable options.
+   * If a plugin depends on another, an error is thrown when the dependency is missing.
+   * Use `dependencies` on the plugin to declare execution order.
    */
   plugins: Array<Plugin>
+  /**
+   * Project-wide renderer factory. All plugins and generators that do not declare their own
+   * `renderer` ultimately fall back to this value.
+   *
+   * The resolution chain is: `generator.renderer` → `plugin.renderer` → `config.renderer` → `undefined` (raw `FileNode[]` mode).
+   *
+   * @example
+   * ```ts
+   * import { jsxRenderer } from '@kubb/renderer-jsx'
+   * export default defineConfig({
+   *   renderer: jsxRenderer,
+   *   plugins: [pluginTs(), pluginZod()],
+   * })
+   * ```
+   */
+  renderer?: RendererFactory
   /**
    * Devtools configuration for Kubb Studio integration.
    */
@@ -400,22 +347,6 @@ export type Resolver = {
   resolveFooter(node: InputNode | null, context: ResolveBannerContext): string | undefined
 }
 
-/**
- * The user-facing subset of a `Resolver` — everything except the four methods injected by
- * `defineResolver` (`default`, `resolveOptions`, `resolvePath`, and `resolveFile`).
- *
- * All four injected methods can still be overridden by providing them explicitly in the builder.
- *
- * @example
- * ```ts
- * export const resolver = defineResolver<PluginTs>(() => ({
- *   name: 'default',
- *   resolveName(node) { return this.default(node.name, 'function') },
- * }))
- * ```
- */
-export type UserResolver = Omit<Resolver, 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter'>
-
 export type PluginFactoryOptions<
   /**
    * Name to be used for the plugin.
@@ -451,15 +382,20 @@ export type PluginFactoryOptions<
   resolver: TResolver
 }
 
+/**
+ * @deprecated
+ */
 export type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
-   * Unique name used for the plugin
-   * The name of the plugin follows the format scope:foo-bar or foo-bar, adding scope: can avoid naming conflicts with other plugins.
-   * @example @kubb/typescript
+   * Unique name used for the plugin.
+   * The name follows the format `scope:foo-bar` or `foo-bar` — adding a scope avoids conflicts with other plugins.
+   *
+   * @example Plugin name
+   * `'@kubb/typescript'`
    */
   name: TOptions['name']
   /**
-   * Options set for a specific plugin(see kubb.config.js), passthrough of options.
+   * Resolved options merged with output/include/exclude/override defaults for the current plugin.
    */
   options: TOptions['resolvedOptions'] & {
     output: Output
@@ -469,24 +405,43 @@ export type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOpti
   }
   /**
    * The resolver for this plugin.
-   * Composed by `getPreset` from the preset resolver and the user's `resolver` partial override.
+   * Set via `setResolver()` in `kubb:plugin:setup` or passed as a user option.
    */
   resolver?: TOptions['resolver']
   /**
    * The composed transformer for this plugin.
-   * Composed by `getPreset` from the preset's transformers and the user's `transformer` visitor.
-   * When a visitor method returns `null`/`undefined`, the preset transformer's result is used instead.
+   * Set via `setTransformer()` in `kubb:plugin:setup` or passed as a user option.
    */
   transformer?: Visitor
   /**
-   * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin is executed after these plugins.
-   * Can be used to validate dependent plugins.
+   * Plugin-level renderer factory. All generators that do not declare their own `renderer`
+   * inherit this value. A generator can explicitly opt out by setting `renderer: null`.
+   *
+   * @example
+   * ```ts
+   * import { jsxRenderer } from '@kubb/renderer-jsx'
+   * createPlugin((options) => ({
+   *   name: 'my-plugin',
+   *   renderer: jsxRenderer,
+   *   generators: [
+   *     { name: 'types', schema(node) { return <File>...</File> } },   // inherits jsxRenderer
+   *     { name: 'raw', renderer: null, schema(node) { return [...] } }, // explicit opt-out
+   *   ],
+   * }))
+   * ```
+   */
+  renderer?: RendererFactory
+  /**
+   * Generators declared directly on the plugin. Each generator's `renderer` takes precedence
+   * over `plugin.renderer`; set `renderer: null` on a generator to opt out of rendering even
+   * when the plugin declares a renderer.
    */
-  pre?: Array<string>
+  generators?: Array<Generator<any>>
   /**
-   * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin is executed before these plugins.
+   * Specifies the plugins that the current plugin depends on. The current plugin is executed after all listed plugins.
+   * An error is returned if any required dependency plugin is missing.
    */
-  post?: Array<string>
+  dependencies?: Array<string>
   /**
    * When `apply` is defined, the plugin is only activated when `apply(config)` returns `true`.
    * Inspired by Vite's `apply` option.
@@ -514,10 +469,11 @@ export type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOpti
   inject?: (this: PluginContext<TOptions>) => TOptions['context']
 }
 
+/**
+ * @deprecated
+ */
 export type UserPluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = UserPlugin<TOptions> & PluginLifecycle<TOptions>
 
-type UnknownUserPlugin = UserPlugin<PluginFactoryOptions<string, object, object, unknown, object>>
-
 /**
  * Handler for a single schema node. Used by the `schema` hook on a plugin.
  */
@@ -525,7 +481,7 @@ export type SchemaHook<TOptions extends PluginFactoryOptions = PluginFactoryOpti
   this: GeneratorContext<TOptions>,
   node: SchemaNode,
   options: TOptions['resolvedOptions'],
-) => PossiblePromise<KubbReactNode | Array<FileNode> | void>
+) => PossiblePromise<unknown | Array<FileNode> | void>
 
 /**
  * Handler for a single operation node. Used by the `operation` hook on a plugin.
@@ -534,7 +490,7 @@ export type OperationHook<TOptions extends PluginFactoryOptions = PluginFactoryO
   this: GeneratorContext<TOptions>,
   node: OperationNode,
   options: TOptions['resolvedOptions'],
-) => PossiblePromise<KubbReactNode | Array<FileNode> | void>
+) => PossiblePromise<unknown | Array<FileNode> | void>
 
 /**
  * Handler for all collected operation nodes. Used by the `operations` hook on a plugin.
@@ -543,23 +499,23 @@ export type OperationsHook<TOptions extends PluginFactoryOptions = PluginFactory
   this: GeneratorContext<TOptions>,
   nodes: Array<OperationNode>,
   options: TOptions['resolvedOptions'],
-) => PossiblePromise<KubbReactNode | Array<FileNode> | void>
-
+) => PossiblePromise<unknown | Array<FileNode> | void>
+/**
+ * @deprecated will be replaced with HookStylePlugin
+ */
 export type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
-   * Unique name used for the plugin
-   * @example @kubb/typescript
+   * Unique name used for the plugin.
+   *
+   * @example Plugin name
+   * `'@kubb/typescript'`
    */
   name: TOptions['name']
   /**
-   * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin is executed after these plugins.
-   * Can be used to validate dependent plugins.
-   */
-  pre?: Array<string>
-  /**
-   * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin is executed before these plugins.
+   * Specifies the plugins that the current plugin depends on. The current plugin is executed after all listed plugins.
+   * An error is returned if any required dependency plugin is missing.
    */
-  post?: Array<string>
+  dependencies?: Array<string>
   /**
    * Options set for a specific plugin(see kubb.config.js), passthrough of options.
    */
@@ -571,13 +527,12 @@ export type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>
   }
   /**
    * The resolver for this plugin.
-   * Composed by `getPreset` from the preset resolver and the user's `resolver` partial override.
+   * Set via `setResolver()` in `kubb:plugin:setup` or passed as a user option.
    */
   resolver: TOptions['resolver']
   /**
-   * The composed transformer for this plugin. Accessible via `context.transformer`.
-   * Composed by `getPreset` from the preset's transformers and the user's `transformer` visitor.
-   * When a visitor method returns `null`/`undefined`, the preset transformer's result is used instead.
+   * The composed transformer for this plugin.
+   * Set via `setTransformer()` in `kubb:plugin:setup` or passed as a user option.
    */
   transformer?: Visitor
 
@@ -591,6 +546,17 @@ export type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>
    * Used in diagnostic messages and version-conflict detection.
    */
   version?: string
+  /**
+   * Plugin-level renderer factory. All generators that do not declare their own `renderer`
+   * inherit this value. A generator can explicitly opt out by setting `renderer: null`.
+   */
+  renderer?: RendererFactory
+  /**
+   * Generators declared directly on the plugin. Each generator's `renderer` takes precedence
+   * over `plugin.renderer`; set `renderer: null` on a generator to opt out of rendering even
+   * when the plugin declares a renderer.
+   */
+  generators?: Array<Generator<any>>
 
   buildStart: (this: PluginContext<TOptions>) => PossiblePromise<void>
   /**
@@ -625,20 +591,22 @@ export type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>
    */
   inject: (this: PluginContext<TOptions>) => TOptions['context']
 }
-
+/**
+ * @deprecated
+ */
 export type PluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Plugin<TOptions> & PluginLifecycle<TOptions>
-
+/**
+ * @deprecated
+ */
 export type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
    * Called once per plugin at the start of its processing phase, before schema/operation/operations hooks run.
    * Use this to set up shared state, fetch remote data, or perform any async initialization.
-   * @type hookParallel
    */
   buildStart?: (this: PluginContext<TOptions>) => PossiblePromise<void>
   /**
    * Called once per plugin after all files have been written to disk.
    * Use this for post-processing, copying assets, or generating summary reports.
-   * @type hookParallel
    */
   buildEnd?: (this: PluginContext<TOptions>) => PossiblePromise<void>
   /**
@@ -666,23 +634,30 @@ export type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactor
    */
   operations?: OperationsHook<TOptions>
   /**
-   * Resolve to a Path based on a baseName(example: `./Pet.ts`) and directory(example: `./models`).
-   * Options can als be included.
-   * @type hookFirst
-   * @example ('./Pet.ts', './src/gen/') => '/src/gen/Pet.ts'
-   * @deprecated this will be replaced by resolvers
+   * Resolves a path from a baseName and directory.
+   * Options can also be included.
+   *
+   * @example
+   * `('./Pet.ts', './src/gen/') => '/src/gen/Pet.ts'`
+   *
+   * @deprecated Use resolvers instead.
    */
   resolvePath?: (this: PluginContext<TOptions>, baseName: FileNode['baseName'], mode?: 'single' | 'split', options?: TOptions['resolvePathOptions']) => string
   /**
-   * Resolve to a name based on a string.
+   * Resolves a display name from a raw string.
    * Useful when converting to PascalCase or camelCase.
-   * @type hookFirst
-   * @example ('pet') => 'Pet'
-   * @deprecated this will be replaced by resolvers
+   *
+   * @example
+   * `('pet') => 'Pet'`
+   *
+   * @deprecated Use resolvers instead.
    */
   resolveName?: (this: PluginContext<TOptions>, name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
 }
 
+/**
+ * @deprecated
+ */
 export type PluginLifecycleHooks = keyof PluginLifecycle
 
 export type PluginParameter<H extends PluginLifecycleHooks> = Parameters<Required<PluginLifecycle>[H]>
@@ -692,7 +667,7 @@ export type ResolvePathParams<TOptions = object> = {
   baseName: FileNode['baseName']
   mode?: 'single' | 'split'
   /**
-   * Options to be passed to 'resolvePath' 3th parameter
+   * Options passed as the third argument to `resolvePath`.
    */
   options?: TOptions
 }
@@ -702,15 +677,16 @@ export type ResolveNameParams = {
   pluginName?: string
   /**
    * Specifies the type of entity being named.
-   * - 'file' customizes the name of the created file (uses camelCase).
-   * - 'function' customizes the exported function names (uses camelCase).
-   * - 'type' customizes TypeScript types (uses PascalCase).
-   * - 'const' customizes variable names (uses camelCase).
-   * @default undefined
+   * - `'file'` — customizes the name of the created file (camelCase).
+   * - `'function'` — customizes the exported function names (camelCase).
+   * - `'type'` — customizes TypeScript type names (PascalCase).
+   * - `'const'` — customizes variable names (camelCase).
    */
   type?: 'file' | 'function' | 'type' | 'const'
 }
-
+/**
+ * @deprecated
+ */
 export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   config: Config
   /**
@@ -738,19 +714,16 @@ export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryO
   requirePlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]>
   requirePlugin(name: string): Plugin
   /**
-   * Only add when the file does not exist yet
+   * Add files only when they do not exist yet.
    */
   addFile: (...file: Array<FileNode>) => Promise<void>
   /**
-   * merging multiple sources into the same output file
+   * Merge multiple sources into the same output file.
    */
   upsertFile: (...file: Array<FileNode>) => Promise<void>
+  hooks: AsyncEventEmitter<KubbHooks>
   /**
-   * @deprecated use this.warn, this.error, this.info instead
-   */
-  events: AsyncEventEmitter<KubbEvents>
-  /**
-   * Current plugin
+   * The current plugin.
    */
   plugin: Plugin<TOptions>
   /**
@@ -765,17 +738,17 @@ export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryO
 
   /**
    * Emit a warning via the build event system.
-   * Shorthand for `this.events.emit('warn', message)`.
+   * Shorthand for `this.hooks.emit('kubb:warn', message)`.
    */
   warn: (message: string) => void
   /**
    * Emit an error via the build event system.
-   * Shorthand for `this.events.emit('error', error)`.
+   * Shorthand for `this.hooks.emit('kubb:error', error)`.
    */
   error: (error: string | Error) => void
   /**
    * Emit an info message via the build event system.
-   * Shorthand for `this.events.emit('info', message)`.
+   * Shorthand for `this.hooks.emit('kubb:info', message)`.
    */
   info: (message: string) => void
   /**
@@ -792,7 +765,7 @@ export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryO
        */
       inputNode: InputNode
       /**
-       * Return the adapter from `@kubb/ast`
+       * The adapter from `@kubb/ast`.
        */
       adapter: Adapter
     }
@@ -804,23 +777,27 @@ export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryO
   Kubb.PluginContext
 
 /**
- * Narrowed `PluginContext` used as the `this` type inside generator and plugin AST hook methods.
+ * Context object passed as the second argument to generator `schema`, `operation`, and
+ * `operations` methods.
  *
- * Generators and the `schema`/`operation`/`operations` plugin hooks are only invoked from
- * `runPluginAstHooks`, which already guards against a missing adapter. This type reflects
- * that guarantee — `this.adapter` and `this.inputNode` are always defined, so no runtime
- * checks or casts are needed inside the method bodies.
+ * Generators are only invoked from `runPluginAstHooks`, which already guards against a
+ * missing adapter. This type reflects that guarantee — `ctx.adapter` and `ctx.inputNode`
+ * are always defined, so no runtime checks or casts are needed inside generator bodies.
+ *
+ * `ctx.options` carries the per-node resolved options for `schema`/`operation` calls
+ * (after exclude/include/override filtering) and the plugin-level options for `operations`.
  */
 export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Omit<PluginContext<TOptions>, 'adapter' | 'inputNode'> & {
   adapter: Adapter
   inputNode: InputNode
+  options: TOptions['resolvedOptions']
 }
 /**
- * Specify the export location for the files and define the behavior of the output
+ * Configure generated file output location and behavior.
  */
 export type Output<_TOptions = unknown> = {
   /**
-   * Path to the output folder or file that will contain the generated code
+   * Path to the output folder or file that will contain generated code.
    */
   path: string
   /**
@@ -829,11 +806,13 @@ export type Output<_TOptions = unknown> = {
    */
   barrelType?: BarrelType | false
   /**
-   * Add a banner text in the beginning of every file
+   * Text or function appended at the start of every generated file.
+   * When a function, receives the current `InputNode` and must return a string.
    */
   banner?: string | ((node?: InputNode) => string)
   /**
-   * Add a footer text in the beginning of every file
+   * Text or function appended at the end of every generated file.
+   * When a function, receives the current `InputNode` and must return a string.
    */
   footer?: string | ((node?: InputNode) => string)
   /**
@@ -845,28 +824,27 @@ export type Output<_TOptions = unknown> = {
 
 export type UserGroup = {
   /**
-   * Defines the type where to group the files.
-   * - 'tag' groups files by OpenAPI tags.
-   * - 'path' groups files by OpenAPI paths.
-   * @default undefined
+   * Determines how files are grouped into subdirectories.
+   * - `'tag'` groups files by OpenAPI tags.
+   * - `'path'` groups files by OpenAPI paths.
    */
   type: 'tag' | 'path'
   /**
-   * Return the name of a group based on the group name, this is used for the file and name generation.
+   * Returns the subdirectory name for a given group value.
+   * Defaults to `${camelCase(group)}Controller` for tags and the first path segment for paths.
    */
   name?: (context: { group: string }) => string
 }
 
 export type Group = {
   /**
-   * Defines the type where to group the files.
-   * - 'tag' groups files by OpenAPI tags.
-   * - 'path' groups files by OpenAPI paths.
-   * @default undefined
+   * Determines how files are grouped into subdirectories.
+   * - `'tag'` groups files by OpenAPI tags.
+   * - `'path'` groups files by OpenAPI paths.
    */
   type: 'tag' | 'path'
   /**
-   * Return the name of a group based on the group name, this is used for the file and name generation.
+   * Returns the subdirectory name for a given group value.
    */
   name: (context: { group: string }) => string
 }
@@ -881,7 +859,7 @@ export type LoggerOptions = {
 /**
  * Shared context passed to all plugins, parsers, and other internals.
  */
-export type LoggerContext = AsyncEventEmitter<KubbEvents>
+export type LoggerContext = AsyncEventEmitter<KubbHooks>
 
 export type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
   name: string
@@ -899,46 +877,84 @@ export type CompatibilityPreset = 'default' | 'kubbV4'
 
 export type { Storage } from './createStorage.ts'
 export type { Generator } from './defineGenerator.ts'
-export type { KubbEvents } from './Kubb.ts'
+export type { HookStylePlugin, PluginHooks } from './definePlugin.ts'
+export type { Kubb, KubbHooks } from './Kubb.ts'
 
 /**
- * A preset bundles a name, a resolver, optional AST transformers,
- * and optional generators into a single reusable configuration object.
- *
- * @template TResolver - The concrete resolver type for this preset.
+ * Context passed to a hook-style plugin's `kubb:plugin:setup` handler.
+ * Provides methods to register generators, configure the resolver, transformer,
+ * and renderer, as well as access to the current build configuration.
  */
-export type Preset<TResolver extends Resolver = Resolver> = {
+export type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
-   * Unique identifier for this preset.
+   * Register a generator on this plugin. Generators are invoked during the AST walk
+   * (schema/operation/operations) exactly like generators declared statically on `createPlugin`.
    */
-  name: string
+  addGenerator<TElement = unknown>(generator: Generator<TFactory, TElement>): void
   /**
-   * The resolver used by this preset.
+   * Set or partially override the resolver for this plugin.
+   * The resolver controls file naming and path resolution for generated files.
+   *
+   * When `TFactory` is a concrete `PluginFactoryOptions` (e.g. `PluginClient`),
+   * the resolver parameter is typed to the plugin's own resolver type (e.g. `ResolverClient`).
    */
-  resolver: TResolver
+  setResolver(resolver: Partial<TFactory['resolver']>): void
   /**
-   * Optional AST visitors / transformers applied after resolving.
+   * Set the AST transformer (visitor) for this plugin.
+   * The transformer pre-processes nodes before they reach the generators.
    */
-  transformers?: Array<Visitor>
+  setTransformer(visitor: Visitor): void
   /**
-   * Optional generators used by this preset. Plugin implementations cast this
-   * to their concrete generator type.
+   * Set the renderer factory for this plugin.
+   * Used to process JSX elements returned by generators.
    */
-  generators?: Array<Generator<any>>
+  setRenderer(renderer: RendererFactory): void
+  /**
+   * Set the resolved options for the build loop. These options are merged into the
+   * normalized plugin's `options` object (which includes `output`, `exclude`, `override`).
+   *
+   * Call this in `kubb:plugin:setup` to provide the resolved options that generators
+   * and the build loop need (e.g., `enumType`, `optionalType`, `group`).
+   */
+  setOptions(options: TFactory['resolvedOptions']): void
+  /**
+   * Inject a raw file into the build output, bypassing the normal generation pipeline.
+   */
+  injectFile(file: Pick<FileNode, 'baseName' | 'path'> & { sources?: FileNode['sources'] }): void
   /**
-   * Optional printer factory used by this preset.
-   * The generator calls this function at render-time to produce a configured printer instance.
+   * Merge a partial config update into the current build configuration.
    */
-  printer?: (options: any) => Printer
+  updateConfig(config: Partial<Config>): void
+  /**
+   * The resolved build configuration at the time of setup.
+   */
+  config: Config
+  /**
+   * The plugin's own options as passed by the user.
+   */
+  options: TFactory['options']
 }
 
 /**
- * A named registry of presets, keyed by preset name.
- *
- * @template TResolver - The concrete resolver type shared by all presets in this registry.
- * @template TName - The union of valid preset name keys.
+ * Context passed to a hook-style plugin's `kubb:build:start` handler.
+ * Fires immediately before the plugin execution loop begins.
+ */
+export type KubbBuildStartContext = {
+  config: Config
+  adapter: Adapter
+  inputNode: InputNode
+  getPlugin(name: string): Plugin | undefined
+}
+
+/**
+ * Context passed to a hook-style plugin's `kubb:build:end` handler.
+ * Fires after all files have been written to disk.
  */
-export type Presets<TResolver extends Resolver = Resolver> = Record<CompatibilityPreset, Preset<TResolver>>
+export type KubbBuildEndContext = {
+  files: Array<FileNode>
+  config: Config
+  outputDir: string
+}
 
 type ByTag = {
   type: 'tag'
@@ -975,9 +991,22 @@ type ByContentType = {
   pattern: string | RegExp
 }
 
+/**
+ * A pattern filter that prevents matching nodes from being generated.
+ * Match by `tag`, `operationId`, `path`, `method`, `contentType`, or `schemaName`.
+ */
 export type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+
+/**
+ * A pattern filter that restricts generation to only matching nodes.
+ * Match by `tag`, `operationId`, `path`, `method`, `contentType`, or `schemaName`.
+ */
 export type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
 
+/**
+ * A pattern filter paired with partial option overrides applied when the pattern matches.
+ * Match by `tag`, `operationId`, `path`, `method`, `schemaName`, or `contentType`.
+ */
 export type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
   //TODO should be options: Omit<Partial<TOptions>, 'override'>
   options: Partial<TOptions>
@@ -1090,7 +1119,44 @@ export type ResolveBannerContext = {
   config: Config
 }
 
-export type { CLIOptions, ConfigInput } from './defineConfig.ts'
+/**
+ * CLI options derived from command-line flags.
+ */
+export type CLIOptions = {
+  /**
+   * Path to `kubb.config.js`.
+   */
+  config?: string
+  /**
+   * Enable watch mode for input files.
+   */
+  watch?: boolean
+  /**
+   * Logging verbosity for CLI usage.
+   * @default 'silent'
+   */
+  logLevel?: 'silent' | 'info' | 'debug'
+}
+
+/**
+ * All accepted forms of a Kubb configuration.
+ *
+ * Config is always `@kubb/core` {@link Config}.
+ * - `PossibleConfig` accepts `Config`/`Config[]`/promise or a no-arg config factory.
+ * - `PossibleConfig<TCliOptions>` accepts the same config forms or a config factory receiving `TCliOptions`.
+ */
+export type PossibleConfig<TCliOptions = undefined> =
+  | PossiblePromise<Config | Config[]>
+  | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Config[]>)
+
+/**
+ * All accepted forms of a Kubb configuration.
+ * @deprecated
+ * Kept for backward compatibility. Prefer `PossibleConfig<CLIOptions>` in new code.
+ */
+export type ConfigInput = PossibleConfig<CLIOptions>
+
+export type { BuildOutput } from './createKubb.ts'
 export type { Parser } from './defineParser.ts'
 export type { FunctionParamsAST } from './utils/FunctionParams.ts'
 export type { FileMetaBase } from './utils/getBarrelFiles.ts'