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

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

@@ -715,7 +715,7 @@ interface BuildCtx {
   hasScriptChanges: boolean;
   hasStyleChanges: boolean;
   hasWarning: boolean;
-  hydrateAppFilePath: string;
+  ssrAppFilePath: string;
   indexBuildCount: number;
   indexDoc: Document;
   isRebuild: boolean;
@@ -868,6 +868,25 @@ interface CollectionCompilerVersion {
   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 +899,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 +914,7 @@ interface CompilerCtx {
   moduleMap: ModuleMap;
   nodeMap: NodeMap;
   resolvedCollections: Set<string>;
-  rolldownCacheHydrate: any;
+  rolldownCacheSsr: any;
   rolldownCacheLazy: any;
   rolldownCacheNative: any;
   styleModeNames: Set<string>;
@@ -902,6 +922,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>;
@@ -1404,7 +1450,7 @@ interface PrerenderUrlRequest {
   baseUrl: string;
   componentGraphPath: string;
   devServerHostUrl: string;
-  hydrateAppFilePath: string;
+  ssrAppFilePath: string;
   isDebug: boolean;
   prerenderConfigPath: string;
   staticSite: boolean;
@@ -1487,9 +1533,10 @@ interface PackageJsonData {
   browser?: string;
   module?: string;
   'jsnext:main'?: string;
-  'collection:main'?: string;
   unpkg?: string;
+  /** @deprecated Use `stencilRebundle` instead. Kept for reading v4 dependencies. */
   collection?: string;
+  stencilRebundle?: string;
   types?: string;
   files?: string[];
   ['dist-tags']?: {
@@ -1673,11 +1720,6 @@ interface StencilConfig {
    * (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,13 +1739,6 @@ 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.
@@ -1779,14 +1814,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 +1841,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:
@@ -1870,20 +1897,6 @@ interface ConfigExtrasBase {
    * 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> = {
   /**
@@ -1923,7 +1936,6 @@ type ConfigExtrasSlotFixes<ExperimentalFixesEnabled extends boolean, IndividualF
 type ConfigExtras = ConfigExtrasBase & (ConfigExtrasSlotFixes<true, true> | ConfigExtrasSlotFixes<false, boolean>);
 interface Config extends StencilConfig {
   buildAppCore?: boolean;
-  buildDocs?: boolean;
   configPath?: string;
   writeLog?: boolean;
   devServer?: DevServerConfig;
@@ -1937,6 +1949,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)
    */
@@ -2019,7 +2036,7 @@ 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' | 'extras' | 'fsNamespace' | 'hashFileNames' | 'hashedFileNameLength' | '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,6 +2044,11 @@ 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 HydratedFlag {
@@ -2231,11 +2253,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 +2301,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 +2327,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 +2344,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 +2443,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 +2468,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 +2509,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 +2554,11 @@ interface PrerenderHydrateOptions extends SerializeDocumentOptions {
    */
   staticDocument?: boolean;
 }
+/**
+ * v4 backwards compat
+ * @deprecated - use PrerenderOptions instead
+ */
+interface PrerenderHydrateOptions extends PrerenderOptions {}
 interface RobotsTxtOpts {
   urls: string[];
   sitemapUrl: string;
@@ -2911,7 +2956,7 @@ interface CompilerBuildResults {
   hasError: boolean;
   hasSuccessfulBuild: boolean;
   hmr?: HotModuleReplacement;
-  hydrateAppFilePath?: string;
+  ssrAppFilePath?: string;
   isRebuild: boolean;
   namespace: string;
   outputs: BuildOutput[];
@@ -3074,8 +3119,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 {
   /**
@@ -3273,57 +3318,69 @@ interface LoggerTimeSpan {
   duration(): number;
   finish(finishedMsg: string, color?: string, bold?: boolean, newLineSuffix?: boolean): number;
 }
-interface OutputTargetDist extends OutputTargetValidationConfig {
-  type: 'dist';
-  buildDir?: string;
-  collectionDir?: string | null;
-  /**
-   * 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`.
-   *
-   * @example
-   * // tsconfig.json
-   * {
-   *   paths: {
-   *     "@utils/*": ['/src/utils/*']
-   *   }
-   * }
-   *
-   * // Source file
-   * import * as dateUtils from '@utils/date-utils';
-   * // Output file
-   * import * as dateUtils from '../utils/date-utils';
-   */
-  transformAliasedImportPathsInCollection?: boolean | null;
-  typesDir?: string;
+/**
+ * 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';
   /**
-   * Provide a custom path for the ESM loader directory, containing files you can import
-   * in an initiation script within your application to register all your components for
-   * lazy loading.
-   *
-   * @default /dist/loader
+   * Directory where lazy-loaded bundles will be written.
+   * @default '' (root of output directory)
    */
-  esmLoaderPath?: string;
+  buildDir?: string;
   copy?: CopyTask[];
   empty?: boolean;
   /**
    * Whether to generate CommonJS (CJS) bundles.
    *
-   * When `true`, generates CJS output in `dist/cjs/` and `dist/index.cjs.js`.
+   * When `true`, generates CJS output in `cjs/` subdirectory.
    * When `false` (default in v5+), only ESM bundles are generated.
    *
    * @default false
    */
   cjs?: boolean;
+  /**
+   * 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 'loader' (relative to output directory)
+   */
+  loaderPath?: string;
 }
-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: 'stencil-rebundle',
+ *   dir: 'dist/stencil-rebundle',
+ *   transformAliasedImportPaths: true
+ * }
+ * ```
+ */
+interface OutputTargetStencilRebundle extends OutputTargetBaseNext {
+  type: 'stencil-rebundle';
   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 +3402,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 +3430,100 @@ interface OutputTargetDistLazy extends OutputTargetBase {
   isBrowserBuild?: boolean;
   esmIndexFile?: string;
   cjsIndexFile?: string;
+  loaderDir?: string;
+  typesDir?: string;
   empty?: 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.
@@ -3494,14 +3644,13 @@ 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 +3659,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 +3668,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 true
    */
   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 +3712,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 +3753,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 = OutputTargetStencilRebundle | 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 +3838,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}`;
    *   }
    * }
@@ -3669,7 +3854,7 @@ interface OutputTargetWww extends OutputTargetBase {
   serviceWorker?: ServiceWorkerConfig | null | false;
   appDir?: string;
 }
-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 | OutputTargetStencilRebundle | OutputTargetTypes | OutputTargetGlobalStyle | OutputTargetAssets | OutputTargetDistLazy | OutputTargetDocsJson | OutputTargetDocsCustom | OutputTargetDocsReadme | OutputTargetDocsVscode | OutputTargetDocsCustomElementsManifest | OutputTargetWww | OutputTargetStats;
 /**
  * Our custom configuration interface for generated caching Service Workers
  * using the Workbox library (see https://developer.chrome.com/docs/workbox/).
@@ -3781,7 +3966,7 @@ interface ResolveModuleOptions {
 }
 interface PrerenderStartOptions {
   buildId?: string;
-  hydrateAppFilePath?: string;
+  ssrAppFilePath?: string;
   componentGraph?: BuildResultsComponentGraph;
   srcIndexHtmlPath?: string;
 }
@@ -3982,6 +4167,27 @@ interface TranspileOptions {
    * Adds `transformTag` calls to css strings and querySelector(All) calls
    */
   additionalTagTransformers?: boolean;
+  /**
+   * A map of virtual file paths to source text for modules that the component
+   * under transpilation extends from.  When provided, `transpile()` builds a
+   * minimal multi-file TypeScript program from these sources so that
+   * {@link https://stenciljs.com/docs/component-lifecycle inheritance chains}
+   * can be resolved without requiring the parent files to exist on disk.
+   *
+   * Keys are the same import paths used in the component's `import` statements
+   * (relative paths are resolved against `currentDirectory`).  Values are the
+   * TypeScript/JavaScript source text of that module.
+   *
+   * @example
+   * ```ts
+   * transpile(myComponentCode, {
+   *   extraFiles: {
+   *     './base-component.ts': baseComponentSourceText,
+   *   },
+   * });
+   * ```
+   */
+  extraFiles?: Record<string, string>;
 }
 type CompileTarget = 'latest' | 'esnext' | 'es2020' | 'es2019' | 'es2018' | 'es2017' | 'es2015' | string | undefined;
 interface TranspileResults {
@@ -4008,6 +4214,10 @@ interface TransformOptions {
   style: 'static' | null;
   styleImportData: 'queryparams' | null;
   target?: string;
+  /**
+   * @see {@link TranspileOptions.extraFiles}
+   */
+  extraFiles?: Record<string, string>;
 }
 interface CompileScriptMinifyOptions {
   target?: CompileTarget;
@@ -4028,4 +4238,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, 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, 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, OutputTargetAssets, OutputTargetBase, OutputTargetBaseNext, OutputTargetBuild, OutputTargetCopy, OutputTargetCustom, OutputTargetDistLazy, OutputTargetDocsCustom, OutputTargetDocsCustomElementsManifest, OutputTargetDocsJson, OutputTargetDocsReadme, OutputTargetDocsVscode, OutputTargetGlobalStyle, OutputTargetLoaderBundle, OutputTargetSsr, OutputTargetStandalone, OutputTargetStats, OutputTargetStencilRebundle, OutputTargetTypes, OutputTargetWww, PageReloadStrategy, ParsedPath, PlatformPath, PrerenderConfig, PrerenderHydrateOptions, PrerenderOptions, PrerenderResults, PrerenderStartOptions, ResolveModuleIdOptions, ResolveModuleIdResults, ResolveModuleOptions, RobotsTxtOpts, RobotsTxtResults, RolldownConfig, RolldownInputOptions, RolldownInterface, RolldownOutputOptions, SerializeDocumentOptions, ServiceWorkerConfig, SitemapXmpOpts, SitemapXmpResults, SsrDocumentOptions, SsrFactoryOptions, StencilConfig, StencilDevServerConfig, StencilDocsConfig, StyleDoc, SystemDetails, TransformOptions, TranspileOnlyResults, TranspileOptions, TranspileResults, UnvalidatedConfig, ValidatedConfig, WatcherCloseResults, WorkerMainController, WorkerOptions };