chore: mark the plugin API as experimental (#16276)

Marking the Plugin API as experimental in both docs and types,
previously it was internal.

Author: paulpopus

docs/plugins/plugin-api.mdx

@@ -10,10 +10,9 @@ Payload's plugin system is built around a simple contract: a plugin is a functio
 
 This page covers the advanced plugin API that makes plugins more powerful: execution ordering via `order`, typed cross-plugin communication via `RegisteredPlugins`, and the `definePlugin` helper that ties it all together.
 
-<Banner type="info">
-  The API on this page is marked `@internal` while we finalize the design. It is
-  safe to use across Payload's own plugins, but the surface may change before
-  being declared stable.
+<Banner type="warning">
+  The API on this page is **experimental**. It is safe to use across Payload's
+  own plugins, but the surface may change before being declared stable.
 </Banner>
 
 ## The basics still work

packages/payload/src/config/definePlugin.ts

@@ -19,6 +19,8 @@ function buildPluginsMap(plugins: Plugin[] | undefined): PluginsMap {
  * The `plugin` function receives a single object containing `config`, `plugins`
  * (a slug-keyed map of other plugins), and any user-provided options spread in.
  *
+ * @experimental
+ *
  * @example
  * // With options:
  * export const seoPlugin = definePlugin<SEOPluginOptions>({

packages/payload/src/config/types.ts

@@ -144,18 +144,23 @@ type Prettify<T> = {
   [K in keyof T]: T[K]
 } & NonNullable<unknown>
 
+/**
+ * @experimental The plugin API (`order`, `slug`, `options`) may change before being declared stable.
+ */
 export type Plugin = ((config: Config) => Config | Promise<Config>) & {
-  /** @internal Plugin options exposed for cross-plugin mutation. */
+  /** @experimental Plugin options exposed for cross-plugin mutation. */
   options?: Record<string, unknown>
-  /** @internal Execution order - lower values run first. Defaults to 0. */
+  /** @experimental Execution order - lower values run first. Defaults to 0. */
   order?: number
-  /** @internal Unique identifier for cross-plugin discovery via `config.plugins`. */
+  /** @experimental Unique identifier for cross-plugin discovery via `config.plugins`. */
   slug?: string
 }
 
 /**
  * A map of plugin slugs to Plugin instances, built from `config.plugins`.
  * Registered slugs (via `RegisteredPlugins` module augmentation) return typed options.
+ *
+ * @experimental
  */
 export type PluginsMap = {
   [K in keyof RegisteredPlugins]: ({ options: RegisteredPlugins[K] } & Plugin) | undefined

packages/payload/src/index.ts

@@ -271,6 +271,8 @@ export interface GeneratedTypes {}
  * Maps plugin slug to plugin options type, enabling typed cross-plugin
  * discovery via the `plugins` map passed to `definePlugin` functions.
  *
+ * @experimental
+ *
  * @example
  * // In a plugin package's index.ts:
  * declare module 'payload' {