@stencil/core 5.0.0-alpha.3 → 5.0.0-alpha.31

package/dist/declarations/stencil-public-compiler.d.ts

@@ -1,4 +1,6 @@
 import { ListenTargetOptions, ResolutionHandler } from "./stencil-public-runtime.js";
+import { InputOptions, SourceMap as RolldownSourceMap } from "rolldown";
+import "typescript";
 //#region src/utils/result.d.ts
 /**
  * A Result wraps up a success state and a failure state, allowing you to
@@ -45,15 +47,6 @@ type Err<T> = {
   isErr: true;
   value: T;
 };
-/**
- * Create an `Ok` given a value. This doesn't do any checking that the value is
- * 'ok-ish' since doing so would make an undue assumption about what is 'ok'.
- * Instead, this trusts the user to determine, at the call site, whether
- * something is `ok()` or `err()`.
- *
- * @param value the value to wrap up in an `Ok`
- * @returns an Ok wrapping the value
- */
 //#endregion
 //#region src/compiler/sys/in-memory-fs.d.ts
 /**
@@ -230,10 +223,6 @@ declare const createInMemoryFs: (sys: CompilerSystem) => {
  * `[ source, destination ]`
  */
 type FileCopyTuple = [string, string];
-/**
- * Collected instructions for all pending filesystem operations saved
- * to the in-memory filesystem.
- */
 /**
  * Results from committing pending filesystem operations
  */
@@ -244,14 +233,6 @@ interface FsCommitResults {
   dirsDeleted: string[];
   dirsAdded: string[];
 }
-/**
- * Given the current state of the in-memory proxy filesystem, collect all of
- * the changes that need to be made in order to commit the currently-pending
- * operations (e.g. write, copy, delete) to the OS filesystem.
- *
- * @param items the storage data structure for the in-memory FS cache
- * @returns a collection of all the operations that need to be done
- */
 //#endregion
 //#region src/declarations/stencil-public-docs.d.ts
 /**
@@ -274,6 +255,13 @@ interface JsonDocs {
    * The metadata for the JSDocs for each component in a Stencil project
    */
   components: JsonDocsComponent[];
+  /**
+   * Project-level usage content, collected from markdown files in a `usage`
+   * directory at the project's {@link Config.srcDir} root (as opposed to
+   * per-component usage content, which lives in {@link JsonDocsComponent.usage}).
+   * Keyed by file name (without extension), same shape as component usage.
+   */
+  usage?: JsonDocsUsage;
   /**
    * The timestamp at which the metadata was generated, in the format YYYY-MM-DDThh:mm:ss
    */
@@ -670,6 +658,103 @@ interface PrintLine {
   errorCharStart: number;
   errorLength?: number;
 }
+interface BuildFeatures {
+  style: boolean;
+  mode: boolean;
+  formAssociated: boolean;
+  shadowDom: boolean;
+  shadowDelegatesFocus: boolean;
+  shadowModeClosed: boolean;
+  shadowSlotAssignmentManual: boolean;
+  scoped: boolean;
+  /**
+   * Every component has a render function
+   */
+  allRenderFn: boolean;
+  /**
+   * At least one component has a render function
+   */
+  hasRenderFn: boolean;
+  vdomRender: boolean;
+  vdomAttribute: boolean;
+  vdomClass: boolean;
+  vdomFunctional: boolean;
+  vdomKey: boolean;
+  vdomListener: boolean;
+  vdomPropOrAttr: boolean;
+  vdomRef: boolean;
+  vdomStyle: boolean;
+  vdomText: boolean;
+  vdomXlink: boolean;
+  vdomSignals: boolean;
+  slotRelocation: boolean;
+  patchAll: boolean;
+  patchChildren: boolean;
+  patchClone: boolean;
+  patchInsert: boolean;
+  slot: boolean;
+  svg: boolean;
+  element: boolean;
+  event: boolean;
+  hostListener: boolean;
+  hostListenerTargetWindow: boolean;
+  hostListenerTargetDocument: boolean;
+  hostListenerTargetBody: boolean;
+  hostListenerTarget: boolean;
+  method: boolean;
+  prop: boolean;
+  propChangeCallback: boolean;
+  propMutable: boolean;
+  state: boolean;
+  member: boolean;
+  updatable: boolean;
+  propBoolean: boolean;
+  propNumber: boolean;
+  propString: boolean;
+  serializer: boolean;
+  deserializer: boolean;
+  lifecycle: boolean;
+  asyncLoading: boolean;
+  observeAttribute: boolean;
+  reflect: boolean;
+  taskQueue: boolean;
+}
+interface BuildConditionals extends Partial<BuildFeatures> {
+  hotModuleReplacement?: boolean;
+  isDebug?: boolean;
+  isTesting?: boolean;
+  isDev?: boolean;
+  devTools?: boolean;
+  invisiblePrehydration?: boolean;
+  hydrateServerSide?: boolean;
+  hydrateClientSide?: boolean;
+  lifecycleDOMEvents?: boolean;
+  cssAnnotations?: boolean;
+  lazyLoad?: boolean;
+  profile?: boolean;
+  constructableCSS?: boolean;
+  /** True when `compat.lightDomPatches === true` - enables `applyLightDomPatches` shortcut. */
+  lightDomPatches?: boolean;
+  /** Patch `childNodes`/`children` getters on light-dom slotted components. */
+  slotChildNodes?: boolean;
+  /** Patch `cloneNode()` on light-dom slotted components. */
+  slotCloneNode?: boolean;
+  /** Patch `appendChild`/`insertBefore`/`removeChild` on light-dom slotted components. */
+  slotDomMutations?: boolean;
+  /** Patch `textContent` on light-dom slotted components. */
+  slotTextContent?: boolean;
+  hydratedAttribute?: boolean;
+  hydratedClass?: boolean;
+  hydratedSelectorName?: string;
+  /** True when a global-style input contains `@import "stencil-hydrate"` - suppresses dynamic style injection in the loader. */
+  staticHydrationStyles?: boolean;
+  initializeNextTick?: boolean;
+  asyncQueue?: boolean;
+  additionalTagTransformers?: boolean | 'prod';
+  signalBacking?: boolean;
+  /** True when JSX signal bypass is active - text nodes and attributes backed by Signal objects update the DOM directly. Auto-enabled when `signalBacking: true`. */
+  vdomSignals?: boolean;
+}
 type ModuleFormat = 'amd' | 'cjs' | 'es' | 'iife' | 'system' | 'umd' | 'commonjs' | 'esm' | 'module' | 'systemjs';
 interface RolldownResultModule {
   id: string;
@@ -715,15 +800,17 @@ interface BuildCtx {
   hasScriptChanges: boolean;
   hasStyleChanges: boolean;
   hasWarning: boolean;
-  hydrateAppFilePath: string;
+  ssrAppFilePath: string;
   indexBuildCount: number;
   indexDoc: Document;
+  /** All non-entry HTML files found in srcDir, keyed by path relative to srcDir */
+  htmlDocs: Map<string, Document>;
   isRebuild: boolean;
   /**
    * A collection of Stencil's intermediate representation of components, tied to the current build
    */
   moduleFiles: Module[];
-  packageJson: PackageJsonData;
+  packageJson: PackageJsonData | null;
   pendingCopyTasks: Promise<CopyResults>[];
   progress(task: BuildTask): void;
   requiresFullBuild: boolean;
@@ -767,8 +854,6 @@ interface CompilerBuildStats {
   options: {
     minifyJs: boolean;
     minifyCss: boolean;
-    hashFileNames: boolean;
-    hashedFileNameLength: number;
   };
   formats: {
     esmBrowser: ReadonlyArray<CompilerBuildStatBundle>;
@@ -817,16 +902,6 @@ interface RolldownChunkResult {
   moduleFormat: ModuleFormat;
   map?: RolldownSourceMap;
 }
-interface RolldownSourceMap {
-  file: string;
-  mappings: string;
-  names: string[];
-  sources: string[];
-  sourcesContent: string[];
-  version: number;
-  toString(): string;
-  toUrl(): string;
-}
 interface BundleModule {
   entryKey: string;
   rolldownResult: RolldownChunkResult;
@@ -862,12 +937,32 @@ interface CollectionCompilerMeta {
   bundles?: {
     components: string[];
   }[];
+  buildFlags?: Partial<BuildConditionals>;
 }
 interface CollectionCompilerVersion {
   name: string;
   version: string;
   typescriptVersion?: string;
 }
+/**
+ * A memoized result of the SASS + Lightning CSS transformation for a single stylesheet, keyed by
+ * the annotated Rolldown import id (e.g. `/path/to/comp.scss?tag=ion-button&encapsulation=shadow`).
+ *
+ * Storing this allows all output targets (customElements, lazy, hydrate) that process the same
+ * stylesheets to share a single computation instead of repeating it N times.
+ */
+interface CssTransformCacheEntry {
+  /** Resolved file ID after plugin (SASS) transforms */
+  pluginTransformId: string;
+  /** CSS source produced by the SASS / plugin pipeline */
+  pluginTransformCode: string;
+  /** File dependencies discovered during the SASS transform (e.g. `@import`-ed partials) */
+  pluginTransformDependencies: string[];
+  /** Diagnostics emitted during the plugin transform pass */
+  pluginTransformDiagnostics: Diagnostic[];
+  /** Full output of the subsequent `transformCssToEsm` call */
+  cssTransformOutput: TransformCssToEsmOutput;
+}
 interface CompilerCtx {
   version: number;
   activeBuildId: number;
@@ -880,7 +975,8 @@ interface CompilerCtx {
   addWatchFile: (path: string) => void;
   cache: Cache;
   cssModuleImports: Map<string, string[]>;
-  cachedGlobalStyle: string;
+  /** Cache of built global styles, keyed by input file path */
+  globalStyleCache: Map<string, string>;
   collections: CollectionCompilerMeta[];
   compilerOptions: any;
   events: BuildEvents;
@@ -894,7 +990,7 @@ interface CompilerCtx {
   moduleMap: ModuleMap;
   nodeMap: NodeMap;
   resolvedCollections: Set<string>;
-  rolldownCacheHydrate: any;
+  rolldownCacheSsr: any;
   rolldownCacheLazy: any;
   rolldownCacheNative: any;
   styleModeNames: Set<string>;
@@ -902,6 +998,32 @@ interface CompilerCtx {
   changedFiles: Set<string>;
   worker?: CompilerWorkerContext;
   rolldownCache: Map<string, any>;
+  /**
+   * Cross-build cache for {@link ts.transpileModule} results.
+   * Keyed by `"${bundleId}:${normalizedFilePath}"`. Invalidated for any
+   * file that appears in {@link changedModules} after TypeScript re-emits.
+   * @see transpileCache in compiler-ctx.ts
+   */
+  transpileCache: Map<string, {
+    outputText: string;
+    sourceMapText: string | null;
+  }>;
+  /**
+   * Cross-build cache of the last style text pushed to the HMR client.
+   * Keyed by getScopeId result (e.g. "ion-accordion$ios"). Used by
+   * extTransformsPlugin to avoid re-pushing unchanged styles on every rebuild.
+   */
+  prevStylesMap: Map<string, string>;
+  /**
+   * Cross-output-target cache for the SASS + Lightning CSS computation.
+   * Keyed by the annotated Rolldown import id. Null entries indicate that the
+   * source file could not be read (propagated as a `null` return from the
+   * transform hook).
+   *
+   * Entries are invalidated in `invalidateRolldownCaches` whenever a
+   * source file or one of its SASS dependencies is modified.
+   */
+  cssTransformCache: Map<string, CssTransformCacheEntry | null>;
   reset(): void;
 }
 type NodeMap = WeakMap<any, ComponentCompilerMeta>;
@@ -962,10 +1084,12 @@ interface ComponentCompilerFeatures {
   hasVdomStyle: boolean;
   hasVdomText: boolean;
   hasVdomXlink: boolean;
+  hasSignalsImport: boolean;
   hasWatchCallback: boolean;
   htmlAttrNames: string[];
   htmlTagNames: string[];
   htmlParts: string[];
+  htmlSlots: string[];
   isUpdateable: boolean;
   /**
    * A plain component is one that doesn't have:
@@ -1059,6 +1183,7 @@ interface ComponentCompilerMeta extends ComponentCompilerFeatures {
   states: ComponentCompilerState[];
   styleDocs: CompilerStyleDoc[];
   styles: StyleCompiler[];
+  globalStyles: ComponentGlobalStyle[];
   tagName: string;
   virtualProperties: ComponentCompilerVirtualProperty[];
   watchers: ComponentCompilerChangeHandler[];
@@ -1075,7 +1200,7 @@ type Encapsulation = 'shadow' | 'scoped' | 'none';
  * These enable proper slot behavior when not using native Shadow DOM.
  */
 interface ComponentPatches {
-  /** Apply all slot patches (equivalent to experimentalSlotFixes) */
+  /** Apply all slot patches (equivalent to lightDomPatches) */
   all?: boolean;
   /** Patch child node accessors (children, firstChild, lastChild, etc.) */
   children?: boolean;
@@ -1135,6 +1260,11 @@ interface ComponentCompilerPropertyComplexType {
    * annotation in the original source file.
    */
   references: ComponentCompilerTypeReferences;
+  /**
+   * @internal TypeScript AST node used for semantic type analysis during compilation.
+   * Not serialized, only used internally for improved type renaming logic.
+   */
+  _astNode?: any;
 }
 /**
  * A record of `ComponentCompilerTypeReference` entities.
@@ -1228,6 +1358,11 @@ interface ComponentCompilerMethodComplexType {
   parameters: JsonDocMethodParameter[];
   references: ComponentCompilerTypeReferences;
   return: string;
+  /**
+   * @internal TypeScript AST method node used for semantic type analysis during compilation.
+   * Not serialized, only used internally for improved type renaming logic.
+   */
+  _astNode?: any;
 }
 interface ComponentCompilerChangeHandler {
   propName: string;
@@ -1363,6 +1498,7 @@ interface Module {
   htmlAttrNames: string[];
   htmlTagNames: string[];
   htmlParts: string[];
+  htmlSlots: string[];
   isCollectionDependency: boolean;
   isLegacy: boolean;
   jsFilePath: string;
@@ -1392,6 +1528,7 @@ interface Module {
   hasVdomStyle: boolean;
   hasVdomText: boolean;
   hasVdomXlink: boolean;
+  hasSignalsImport: boolean;
 }
 interface PrerenderUrlResults {
   anchorUrls: string[];
@@ -1404,7 +1541,7 @@ interface PrerenderUrlRequest {
   baseUrl: string;
   componentGraphPath: string;
   devServerHostUrl: string;
-  hydrateAppFilePath: string;
+  ssrAppFilePath: string;
   isDebug: boolean;
   prerenderConfigPath: string;
   staticSite: boolean;
@@ -1424,6 +1561,12 @@ interface ExternalStyleCompiler {
   relativePath: string;
   originalComponentPath: string;
 }
+interface ComponentGlobalStyle {
+  /** Absolute path to the CSS file, or null for inline styles */
+  absolutePath: string | null;
+  /** Raw inline CSS string, or null for file-based styles */
+  styleStr: string | null;
+}
 /**
  * Input CSS to be transformed into ESM
  */
@@ -1487,7 +1630,6 @@ interface PackageJsonData {
   browser?: string;
   module?: string;
   'jsnext:main'?: string;
-  'collection:main'?: string;
   unpkg?: string;
   collection?: string;
   types?: string;
@@ -1614,20 +1756,6 @@ interface StencilConfig {
    * @default false
    */
   generateExportMaps?: boolean;
-  /**
-   * When the hashFileNames config is set to true, and it is a production build,
-   * the hashedFileNameLength config is used to determine how many characters the file name's hash should be.
-   */
-  hashedFileNameLength?: number;
-  /**
-   * During production builds, the content of each generated file is hashed to represent the content,
-   * and the hashed value is used as the filename. If the content isn't updated between builds,
-   * then it receives the same filename. When the content is updated, then the filename is different.
-   *
-   * By doing this, deployed apps can "forever-cache" the build directory and take full advantage of
-   * content delivery networks (CDNs) and heavily caching files for faster apps.
-   */
-  hashFileNames?: boolean;
   /**
    * The namespace config is a string representing a namespace for the app.
    * For apps that are not meant to be a library of reusable components,
@@ -1668,16 +1796,6 @@ interface StencilConfig {
    * This behavior defaults to `true`, but may be opted-out of by setting this flag to `false`.
    */
   transformAliasedImportPaths?: boolean;
-  /**
-   * When `true`, Stencil will suppress diagnostics which warn about public members using reserved names
-   * (for example, decorating a method named `focus` with `@Method()`). Defaults to `false`.
-   */
-  suppressReservedPublicNameWarnings?: boolean;
-  /**
-   * When `true`, we will validate a project's `package.json` based on the output target the user has designated
-   * as `isPrimaryPackageOutputTarget: true` in their Stencil config.
-   */
-  validatePrimaryPackageOutputTarget?: boolean;
   /**
    * Passes custom configuration down to the "@rolldown/plugin-node-resolve" that Stencil uses under the hood.
    * For further information: https://stenciljs.com/docs/module-bundling
@@ -1697,24 +1815,24 @@ interface StencilConfig {
    * Defaults to `false` in dev mode and `true` in production mode.
    */
   minifyCss?: boolean;
-  /**
-   * Forces Stencil to run in `dev` mode if the value is `true` and `production` mode
-   * if it's `false`.
-   *
-   * Defaults to `false` (ie. production) unless the `--dev` flag is used in the CLI.
-   */
-  devMode?: boolean;
   /**
    * Object to provide a custom logger. By default a `logger` is already provided for the
    * platform the compiler is running on, such as NodeJS or a browser.
    */
   logger?: Logger;
   /**
-   * Config to add extra runtime for DOM features that require more polyfills. Note
-   * that not all DOM APIs are fully polyfilled when using the slot polyfill. These
-   * are opt-in since not all users will require the additional runtime.
+   * Compatibility and workaround flags for framework/bundler edge cases
+   * and rarely-needed diagnostic suppressions.
    */
-  extras?: ConfigExtras;
+  compat?: ConfigCompat;
+  /**
+   * Replace `@State` and `@Prop` internals with `@preact/signals-core` signal primitives.
+   * Enables cross-framework reactive interop - component state becomes subscribable by
+   * Solid, Angular, Preact and any TC39-signal-compatible library without event/attribute
+   * roundtrips. No API changes required in component code.
+   * Defaults to `false`.
+   */
+  signalBacking?: boolean;
   /**
    * The hydrated flag identifies if a component and all of its child components
    * have finished hydrating. This helps prevent any flash of unstyled content (FOUC)
@@ -1779,14 +1897,6 @@ interface StencilConfig {
     after?: any[];
   };
   entryComponentsHint?: string[];
-  /**
-   * Sets whether Stencil will write files to `dist/` during the build or not.
-   *
-   * By default this value is set to the opposite value of {@link devMode},
-   * i.e. it will be `true` when building for production and `false` when
-   * building for development.
-   */
-  buildDist?: boolean;
   buildLogFilePath?: string;
   devInspector?: boolean;
   devServer?: StencilDevServerConfig;
@@ -1814,7 +1924,7 @@ interface StencilConfig {
    * An array of component tag names to exclude from production builds.
    * Useful to remove test, demo or experimental components from final output.
    *
-   * **Note:** Exclusion only applies to production builds (default, or when `--prod` is used).
+   * **Note:** Exclusion only applies to production builds (the default).
    * Development builds (with `--dev` flag) will include all components to support local testing.
    *
    * Supports glob patterns for matching multiple components:
@@ -1838,14 +1948,78 @@ interface StencilConfig {
    * Set whether unused dependencies should be excluded from the built output.
    */
   excludeUnusedDependencies?: boolean;
-  stencilCoreResolvedId?: string;
+  /**
+   * Declares the set of valid style "modes" (e.g. `ios`, `md`) used by mode-keyed
+   * `styleUrls`/`styles` in `@Component()`. When set, the compiler validates that
+   * every mode key used in a component matches one of these entries, catching typos
+   * at build time. Entries marked `required` must be present on every component that
+   * defines any mode-keyed styles.
+   *
+   * @example
+   * ```ts
+   * export const config: Config = {
+   *   modes: ['ios', { mode: 'md', required: true }],
+   * };
+   * ```
+   *
+   * @default []
+   */
+  modes?: (string | ModeConfig)[];
+  /**
+   * Explicitly declare which npm packages are Stencil collections to be re-bundled into this project.
+   *
+   * Without this option, collection ingestion is triggered only by a side-effect import:
+   * ```ts
+   * import '@ionic/core';
+   * ```
+   * @example
+   * ```ts
+   * export const config: Config = {
+   *   collections: ['@ionic/core', '@my-org/design-system'],
+   * };
+   * ```
+   *
+   * @default []
+   */
+  collections?: string[];
 }
-interface ConfigExtrasBase {
+/**
+ * DOM patches for light-dom / scoped components that use `<slot>`.
+ *
+ * These patches shield the component's slot machinery from framework DOM mutations
+ * (e.g. when Angular or React insert / remove nodes they route directly to the host
+ * element, bypassing the slot polyfill) and prevent hydration errors when a framework
+ * encounters Stencil's internal slot reference nodes during SSR reconciliation.
+ *
+ * Patches are only applied at runtime when a component is both non-shadow **and**
+ * declares at least one `<slot>`, so enabling them has no effect on pure shadow-DOM
+ * components.
+ *
+ * Set to `true` (default) to enable all patches, `false` to disable all, or an object
+ * for granular control.
+ */
+type LightDomPatches = {
+  /** Patches `childNodes`/`children` getters to return only slotted content. */
+  childNodes?: boolean;
+  /** Patches `cloneNode()` to correctly deep-clone slotted content. */
+  cloneNode?: boolean;
+  /** Patches `appendChild()`, `insertBefore()`, and `removeChild()` to route to the correct slot. */
+  domMutations?: boolean;
+  /** Patches `textContent` to act like shadow DOM (reads/writes slotted text only). */
+  textContent?: boolean;
+};
+/**
+ * Compatibility and workaround flags, primarily for shielding non-shadow DOM components
+ * from consuming frameworks that mutate internals they don't know about, plus other
+ * framework/bundler integration edge cases and rarely-needed diagnostic suppressions.
+ * These are opt-in behaviors that aren't needed by every project.
+ */
+interface ConfigCompat {
   /**
    * Projects that use a Stencil library built using the `dist` output target may have trouble lazily
    * loading components when using a bundler such as Vite or Parcel. Setting this flag to `true` will change how Stencil
    * lazily loads components in a way that works with additional bundlers. Setting this flag to `true` will increase
-   * the size of the compiled output. Defaults to `false`.
+   * the size of the compiled output. Defaults to `true`.
    */
   enableImportInjection?: boolean;
   /**
@@ -1860,70 +2034,27 @@ interface ConfigExtrasBase {
    */
   initializeNextTick?: boolean;
   /**
-   * Adds `transformTag` calls to css strings and querySelector(All) calls
+   * Adds `transformTag` calls to css strings and querySelector(All) calls.
+   * Use `'prod'` to enable only in production builds.
    */
   additionalTagTransformers?: boolean | 'prod';
   /**
-   * Experimental flag.
-   * Updates the behavior of scoped components to align more closely with the behavior of the native
-   * Shadow DOM when using `slot`s.
-   * Defaults to `false`.
-   */
-  experimentalScopedSlotChanges?: boolean;
-  /**
-   * By default Stencil turns the stylesheet provided to `globalStyle` into a constructable stylesheet
-   * and adds it to each component when rendered on the client which can be useful for sharing styles
-   * efficiently across components.
-   *
-   * If you want Stencil to also add the `globalStyle` to each component when rendering on the server
-   * then set this to `true`. If your `globalStyle` sheet is large then doing this may bloat the size
-   * of your SSR output when using declarative-shadow-dom.
-   *
-   * Setting this to `false` will prevent Stencil from adding any `globalStyle` to each component.
-   *
-   * Defaults to `'client'`.
-   */
-  addGlobalStyleToComponents?: boolean | 'client';
-}
-type ConfigExtrasSlotFixes<ExperimentalFixesEnabled extends boolean, IndividualFlags extends boolean> = {
-  /**
-   * By default, the slot polyfill does not update `appendChild()` so that it appends
-   * new child nodes into the correct child slot like how shadow dom works. This is an opt-in
-   * polyfill for those who need it when using `element.appendChild(node)` and expecting the
-   * child to be appended in the same location shadow dom would. This is not required for
-   * IE11 or Edge 18, but can be enabled if the app is using `appendChild()`. Defaults to `false`.
-   */
-  appendChildSlotFix?: IndividualFlags;
-  /**
-   * By default, the runtime does not polyfill `cloneNode()` when cloning a component
-   * that uses the slot polyfill. This is an opt-in polyfill for those who need it.
-   * This is not required for IE11 or Edge 18, but can be enabled if the app is using
-   * `cloneNode()` and unexpected node are being cloned due to the slot polyfill
-   * simulating shadow dom. Defaults to `false`.
-   */
-  cloneNodeFix?: IndividualFlags;
-  /**
-   * Experimental flag to align the behavior of invoking `textContent` on a scoped component to act more like a
-   * component that uses the shadow DOM. Defaults to `false`
+   * DOM patches for light-dom / scoped components that use `<slot>`.
+   * See {@link LightDomPatches} for granular control. Defaults to `true`.
    */
-  scopedSlotTextContentFix?: IndividualFlags;
+  lightDomPatches?: boolean | LightDomPatches;
   /**
-   * For browsers that do not support shadow dom (IE11 and Edge 18 and below), slot is polyfilled
-   * to simulate the same behavior. However, the host element's `childNodes` and `children`
-   * getters are not patched to only show the child nodes and elements of the default slot.
-   * Defaults to `false`.
+   * When `true`, Stencil will suppress diagnostics which warn about public members using reserved names
+   * (for example, decorating a method named `focus` with `@Method()`). Defaults to `false`.
    */
-  slotChildNodesFix?: IndividualFlags;
+  suppressPublicNameWarnings?: boolean;
   /**
-   * Enables all slot-related fixes such as {@link slotChildNodesFix}, and
-   * {@link scopedSlotTextContentFix}.
+   * When `true`, Stencil will suppress diagnostics which warn about event names conflicting with native DOM event names. Defaults to `false`.
    */
-  experimentalSlotFixes?: ExperimentalFixesEnabled;
-};
-type ConfigExtras = ConfigExtrasBase & (ConfigExtrasSlotFixes<true, true> | ConfigExtrasSlotFixes<false, boolean>);
+  suppressEventNameWarnings?: boolean;
+}
 interface Config extends StencilConfig {
   buildAppCore?: boolean;
-  buildDocs?: boolean;
   configPath?: string;
   writeLog?: boolean;
   devServer?: DevServerConfig;
@@ -1937,6 +2068,11 @@ interface Config extends StencilConfig {
   tsWatchOptions?: any;
   _isValidated?: boolean;
   _isTesting?: boolean;
+  /**
+   * Internal flag set when --docs CLI flag is used.
+   * Forces docs output targets to build even in dev mode.
+   */
+  _docsFlag?: boolean;
   /**
    * Whether running in a CI environment (disables interactive features, adjusts worker count)
    */
@@ -2015,11 +2151,11 @@ type UnvalidatedConfig = Loose<Config>;
  * type ReqFieldFoo = RequireFields<Foo, 'bar'>; // { bar: number, baz?: string }
  * ```
  */
-type RequireFields<T, K extends keyof T> = T & { [P in K]-?: T[P] };
+type RequireFields<T, K extends keyof T> = T & { [P in K]-?: T[P]; };
 /**
  * Fields in {@link Config} to make required for {@link ValidatedConfig}
  */
-type StrictConfigFields = keyof Pick<Config, 'cacheDir' | 'devMode' | 'devServer' | 'extras' | 'fsNamespace' | 'hashFileNames' | 'hashedFileNameLength' | 'hydratedFlag' | 'logLevel' | 'logger' | 'minifyCss' | 'minifyJs' | 'namespace' | 'outputTargets' | 'packageJsonFilePath' | 'rolldownConfig' | 'rootDir' | 'srcDir' | 'srcIndexHtml' | 'sys' | 'transformAliasedImportPaths' | 'validatePrimaryPackageOutputTarget'>;
+type StrictConfigFields = keyof Pick<Config, 'cacheDir' | 'devServer' | 'compat' | 'fsNamespace' | 'hydratedFlag' | 'logLevel' | 'logger' | 'minifyCss' | 'minifyJs' | 'namespace' | 'outputTargets' | 'packageJsonFilePath' | 'rolldownConfig' | 'rootDir' | 'srcDir' | 'srcIndexHtml' | 'sys' | 'transformAliasedImportPaths'>;
 /**
  * A version of {@link Config} that makes certain fields required. This type represents a valid configuration entity.
  * When a configuration is received by the user, it is a bag of unverified data. In order to make stricter guarantees
@@ -2027,8 +2163,24 @@ type StrictConfigFields = keyof Pick<Config, 'cacheDir' | 'devMode' | 'devServer
  * validations have occurred at runtime.
  */
 type ValidatedConfig = RequireFields<Config, StrictConfigFields> & {
+  /**
+   * Whether the build is running in development mode.
+   * Set by the `--dev` CLI flag. Not user-configurable in `stencil.config.ts`.
+   */
+  devMode: boolean;
   sourceMap: boolean;
 };
+interface ModeConfig {
+  /**
+   * The mode name, matched against `styleUrls`/`styles` object keys in `@Component()`.
+   */
+  mode: string;
+  /**
+   * When `true`, every component that defines mode-keyed `styleUrls` or `styles`
+   * must include this mode. Defaults to `false`.
+   */
+  required?: boolean;
+}
 interface HydratedFlag {
   /**
    * Defaults to `hydrated`.
@@ -2231,11 +2383,11 @@ interface PrerenderConfig {
    * Run after each `document` is hydrated, but before it is serialized
    * into an HTML string. Hook is passed the `document` and its `URL`.
    */
-  afterHydrate?(document: Document, url: URL, results: PrerenderUrlResults): any | Promise<any>;
+  afterSsr?(document: Document, url: URL, results: PrerenderUrlResults): any | Promise<any>;
   /**
    * Run before each `document` is hydrated. Hook is passed the `document` it's `URL`.
    */
-  beforeHydrate?(document: Document, url: URL): any | Promise<any>;
+  beforeSsr?(document: Document, url: URL): any | Promise<any>;
   /**
    * Runs after the template Document object has serialize into an
    * HTML formatted string. Returns an HTML string to be used as the
@@ -2279,9 +2431,9 @@ interface PrerenderConfig {
    */
   filePath?(url: URL, filePath: string): string;
   /**
-   * Returns the hydrate options to use for each individual prerendered page.
+   * Returns the prerender options to use for each individual prerendered page.
    */
-  hydrateOptions?(url: URL): PrerenderHydrateOptions;
+  prerenderOptions?(url: URL): PrerenderOptions;
   /**
    * Returns the template file's content. The template is the base
    * HTML used for all prerendered pages.
@@ -2305,7 +2457,7 @@ interface PrerenderConfig {
    */
   trailingSlash?: boolean;
 }
-interface HydrateDocumentOptions {
+interface SsrDocumentOptions {
   /**
    * Build ID that will be added to `<html data-stencil-build="BUILD_ID">`. By default
    * a random ID will be generated
@@ -2322,7 +2474,7 @@ interface HydrateDocumentOptions {
    * JavaScript to read the structure of the HTML and rebuild each
    * component. Defaults to `true`.
    */
-  clientHydrateAnnotations?: boolean;
+  clientSsrAnnotations?: boolean;
   /**
    * Constrain `setTimeout()` to 1ms, but still async. Also
    * only allows `setInterval()` to fire once, also constrained to 1ms.
@@ -2421,10 +2573,19 @@ interface HydrateDocumentOptions {
     default: 'declarative-shadow-dom' | 'scoped';
   } | boolean;
 }
-interface SerializeDocumentOptions extends HydrateDocumentOptions {
+/**
+ * Backwards compat for v4
+ * @deprecated - use SsrDocumentOptions instead
+ */
+interface HydrateDocumentOptions extends SsrDocumentOptions {}
+interface SerializeDocumentOptions extends SsrDocumentOptions {
   /**
    * Runs after the `document` has been hydrated.
    */
+  afterSsr?(document: any): any | Promise<any>;
+  /**
+   * @deprecated Use `afterSsr` instead.
+   */
   afterHydrate?(document: any): any | Promise<any>;
   /**
    * Sets an approximate line width the HTML should attempt to stay within.
@@ -2437,6 +2598,10 @@ interface SerializeDocumentOptions extends HydrateDocumentOptions {
   /**
    * Runs before the `document` has been hydrated.
    */
+  beforeSsr?(document: any): any | Promise<any>;
+  /**
+   * @deprecated Use `beforeSsr` instead.
+   */
   beforeHydrate?(document: any): any | Promise<any>;
   /**
    * Format the HTML in a nicely indented format.
@@ -2474,12 +2639,17 @@ interface SerializeDocumentOptions extends HydrateDocumentOptions {
    */
   modes?: ResolutionHandler[];
 }
-interface HydrateFactoryOptions extends SerializeDocumentOptions {
+interface SsrFactoryOptions extends SerializeDocumentOptions {
   serializeToHtml: boolean;
   destroyWindow: boolean;
   destroyDocument: boolean;
 }
-interface PrerenderHydrateOptions extends SerializeDocumentOptions {
+/**
+ * Backwards compat for v4
+ * @deprecated - use SsrFactoryOptions instead
+ */
+interface HydrateFactoryOptions extends SsrFactoryOptions {}
+interface PrerenderOptions extends SerializeDocumentOptions {
   /**
    * Adds `<link rel="modulepreload">` for modules that will eventually be requested.
    * Defaults to `true`.
@@ -2514,6 +2684,11 @@ interface PrerenderHydrateOptions extends SerializeDocumentOptions {
    */
   staticDocument?: boolean;
 }
+/**
+ * v4 backwards compat
+ * @deprecated - use PrerenderOptions instead
+ */
+interface PrerenderHydrateOptions extends PrerenderOptions {}
 interface RobotsTxtOpts {
   urls: string[];
   sitemapUrl: string;
@@ -2822,18 +2997,18 @@ interface ResolveModuleIdResults {
  * A controller which provides for communication and coordination between
  * threaded workers.
  */
-interface WorkerMainController {
+interface WorkerMainController<T extends Record<string, (...args: any[]) => Promise<any>> = Record<string, (...args: any[]) => Promise<any>>> {
   /**
    * Send a given set of arguments to a worker
    */
-  send(...args: any[]): Promise<any>;
+  send<K extends keyof T>(methodName: K, ...args: Parameters<T[K]>): ReturnType<T[K]>;
   /**
    * Handle a particular method
    *
    * @param name of the method to be passed to a worker
    * @returns a Promise wrapping the results
    */
-  handler(name: string): (...args: any[]) => Promise<any>;
+  handler<K extends keyof T>(name: K): T[K];
   /**
    * Destroy the worker represented by this instance, rejecting all outstanding
    * tasks and killing the child process.
@@ -2900,6 +3075,7 @@ interface BuildNoChangeResults {
 interface CompilerBuildResults {
   buildId: number;
   componentGraph?: BuildResultsComponentGraph;
+  components: ComponentCompilerMeta[];
   diagnostics: Diagnostic[];
   dirsAdded: string[];
   dirsDeleted: string[];
@@ -2911,9 +3087,10 @@ interface CompilerBuildResults {
   hasError: boolean;
   hasSuccessfulBuild: boolean;
   hmr?: HotModuleReplacement;
-  hydrateAppFilePath?: string;
+  ssrAppFilePath?: string;
   isRebuild: boolean;
   namespace: string;
+  fsNamespace: string;
   outputs: BuildOutput[];
   rootDir: string;
   srcDir: string;
@@ -3074,8 +3251,8 @@ interface ConfigBundle {
 }
 /**
  * A file and/or directory copy operation that may be specified as part of
- * certain output targets for Stencil (in particular `dist`,
- * `dist-custom-elements`, and `www`).
+ * certain output targets for Stencil (in particular `loader-bundle`,
+ * `standalone`, and `www`).
  */
 interface CopyTask {
   /**
@@ -3096,8 +3273,9 @@ interface CopyTask {
    */
   dest?: string;
   /**
-   * An optional array of glob patterns to exclude from the copy operation.
-   * @default ['**\/__mocks__/**', '**\/__fixtures__/**', '**\/dist/**', '**\/.{idea,git,cache,output,temp}/**', '**\/.ds_store', '**\/.gitignore', '**\/desktop.ini', '**\/thumbs.db']
+   * Additional glob patterns to exclude from the copy operation, merged with
+   * the built-in defaults: `__mocks__`, `__fixtures__`, `dist`, hidden dirs,
+   * `.ds_store`, `.gitignore`, `desktop.ini`, `thumbs.db`.
    */
   ignore?: string[];
   /**
@@ -3176,39 +3354,12 @@ interface StencilDocsConfig {
     };
   };
 }
-interface NodeResolveConfig {
-  exportConditions?: string[];
-  browser?: boolean;
-  moduleDirectories?: string[];
-  modulePaths?: string[];
-  dedupe?: string[] | ((importee: string) => boolean);
-  extensions?: readonly string[];
-  jail?: string;
-  mainFields?: readonly string[];
-  modulesOnly?: boolean;
-  preferBuiltins?: boolean | ((module: string) => boolean);
-  resolveOnly?: ReadonlyArray<string | RegExp> | null | ((module: string) => boolean);
-  rootDir?: string;
-  allowExportsFolderMapping?: boolean;
-}
+/** Options for rolldown's built-in module resolver, passed directly to rolldown's `resolve` input option. */
+type NodeResolveConfig = NonNullable<InputOptions['resolve']>;
 interface RolldownConfig {
-  inputOptions?: RolldownInputOptions;
-  outputOptions?: RolldownOutputOptions;
-}
-interface RolldownInputOptions {
-  context?: string;
-  moduleContext?: ((id: string) => string) | {
-    [id: string]: string;
-  };
   treeshake?: boolean;
-  maxParallelFileOps?: number;
   external?: (string | RegExp)[] | string | RegExp | ((source: string, importer: string | undefined, isResolved: boolean) => boolean | null | undefined);
 }
-interface RolldownOutputOptions {
-  globals?: {
-    [name: string]: string;
-  } | ((name: string) => string);
-}
 /**
  * This sets the log level hierarchy for our terminal logger, ranging from
  * most to least verbose.
@@ -3273,57 +3424,91 @@ interface LoggerTimeSpan {
   duration(): number;
   finish(finishedMsg: string, color?: string, bold?: boolean, newLineSuffix?: boolean): number;
 }
-interface OutputTargetDist extends OutputTargetValidationConfig {
-  type: 'dist';
+/**
+ * Output target for generating lazy-loaded component bundles with a loader infrastructure.
+ * This creates an optimized distribution for CDN usage and applications that benefit from
+ * lazy-loading components on demand.
+ *
+ * Formerly known as 'dist' in v4.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: 'loader-bundle',
+ *   dir: 'dist/loader-bundle'
+ * }
+ * ```
+ */
+interface OutputTargetLoaderBundle extends OutputTargetBaseNext {
+  type: 'loader-bundle';
+  /**
+   * Directory where lazy-loaded bundles will be written.
+   * @default '' (root of output directory)
+   */
   buildDir?: string;
-  collectionDir?: string | null;
+  copy?: CopyTask[];
+  empty?: boolean;
   /**
-   * When `true` this flag will transform aliased import paths defined in
-   * a project's `tsconfig.json` to relative import paths in the compiled output's
-   * `dist-collection` bundle if it is generated (i.e. `collectionDir` is set).
-   *
-   * Paths will be left in aliased format if `false`.
+   * Whether to generate CommonJS (CJS) bundles.
    *
-   * @example
-   * // tsconfig.json
-   * {
-   *   paths: {
-   *     "@utils/*": ['/src/utils/*']
-   *   }
-   * }
+   * When `true`, generates CJS output in `cjs/` subdirectory.
+   * When `false` (default in v5+), only ESM bundles are generated.
    *
-   * // Source file
-   * import * as dateUtils from '@utils/date-utils';
-   * // Output file
-   * import * as dateUtils from '../utils/date-utils';
+   * @default false
    */
-  transformAliasedImportPathsInCollection?: boolean | null;
-  typesDir?: string;
+  cjs?: boolean;
   /**
-   * Provide a custom path for the ESM loader directory, containing files you can import
+   * Custom path for the loader directory; files you can import
    * in an initiation script within your application to register all your components for
    * lazy loading.
    *
-   * @default /dist/loader
+   * @default 'loader' (relative to output directory)
    */
-  esmLoaderPath?: string;
-  copy?: CopyTask[];
-  empty?: boolean;
+  loaderPath?: string;
   /**
-   * Whether to generate CommonJS (CJS) bundles.
+   * Hash the filenames of generated chunks based on their content.
+   * Enables forever-caching of CDN-served bundles.
    *
-   * When `true`, generates CJS output in `dist/cjs/` and `dist/index.cjs.js`.
-   * When `false` (default in v5+), only ESM bundles are generated.
+   * @default true in production, false in dev mode
+   */
+  hashFileNames?: boolean;
+  /**
+   * Number of characters to use for the content hash in filenames.
+   *
+   * @default 8
+   */
+  hashedFileNameLength?: number;
+  /**
+   * When `true`, marks `@stencil/core` as an external dependency in the bundler (ESM/CJS)
+   * distribution output. Consumers must provide `@stencil/core` themselves.
+   *
+   * Has no effect on the browser/CDN build - the runtime is always bundled there.
    *
    * @default false
    */
-  cjs?: boolean;
+  externalRuntime?: boolean;
 }
-interface OutputTargetDistCollection extends OutputTargetValidationConfig {
-  type: 'dist-collection';
+/**
+ * Output target for generating Stencil component source for downstream re-bundling.
+ * This output contains transpiled source code, component metadata, and configuration
+ * that downstream Stencil projects can re-compile and bundle.
+ *
+ * Formerly 'dist-collection' sub-output in v4, now a first-class output target in v5.
+ *
+ * In production builds, this output is auto-generated unless explicitly configured.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: 'collection',
+ *   dir: 'dist/collection',
+ *   transformAliasedImportPaths: true
+ * }
+ * ```
+ */
+interface OutputTargetCollection extends OutputTargetBaseNext {
+  type: 'collection';
   empty?: boolean;
-  dir: string;
-  collectionDir: string;
   /**
    * When `true` this flag will transform aliased import paths defined in
    * a project's `tsconfig.json` to relative import paths in the compiled output.
@@ -3345,10 +3530,25 @@ interface OutputTargetDistCollection extends OutputTargetValidationConfig {
    */
   transformAliasedImportPaths?: boolean | null;
 }
-interface OutputTargetDistTypes extends OutputTargetValidationConfig {
-  type: 'dist-types';
-  dir: string;
-  typesDir: string;
+/**
+ * Output target for generating TypeScript type definitions (.d.ts files).
+ *
+ * Formerly a sub-output of 'dist' and 'dist-custom-elements' in v4,
+ * now a first-class output target in v5 that can be shared across multiple outputs.
+ *
+ * In production builds, this output is auto-generated unless explicitly configured.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: 'types',
+ *   dir: 'dist/types'
+ * }
+ * ```
+ */
+interface OutputTargetTypes extends OutputTargetBaseNext {
+  type: 'types';
+  empty?: boolean;
 }
 interface OutputTargetDistLazy extends OutputTargetBase {
   type: 'dist-lazy';
@@ -3358,22 +3558,106 @@ interface OutputTargetDistLazy extends OutputTargetBase {
   isBrowserBuild?: boolean;
   esmIndexFile?: string;
   cjsIndexFile?: string;
+  loaderDir?: string;
+  typesDir?: string;
   empty?: boolean;
+  /** Inherited from parent output target (loader-bundle or www). Only meaningful for browser builds. */
+  hashFileNames?: boolean;
+  /** Inherited from parent output target (loader-bundle or www). */
+  hashedFileNameLength?: number;
+  /** Inherited from loader-bundle. When true, @stencil/core is external in this bundler output. */
+  externalRuntime?: boolean;
 }
-interface OutputTargetDistGlobalStyles extends OutputTargetBase {
-  type: 'dist-global-styles';
-  file: string;
+/**
+ * Output target for global styles.
+ * Generates a CSS file from an input stylesheet.
+ *
+ * Can be configured in two ways:
+ * 1. **Implicit** (backwards compat): Set `globalStyle` in the config and this output is auto-generated
+ * 2. **Explicit**: Define this output target with an `input` property
+ *
+ * Multiple `global-style` outputs are supported for building separate CSS bundles.
+ *
+ * @example
+ * ```typescript
+ * // Explicit configuration with custom input/output
+ * {
+ *   type: 'global-style',
+ *   input: './src/theme.css',
+ *   fileName: 'theme.css',
+ *   dir: 'dist/assets',
+ *   copyToLoaderBrowser: false
+ * }
+ * ```
+ */
+interface OutputTargetGlobalStyle extends OutputTargetBaseNext {
+  type: 'global-style';
+  /**
+   * Path to the input CSS file to compile.
+   * When specified, this takes precedence over the `globalStyle` config option.
+   *
+   * If neither `input` nor `globalStyle` config is set, no CSS will be built.
+   */
+  input?: string;
+  /**
+   * Output filename for the compiled CSS.
+   * @default '{namespace}.css' when using globalStyle config, or basename of input file
+   */
+  fileName?: string;
+  /**
+   * When `true`, also copies the global style CSS to the loader-bundle browser directory
+   * for backwards compatibility with existing CDN consumers who have hardcoded CSS paths.
+   *
+   * @default true
+   */
+  copyToLoaderBrowser?: boolean;
+  /**
+   * Controls whether this global stylesheet is injected into component shadow DOMs
+   * as a constructable stylesheet at runtime.
+   *
+   * - `'none'` (default): Don't inject - stylesheet must be loaded externally (e.g., via `<link>`)
+   * - `'client'`: Inject only in client builds, not SSR (reduces SSR output size)
+   * - `'all'`: Inject in both client and SSR builds
+   *
+   * @default 'none'
+   */
+  inject?: 'none' | 'client' | 'all';
 }
-interface OutputTargetDistLazyLoader extends OutputTargetBase {
-  type: 'dist-lazy-loader';
-  dir: string;
-  esmDir: string;
-  cjsDir?: string;
-  componentDts: string;
-  empty: boolean;
+/**
+ * Output target for component assets.
+ * Copies all component `assetsDirs` to a unified location.
+ *
+ * auto-generated when components have `assetsDirs` unless explicitly configured.
+ * The output is placed in `dist/assets/` by default and is available to all distribution strategies.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: 'assets',
+ *   dir: 'dist/assets'
+ * }
+ * ```
+ */
+interface OutputTargetAssets extends OutputTargetBaseNext {
+  type: 'assets';
 }
-interface OutputTargetHydrate extends OutputTargetBase {
-  type: 'dist-hydrate-script';
+/**
+ * Output target for server-side rendering (SSR) and hydration.
+ * Generates a script that can be used for SSR and static site generation (prerendering).
+ *
+ * Formerly known as 'dist-hydrate-script' in v4.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: 'ssr',
+ *   dir: 'dist/ssr',
+ *   minify: true
+ * }
+ * ```
+ */
+interface OutputTargetSsr extends OutputTargetBase {
+  type: 'ssr';
   dir?: string;
   /**
    * Module IDs that should not be bundled into the script.
@@ -3393,6 +3677,13 @@ interface OutputTargetHydrate extends OutputTargetBase {
    */
   cjs?: boolean;
 }
+interface OutputTargetSsrWasm extends OutputTargetBase {
+  type: 'ssr-wasm';
+  /** Output directory. @default 'dist/ssr-wasm' */
+  dir?: string;
+  empty?: boolean;
+  minify?: boolean;
+}
 interface OutputTargetCustom extends OutputTargetBase {
   type: 'custom';
   name: string;
@@ -3450,6 +3741,22 @@ interface OutputTargetDocsReadme extends OutputTargetBase {
   overwriteExisting?: boolean | 'if-missing';
   footer?: string;
   strict?: boolean;
+  /**
+   * Add extra columns to the generated Properties/Events tables, e.g. to
+   * surface custom JSDoc tags as a column of their own.
+   */
+  customColumns?: {
+    props?: DocsReadmeCustomColumn<JsonDocsProp>[];
+    events?: DocsReadmeCustomColumn<JsonDocsEvent>[];
+  };
+}
+/**
+ * A custom column to render in a `docs-readme` Properties/Events table.
+ * `content` is invoked once per row.
+ */
+interface DocsReadmeCustomColumn<T> {
+  header: string;
+  content: (member: T, cmp: JsonDocsComponent) => string;
 }
 interface OutputTargetDocsJson extends OutputTargetBase {
   type: 'docs-json';
@@ -3490,18 +3797,46 @@ interface OutputTargetDocsCustom extends OutputTargetBase {
   generator: (docs: JsonDocs, config: Config) => void | Promise<void>;
   strict?: boolean;
 }
+/**
+ * Output target for generating an [Agent Skill](https://agentskills.io)
+ * (`SKILL.md` + per-component reference files) describing a component
+ * library, so AI coding agents can consume its API and usage examples
+ * directly.
+ */
+interface OutputTargetDocsAgentSkill extends OutputTargetBase {
+  type: 'docs-agent-skill';
+  /**
+   * The root directory where the skill (`SKILL.md` + `components/*.md`) is written.
+   *
+   * defaults to `dist/skill`
+   */
+  dir?: string;
+  /**
+   * The skill's name, used in the `SKILL.md` frontmatter.
+   *
+   * Defaults to a kebab-cased form of {@link Config.namespace}.
+   */
+  name?: string;
+  /**
+   * The skill's description, used in the `SKILL.md` frontmatter - this is the
+   * text agents use to decide when to load the skill.
+   *
+   * Defaults to an auto-generated sentence built from the project's
+   * {@link JsonDocs.usage} (if present) or its component tags.
+   */
+  description?: string;
+}
 interface OutputTargetStats extends OutputTargetBase {
   type: 'stats';
   file?: string;
 }
-interface OutputTargetBaseNext {
-  type: string;
+interface OutputTargetBaseNext extends OutputTargetBase {
   dir?: string;
 }
 /**
  * The collection of valid export behaviors.
  * Used to generate a type for typed configs as well as output target validation
- * for the `dist-custom-elements` output target.
+ * for the `standalone` output target.
  *
  * Adding a value to this const array will automatically add it as a valid option on the
  * output target configuration for `customElementsExportBehavior`.
@@ -3510,8 +3845,7 @@ interface OutputTargetBaseNext {
  * - `auto-define-custom-elements`: Enables the auto-definition of a component and its children (recursively) in the custom elements registry. This
  * functionality allows consumers to bypass the explicit call to define a component, its children, its children's
  * children, etc. Users of this flag should be aware that enabling this functionality may increase bundle size.
- * - `bundle`: A `defineCustomElements` function will be exported from the distribution directory. This behavior was added to allow easy migration
- * from `dist-custom-elements-bundle` to `dist-custom-elements`.
+ * - `bundle`: A `defineCustomElements` function will be exported from the distribution directory.
  * - `single-export-module`: All components will be re-exported from the specified directory's root `index.js` file.
  */
 declare const CustomElementsExportBehaviorOptions: readonly ["default", "auto-define-custom-elements", "bundle", "single-export-module"];
@@ -3520,23 +3854,40 @@ declare const CustomElementsExportBehaviorOptions: readonly ["default", "auto-de
  * This is used on the output target config for intellisense in typed configs.
  */
 type CustomElementsExportBehavior = (typeof CustomElementsExportBehaviorOptions)[number];
-interface OutputTargetDistCustomElements extends OutputTargetValidationConfig {
-  type: 'dist-custom-elements';
+/**
+ * Output target for generating standalone component modules.
+ * Each component is output as an individual ES module that can be directly imported.
+ *
+ * This output target is ideal for npm consumption and tree-shaking, as consumers
+ * can import only the components they need.
+ *
+ * Formerly known as 'dist-custom-elements' in v4.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: 'standalone',
+ *   dir: 'dist/standalone',
+ *   externalRuntime: true,
+ *   autoLoader: true
+ * }
+ * ```
+ */
+interface OutputTargetStandalone extends OutputTargetBaseNext {
+  type: 'standalone';
   empty?: boolean;
   /**
    * Triggers the following behaviors when enabled:
    * 1. All `@stencil/core/*` module references are treated as external during bundling.
    * 2. File names are not hashed.
    * 3. File minification will follow the behavior defined at the root of the Stencil config.
+   *
+   * @default false
    */
   externalRuntime?: boolean;
   copy?: CopyTask[];
   includeGlobalScripts?: boolean;
   minify?: boolean;
-  /**
-   * Enables the generation of type definition files for the output target.
-   */
-  generateTypeDeclarations?: boolean;
   /**
    * Define the export/definition behavior for the output target's generated output.
    * This controls if/how custom elements will be defined or where components will be exported from.
@@ -3547,6 +3898,8 @@ interface OutputTargetDistCustomElements extends OutputTargetValidationConfig {
    * Generate an auto-loader script that uses MutationObserver to lazily load
    * and define custom elements as they appear in the DOM.
    *
+   * @default true
+   *
    * When set to `true`, generates a `loader.js` file that auto-starts on import.
    * Can also be configured with an object for more control:
    * - `fileName`: Custom filename for the loader (default: 'loader.js')
@@ -3586,27 +3939,45 @@ interface OutputTargetBase {
    * A unique string to differentiate one output target from another
    */
   type: string;
+  /**
+   * When `true`, this output target will be skipped during development builds (`--dev`).
+   * This improves dev build times by not generating production-only artifacts.
+   *
+   * Defaults vary by output target type:
+   * - `loader-bundle`: `false` (always builds)
+   * - `standalone`: `true` (skips in dev)
+   * - `ssr`: `true` (skips in dev, unless `devServer.ssr` is enabled)
+   * - `docs-*`: `true` (skips in dev)
+   * - `custom`: `true` (skips in dev)
+   * - `www`, `copy`, `stats`: `false` (always runs)
+   */
+  skipInDev?: boolean;
 }
-/**
- * Output targets that can have validation for common `package.json` field values
- * (module, types, etc.). This allows them to be marked for validation in a project's Stencil config.
- */
-interface OutputTargetValidationConfig extends OutputTargetBaseNext {
-  isPrimaryPackageOutputTarget?: boolean;
-}
-type EligiblePrimaryPackageOutputTarget = OutputTargetDist | OutputTargetDistCustomElements | OutputTargetDistCollection | OutputTargetDistTypes;
-type OutputTargetBuild = OutputTargetDistCollection | OutputTargetDistLazy;
+type OutputTargetBuild = OutputTargetCollection | OutputTargetDistLazy;
 interface OutputTargetCopy extends OutputTargetBase {
   type: 'copy';
   dir: string;
   copy?: CopyTask[];
-  copyAssets?: 'collection' | 'dist';
 }
 interface OutputTargetWww extends OutputTargetBase {
   /**
    * Webapp output target.
    */
   type: 'www';
+  /**
+   * Choose how components are bundled for the www output.
+   *
+   * - `'loader'` (default): Uses the loader-bundle architecture with chunk
+   *   splitting and a loader infrastructure. Best for production apps with many
+   *   components where you want optimal loading performance.
+   *
+   * - `'standalone'`: Uses standalone component modules with an auto-loader that
+   *   uses MutationObserver to dynamically import components as they appear in
+   *   the DOM. Simpler architecture, easier debugging, one module per component.
+   *
+   * Default: `'loader'`
+   */
+  bundleMode?: 'loader' | 'standalone';
   /**
    * The directory to write the app's JavaScript and CSS build
    * files to. The default is to place this directory as a child
@@ -3653,7 +4024,7 @@ interface OutputTargetWww extends OutputTargetBase {
    * Path to an external node module which has exports of the prerender config object.
    * ```
    * module.exports = {
-   *   afterHydrate(document, url) {
+   *   afterSsr(document, url) {
    *     document.title = `URL: ${url.href}`;
    *   }
    * }
@@ -3661,15 +4032,35 @@ interface OutputTargetWww extends OutputTargetBase {
    */
   prerenderConfig?: string;
   /**
-   * Service worker config for production builds. During development builds
-   * service worker script will be injected to automatically deregister existing
-   * service workers. When set to `false` neither a service worker registration
-   * or deregistration will be added to the index.html.
+   * Service worker config for production builds. In development mode, a script
+   * to deregister existing service workers is always injected. Defaults to
+   * `null` (disabled). Set to `true` to enable with default settings, or provide
+   * a config object for custom settings.
    */
-  serviceWorker?: ServiceWorkerConfig | null | false;
+  serviceWorker?: ServiceWorkerConfig | true | null;
   appDir?: string;
+  /**
+   * Hash the filenames of generated chunks based on their content.
+   * Enables forever-caching of CDN-served bundles.
+   *
+   * @default true in production, false in dev mode
+   */
+  hashFileNames?: boolean;
+  /**
+   * Number of characters to use for the content hash in filenames.
+   *
+   * @default 8
+   */
+  hashedFileNameLength?: number;
 }
-type OutputTarget = OutputTargetCopy | OutputTargetCustom | OutputTargetDist | OutputTargetDistCollection | OutputTargetDistCustomElements | OutputTargetDistLazy | OutputTargetDistGlobalStyles | OutputTargetDistLazyLoader | OutputTargetDocsJson | OutputTargetDocsCustom | OutputTargetDocsReadme | OutputTargetDocsVscode | OutputTargetDocsCustomElementsManifest | OutputTargetWww | OutputTargetHydrate | OutputTargetStats | OutputTargetDistTypes;
+type OutputTarget = OutputTargetCopy | OutputTargetCustom | OutputTargetLoaderBundle | OutputTargetStandalone | OutputTargetSsr | OutputTargetSsrWasm | OutputTargetCollection | OutputTargetTypes | OutputTargetGlobalStyle | OutputTargetAssets | OutputTargetDistLazy | OutputTargetDocsJson | OutputTargetDocsCustom | OutputTargetDocsReadme | OutputTargetDocsVscode | OutputTargetDocsCustomElementsManifest | OutputTargetDocsAgentSkill | OutputTargetWww | OutputTargetStats;
+/**
+ * A post-validation form of {@link OutputTargetWww} where `serviceWorker`
+ * has been normalized - `true` is resolved to a {@link ServiceWorkerConfig}.
+ */
+type ValidatedOutputTargetWww = Omit<OutputTargetWww, 'serviceWorker'> & {
+  serviceWorker?: ServiceWorkerConfig | null;
+};
 /**
  * Our custom configuration interface for generated caching Service Workers
  * using the Workbox library (see https://developer.chrome.com/docs/workbox/).
@@ -3717,12 +4108,6 @@ interface LoadConfigInit {
   configPath?: string;
   logger?: Logger;
   sys?: CompilerSystem;
-  /**
-   * When set to true, if the "tsconfig.json" file is not found
-   * it'll automatically generate and save a default tsconfig
-   * within the root directory.
-   */
-  initTsConfig?: boolean;
 }
 /**
  * Results from an attempt to load a config. The values on this interface
@@ -3764,24 +4149,13 @@ interface WorkerOptions {
   maxConcurrentTasksPerWorker?: number;
   logger?: Logger;
 }
-interface RolldownInterface {
-  rolldown: {
-    (config: any): Promise<any>;
-  };
-  plugins: {
-    nodeResolve(opts: any): any;
-    replace(opts: any): any;
-    commonjs(opts: any): any;
-    json(): any;
-  };
-}
 interface ResolveModuleOptions {
   manuallyResolve?: boolean;
   packageJson?: boolean;
 }
 interface PrerenderStartOptions {
   buildId?: string;
-  hydrateAppFilePath?: string;
+  ssrAppFilePath?: string;
   componentGraph?: BuildResultsComponentGraph;
   srcIndexHtmlPath?: string;
 }
@@ -3856,6 +4230,18 @@ interface Compiler {
   createWatcher(): Promise<CompilerWatcher>;
   destroy(): Promise<void>;
   sys: CompilerSystem;
+  /**
+   * @internal - Testing only. Access to the in-memory filesystem
+   */
+  fs?: InMemoryFileSystem;
+  /**
+   * @internal - Testing only. Access to the validated configuration
+   */
+  config?: ValidatedConfig;
+  /**
+   * @internal - Testing only. Access to the compiler context
+   */
+  compilerCtx?: CompilerCtx;
 }
 interface CompilerWatcher extends BuildOnEvents {
   start: () => Promise<WatcherCloseResults>;
@@ -3896,7 +4282,7 @@ interface TranspileOptions {
   componentMetadata?: 'runtimestatic' | 'compilerstatic' | string | undefined;
   /**
    * The actual internal import path for any `@stencil/core` imports.
-   * Default is `@stencil/core/runtime/client`.
+   * Default is `@stencil/core/runtime/client/standalone`.
    */
   coreImportPath?: string;
   /**
@@ -3982,7 +4368,51 @@ interface TranspileOptions {
    * Adds `transformTag` calls to css strings and querySelector(All) calls
    */
   additionalTagTransformers?: boolean;
+  /**
+   * Callback used to resolve parent-class source for inheritance-chain analysis.
+   * Called when a component's `extends` clause references a class from another
+   * module.  Return the resolved absolute path and source text of that module,
+   * or `null` to skip inheritance resolution for that specifier.
+   *
+   * @example
+   * ```ts
+   * transpile(myComponentCode, {
+   *   resolveImport: (specifier, importer) => {
+   *     const resolved = require.resolve(specifier, { paths: [path.dirname(importer)] });
+   *     return { code: fs.readFileSync(resolved, 'utf8'), path: resolved };
+   *   },
+   * });
+   * ```
+   */
+  resolveImport?: (specifier: string, importer: string) => {
+    code: string;
+    path: string;
+  } | null;
+  /**
+   * When `true` class declarations at the end of a `@Component` inheritance chain
+   * * that have no `extends` clause * will get `extends HTMLElement` injected, and a minimal
+   * `constructor() { super(); }`. Any stencil static meta-getters are also stripped.
+   */
+  transformAsBaseClass?: boolean;
+  /**
+   * Overrides for Stencil's BUILD feature flags in the generated output.
+   * When set, a BUILD mutation statement is prepended to the compiled code so
+   * that the specified flags take effect for this component at runtime.
+   */
+  buildOverrides?: BuildOverrides;
 }
+/**
+ * Keys of {@link BuildConditionals} that can be meaningfully overridden at
+ * transpile time — config-driven flags that are not derived from component
+ * scanning or runtime environment detection.
+ */
+type BuildOverrideKeys = 'hotModuleReplacement' | 'signalBacking' | 'vdomSignals' | 'lightDomPatches' | 'slotChildNodes' | 'slotCloneNode' | 'slotDomMutations' | 'slotTextContent' | 'lifecycleDOMEvents' | 'initializeNextTick';
+/**
+ * Subset of Stencil's BUILD feature flags that can be overridden at transpile
+ * time. Derived from {@link BuildConditionals} via `Pick` so the field list
+ * and types stay in sync with the authoritative definition.
+ */
+type BuildOverrides = Pick<BuildConditionals, BuildOverrideKeys>;
 type CompileTarget = 'latest' | 'esnext' | 'es2020' | 'es2019' | 'es2018' | 'es2017' | 'es2015' | string | undefined;
 interface TranspileResults {
   code: string;
@@ -4008,6 +4438,17 @@ interface TransformOptions {
   style: 'static' | null;
   styleImportData: 'queryparams' | null;
   target?: string;
+  /**
+   * @see {@link TranspileOptions.resolveImport}
+   */
+  resolveImport?: (specifier: string, importer: string) => {
+    code: string;
+    path: string;
+  } | null;
+  /** @see {@link TranspileOptions.transformAsBaseClass} */
+  transformAsBaseClass?: boolean;
+  /** @see {@link TranspileOptions.buildOverrides} */
+  buildOverrides?: BuildOverrides;
 }
 interface CompileScriptMinifyOptions {
   target?: CompileTarget;
@@ -4028,4 +4469,4 @@ interface CliInitOptions {
   sys: CompilerSystem;
 }
 //#endregion
-export { AutoprefixerOptions, BuildEmitEvents, BuildEvents, BuildLog, BuildNoChangeResults, BuildOnEventRemove, BuildOnEvents, BuildOutput, BuildResultsComponentGraph, CacheStorage, CliInitOptions, CompileScriptMinifyOptions, CompileTarget, Compiler, CompilerBuildResults, CompilerBuildStart, CompilerDependency, CompilerEventBuildFinish, CompilerEventBuildLog, CompilerEventBuildNoChange, CompilerEventBuildStart, CompilerEventDirAdd, CompilerEventDirDelete, CompilerEventFileAdd, CompilerEventFileDelete, CompilerEventFileUpdate, CompilerEventFsChange, CompilerEventName, CompilerFileWatcher, CompilerFileWatcherCallback, CompilerFileWatcherEvent, CompilerFsStats, CompilerRequest, CompilerRequestResponse, CompilerSystem, CompilerSystemCreateDirectoryOptions, CompilerSystemCreateDirectoryResults, CompilerSystemRealpathResults, CompilerSystemRemoveDirectoryOptions, CompilerSystemRemoveDirectoryResults, CompilerSystemRemoveFileResults, CompilerSystemRenameResults, CompilerSystemRenamedPath, CompilerSystemWriteFileResults, CompilerWatcher, Config, ConfigBundle, ConfigExtras, CopyResults, CopyTask, Credentials, CustomElementsExportBehavior, CustomElementsExportBehaviorOptions, DevServer, DevServerConfig, DevServerEditor, Diagnostic, EligiblePrimaryPackageOutputTarget, FsWatchResults, HistoryApiFallback, HmrStyleUpdate, HotModuleReplacement, HydrateDocumentOptions, HydrateFactoryOptions, HydratedFlag, JsonDocMethodParameter, JsonDocs, JsonDocsComponent, JsonDocsCustomState, JsonDocsDependencyGraph, JsonDocsEvent, JsonDocsListener, JsonDocsMethod, JsonDocsMethodReturn, JsonDocsPart, JsonDocsProp, JsonDocsSlot, JsonDocsStyle, JsonDocsTag, JsonDocsTypeLibrary, JsonDocsUsage, JsonDocsValue, LOG_LEVELS, LazyRequire, LoadConfigInit, LoadConfigResults, LogLevel, Logger, LoggerLineUpdater, LoggerTimeSpan, NodeResolveConfig, OptimizeCssInput, OptimizeCssOutput, OptimizeJsInput, OptimizeJsOutput, OutputTarget, OutputTargetBase, OutputTargetBaseNext, OutputTargetBuild, OutputTargetCopy, OutputTargetCustom, OutputTargetDist, OutputTargetDistCollection, OutputTargetDistCustomElements, OutputTargetDistGlobalStyles, OutputTargetDistLazy, OutputTargetDistLazyLoader, OutputTargetDistTypes, OutputTargetDocsCustom, OutputTargetDocsCustomElementsManifest, OutputTargetDocsJson, OutputTargetDocsReadme, OutputTargetDocsVscode, OutputTargetHydrate, OutputTargetStats, OutputTargetWww, PageReloadStrategy, ParsedPath, PlatformPath, PrerenderConfig, PrerenderHydrateOptions, PrerenderResults, PrerenderStartOptions, ResolveModuleIdOptions, ResolveModuleIdResults, ResolveModuleOptions, RobotsTxtOpts, RobotsTxtResults, RolldownConfig, RolldownInputOptions, RolldownInterface, RolldownOutputOptions, SerializeDocumentOptions, ServiceWorkerConfig, SitemapXmpOpts, SitemapXmpResults, StencilConfig, StencilDevServerConfig, StencilDocsConfig, StyleDoc, SystemDetails, TransformOptions, TranspileOnlyResults, TranspileOptions, TranspileResults, UnvalidatedConfig, ValidatedConfig, WatcherCloseResults, WorkerMainController, WorkerOptions };
+export { AutoprefixerOptions, BuildEmitEvents, BuildEvents, BuildLog, BuildNoChangeResults, BuildOnEventRemove, BuildOnEvents, BuildOutput, BuildOverrides, BuildResultsComponentGraph, CacheStorage, CliInitOptions, CompileScriptMinifyOptions, CompileTarget, Compiler, CompilerBuildResults, CompilerBuildStart, CompilerDependency, CompilerEventBuildFinish, CompilerEventBuildLog, CompilerEventBuildNoChange, CompilerEventBuildStart, CompilerEventDirAdd, CompilerEventDirDelete, CompilerEventFileAdd, CompilerEventFileDelete, CompilerEventFileUpdate, CompilerEventFsChange, CompilerEventName, CompilerFileWatcher, CompilerFileWatcherCallback, CompilerFileWatcherEvent, CompilerFsStats, CompilerRequest, CompilerRequestResponse, CompilerSystem, CompilerSystemCreateDirectoryOptions, CompilerSystemCreateDirectoryResults, CompilerSystemRealpathResults, CompilerSystemRemoveDirectoryOptions, CompilerSystemRemoveDirectoryResults, CompilerSystemRemoveFileResults, CompilerSystemRenameResults, CompilerSystemRenamedPath, CompilerSystemWriteFileResults, CompilerWatcher, Config, ConfigBundle, ConfigCompat, CopyResults, CopyTask, Credentials, CustomElementsExportBehavior, CustomElementsExportBehaviorOptions, DevServer, DevServerConfig, DevServerEditor, Diagnostic, DocsReadmeCustomColumn, FsWatchResults, HistoryApiFallback, HmrStyleUpdate, HotModuleReplacement, HydrateDocumentOptions, HydrateFactoryOptions, HydratedFlag, JsonDocMethodParameter, JsonDocs, JsonDocsComponent, JsonDocsCustomState, JsonDocsDependencyGraph, JsonDocsEvent, JsonDocsListener, JsonDocsMethod, JsonDocsMethodReturn, JsonDocsPart, JsonDocsProp, JsonDocsSlot, JsonDocsStyle, JsonDocsTag, JsonDocsTypeLibrary, JsonDocsUsage, JsonDocsValue, LOG_LEVELS, LazyRequire, LightDomPatches, LoadConfigInit, LoadConfigResults, LogLevel, Logger, LoggerLineUpdater, LoggerTimeSpan, ModeConfig, NodeResolveConfig, OptimizeCssInput, OptimizeCssOutput, OptimizeJsInput, OptimizeJsOutput, OutputTarget, OutputTargetAssets, OutputTargetBase, OutputTargetBaseNext, OutputTargetBuild, OutputTargetCollection, OutputTargetCopy, OutputTargetCustom, OutputTargetDistLazy, OutputTargetDocsAgentSkill, OutputTargetDocsCustom, OutputTargetDocsCustomElementsManifest, OutputTargetDocsJson, OutputTargetDocsReadme, OutputTargetDocsVscode, OutputTargetGlobalStyle, OutputTargetLoaderBundle, OutputTargetSsr, OutputTargetSsrWasm, OutputTargetStandalone, OutputTargetStats, OutputTargetTypes, OutputTargetWww, PageReloadStrategy, ParsedPath, PlatformPath, PrerenderConfig, PrerenderHydrateOptions, PrerenderOptions, PrerenderResults, PrerenderStartOptions, ResolveModuleIdOptions, ResolveModuleIdResults, ResolveModuleOptions, RobotsTxtOpts, RobotsTxtResults, RolldownConfig, SerializeDocumentOptions, ServiceWorkerConfig, SitemapXmpOpts, SitemapXmpResults, SsrDocumentOptions, SsrFactoryOptions, StencilConfig, StencilDevServerConfig, StencilDocsConfig, StyleDoc, SystemDetails, TransformOptions, TranspileOnlyResults, TranspileOptions, TranspileResults, UnvalidatedConfig, ValidatedConfig, ValidatedOutputTargetWww, WatcherCloseResults, WorkerMainController, WorkerOptions };