@stencil/core 5.0.0-alpha.9 → 5.0.0-beta.1

package/dist/declarations/stencil-ext-modules.d.ts

@@ -1,24 +1,24 @@
-declare module "*.css" {
+declare module "*.css?stencil" {
   const src: () => string;
   export default src;
 }
 
-declare module "*.svg" {
+declare module "*.svg?stencil" {
   const src: string;
   export default src;
 }
 
-declare module "*.txt" {
+declare module "*.txt?stencil" {
   const src: string;
   export default src;
 }
 
-declare module "*.frag" {
+declare module "*.frag?stencil" {
   const src: string;
   export default src;
 }
 
-declare module "*.vert" {
+declare module "*.vert?stencil" {
   const src: string;
   export default src;
 }

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

@@ -1,5 +1,6 @@
 import { ListenTargetOptions, ResolutionHandler } from "./stencil-public-runtime.js";
-import { InputOptions, SourceMap as RolldownSourceMap } from "rolldown";
+import { InputOptions, Plugin, SourceMap } from "rolldown";
+import "typescript";
 //#region src/utils/result.d.ts
 /**
  * A Result wraps up a success state and a failure state, allowing you to
@@ -46,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
 /**
@@ -231,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
  */
@@ -245,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
 /**
@@ -275,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
    */
@@ -655,7 +642,7 @@ interface StyleDoc {
 }
 //#endregion
 //#region src/declarations/stencil-private.d.ts
-interface SourceMap {
+interface SourceMap$1 {
   file: string;
   mappings: string;
   names: string[];
@@ -679,6 +666,8 @@ interface BuildFeatures {
   shadowDelegatesFocus: boolean;
   shadowModeClosed: boolean;
   shadowSlotAssignmentManual: boolean;
+  shadowClonable: boolean;
+  shadowSerializable: boolean;
   scoped: boolean;
   /**
    * Every component has a render function
@@ -695,6 +684,8 @@ interface BuildFeatures {
   vdomKey: boolean;
   vdomListener: boolean;
   vdomPropOrAttr: boolean;
+  /** True when at least one component uses the explicit `attr:`/`prop:` JSX prefix. */
+  vdomPropOrAttrPrefix: boolean;
   vdomRef: boolean;
   vdomStyle: boolean;
   vdomText: boolean;
@@ -913,7 +904,7 @@ interface RolldownChunkResult {
   isBrowserLoader: boolean;
   imports: string[];
   moduleFormat: ModuleFormat;
-  map?: RolldownSourceMap;
+  map?: SourceMap;
 }
 interface BundleModule {
   entryKey: string;
@@ -1092,6 +1083,7 @@ interface ComponentCompilerFeatures {
   hasVdomKey: boolean;
   hasVdomListener: boolean;
   hasVdomPropOrAttr: boolean;
+  hasVdomPropOrAttrPrefix: boolean;
   hasVdomRef: boolean;
   hasVdomRender: boolean;
   hasVdomStyle: boolean;
@@ -1102,6 +1094,7 @@ interface ComponentCompilerFeatures {
   htmlAttrNames: string[];
   htmlTagNames: string[];
   htmlParts: string[];
+  htmlSlots: string[];
   isUpdateable: boolean;
   /**
    * A plain component is one that doesn't have:
@@ -1174,6 +1167,16 @@ interface ComponentCompilerMeta extends ComponentCompilerFeatures {
   properties: ComponentCompilerProperty[];
   serializers: ComponentCompilerChangeHandler[];
   shadowDelegatesFocus: boolean;
+  /**
+   * Whether the shadow root is preserved when the host element is deep-cloned via
+   * `Node.cloneNode(true)`. Only applicable when encapsulation is 'shadow'.
+   */
+  shadowClonable: boolean;
+  /**
+   * Whether the shadow root is marked serializable for `Element.getHTML({ serializableShadowRoots: true })`.
+   * Only applicable when encapsulation is 'shadow'.
+   */
+  shadowSerializable: boolean;
   /**
    * Shadow DOM mode. 'open' (default) or 'closed'.
    * Only applicable when encapsulation is 'shadow'.
@@ -1510,6 +1513,7 @@ interface Module {
   htmlAttrNames: string[];
   htmlTagNames: string[];
   htmlParts: string[];
+  htmlSlots: string[];
   isCollectionDependency: boolean;
   isLegacy: boolean;
   jsFilePath: string;
@@ -1534,6 +1538,7 @@ interface Module {
   hasVdomKey: boolean;
   hasVdomListener: boolean;
   hasVdomPropOrAttr: boolean;
+  hasVdomPropOrAttrPrefix: boolean;
   hasVdomRef: boolean;
   hasVdomRender: boolean;
   hasVdomStyle: boolean;
@@ -1541,6 +1546,28 @@ interface Module {
   hasVdomXlink: boolean;
   hasSignalsImport: boolean;
 }
+interface Plugin$1 {
+  name?: string;
+  pluginType?: string;
+  load?: (id: string, context: PluginCtx) => Promise<string> | string;
+  resolveId?: (importee: string, importer: string, context: PluginCtx) => Promise<string> | string;
+  transform?: (sourceText: string, id: string, context: PluginCtx) => Promise<PluginTransformResults> | PluginTransformResults;
+}
+type PluginTransformResults = PluginTransformationDescriptor | string | null;
+interface PluginTransformationDescriptor {
+  code?: string;
+  map?: string;
+  id?: string;
+  diagnostics?: Diagnostic[];
+  dependencies?: string[];
+}
+interface PluginCtx {
+  config: Config;
+  sys: CompilerSystem;
+  fs: InMemoryFileSystem;
+  cache: Cache;
+  diagnostics: Diagnostic[];
+}
 interface PrerenderUrlResults {
   anchorUrls: string[];
   diagnostics: Diagnostic[];
@@ -1623,6 +1650,12 @@ interface TransformCssToEsmOutput {
     varName: string;
     importPath: string;
   }[];
+  /**
+   * Whether `output` itself has an observable side effect (a plain, untagged CSS file's
+   * generated module self-injects CSSStyleSheets; a Stencil component's tagged `styleUrl`
+   * output doesn't)
+   */
+  moduleSideEffects?: boolean;
 }
 interface PackageJsonData {
   name?: string;
@@ -1677,7 +1710,7 @@ interface CompilerWorkerContext {
   prepareModule(input: string, minifyOpts: any): Promise<{
     output: string;
     diagnostics: Diagnostic[];
-    sourceMap?: SourceMap;
+    sourceMap?: SourceMap$1;
   }>;
   prerenderWorker(prerenderRequest: PrerenderUrlRequest): Promise<PrerenderUrlResults>;
   transformCssToEsm(input: TransformCssToEsmInput): Promise<TransformCssToEsmOutput>;
@@ -1783,11 +1816,12 @@ interface StencilConfig {
    */
   outputTargets?: OutputTarget[];
   /**
-   * The plugins config can be used to add your own rolldown plugins.
-   * By default, Stencil does not come with Sass or PostCSS support.
+   * The plugins config can be used to add your own rolldown plugins, or Stencil's own
+   * legacy `resolveId`/`load`/`transform` style plugins (identified by a `pluginType`
+   * property). By default, Stencil does not come with Sass or PostCSS support.
    * However, either can be added using the plugin array.
    */
-  plugins?: any[];
+  plugins?: (Plugin$1 | Plugin)[];
   /**
    * Generate js source map files for all bundles.
    * Set to `true` to always generate source maps, `false` to never generate source maps.
@@ -1807,15 +1841,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`, Stencil will suppress diagnostics which warn about event names conflicting with native DOM event names. Defaults to `false`.
-   */
-  suppressReservedEventNameWarnings?: 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
@@ -1826,10 +1851,19 @@ interface StencilConfig {
    */
   rolldownConfig?: RolldownConfig;
   /**
-   * Sets if the JS browser files are minified or not. Stencil uses `terser` under the hood.
+   * Sets if the JS browser files are minified or not.
    * Defaults to `false` in dev mode and `true` in production mode.
    */
   minifyJs?: boolean;
+  /**
+   * Which minifier to use for JS output when `minifyJs` is enabled.
+   *
+   * - `oxc`: built into rolldown. Much faster than terser. Output may be slightly larger.
+   * - `terser`: slower, but currently produces the smallest output.
+   *
+   * Defaults to `oxc`.
+   */
+  jsMinifier?: 'terser' | 'oxc';
   /**
    * Sets if the CSS is minified or not.
    * Defaults to `false` in dev mode and `true` in production mode.
@@ -1841,7 +1875,8 @@ interface StencilConfig {
    */
   logger?: Logger;
   /**
-   * Compatibility and workaround flags for framework integration and bundler edge cases.
+   * Compatibility and workaround flags for framework/bundler edge cases
+   * and rarely-needed diagnostic suppressions.
    */
   compat?: ConfigCompat;
   /**
@@ -1912,8 +1947,8 @@ interface StencilConfig {
   maxConcurrentWorkers?: number;
   preamble?: string;
   rolldownPlugins?: {
-    before?: any[];
-    after?: any[];
+    before?: Plugin[];
+    after?: Plugin[];
   };
   entryComponentsHint?: string[];
   buildLogFilePath?: string;
@@ -1967,6 +2002,23 @@ interface StencilConfig {
    * Set whether unused dependencies should be excluded from the built output.
    */
   excludeUnusedDependencies?: boolean;
+  /**
+   * 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.
    *
@@ -1984,7 +2036,6 @@ interface StencilConfig {
    * @default []
    */
   collections?: string[];
-  stencilCoreResolvedId?: string;
 }
 /**
  * DOM patches for light-dom / scoped components that use `<slot>`.
@@ -2002,14 +2053,20 @@ interface StencilConfig {
  * 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). */
+  /** 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 for framework integration and bundler edge cases.
- * These are opt-in runtime behaviors that aren't needed by every project.
+ * 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 {
   /**
@@ -2040,6 +2097,15 @@ interface ConfigCompat {
    * See {@link LightDomPatches} for granular control. Defaults to `true`.
    */
   lightDomPatches?: boolean | LightDomPatches;
+  /**
+   * 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`.
+   */
+  suppressPublicNameWarnings?: boolean;
+  /**
+   * When `true`, Stencil will suppress diagnostics which warn about event names conflicting with native DOM event names. Defaults to `false`.
+   */
+  suppressEventNameWarnings?: boolean;
 }
 interface Config extends StencilConfig {
   buildAppCore?: boolean;
@@ -2139,11 +2205,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' | 'devServer' | 'compat' | 'fsNamespace' | 'hydratedFlag' | 'logLevel' | 'logger' | 'minifyCss' | 'minifyJs' | 'namespace' | 'outputTargets' | 'packageJsonFilePath' | 'rolldownConfig' | 'rootDir' | 'srcDir' | 'srcIndexHtml' | 'sys' | 'transformAliasedImportPaths'>;
+type StrictConfigFields = keyof Pick<Config, 'cacheDir' | 'devServer' | 'compat' | 'fsNamespace' | 'hydratedFlag' | 'jsMinifier' | '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
@@ -2158,6 +2224,17 @@ type ValidatedConfig = RequireFields<Config, StrictConfigFields> & {
   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`.
@@ -3718,6 +3795,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';
@@ -3758,6 +3851,35 @@ 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;
@@ -3985,7 +4107,7 @@ interface OutputTargetWww extends OutputTargetBase {
    */
   hashedFileNameLength?: number;
 }
-type OutputTarget = OutputTargetCopy | OutputTargetCustom | OutputTargetLoaderBundle | OutputTargetStandalone | OutputTargetSsr | OutputTargetSsrWasm | OutputTargetCollection | OutputTargetTypes | OutputTargetGlobalStyle | OutputTargetAssets | OutputTargetDistLazy | OutputTargetDocsJson | OutputTargetDocsCustom | OutputTargetDocsReadme | OutputTargetDocsVscode | OutputTargetDocsCustomElementsManifest | OutputTargetWww | OutputTargetStats;
+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}.
@@ -4202,9 +4324,11 @@ interface CompilerRequestResponse {
 interface TranspileOptions {
   /**
    * A component can be defined as a custom element by using `customelement`, or the
-   * component class can be exported by using `module`. Default is `customelement`.
+   * component class can be exported by using `module`. Set to `null` to leave the
+   * class's own export as-is (used with `componentMetadata: 'compilerstatic'` for
+   * unit-testing preprocessors). Default is `customelement`.
    */
-  componentExport?: 'customelement' | 'module' | string | undefined;
+  componentExport?: 'customelement' | 'module' | string | null | undefined;
   /**
    * Sets how and if component metadata should be assigned on the compiled
    * component output. The `compilerstatic` value will set the metadata to
@@ -4239,8 +4363,11 @@ interface TranspileOptions {
   /**
    * How component styles should be associated to the component. The `static`
    * setting will assign the styles as a static getter on the component class.
+   * Set to `null` to skip the assignment entirely (and leave any `styleUrl`
+   * import unresolved) - useful for unit-testing preprocessors that don't
+   * need real stylesheets.
    */
-  style?: 'static' | string | undefined;
+  style?: 'static' | string | null | undefined;
   /**
    * How style data should be added for imports. For example, the `queryparams` value
    * adds the component's tagname and encapsulation info as querystring parameter
@@ -4301,28 +4428,51 @@ interface TranspileOptions {
    */
   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.
+   * 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, {
-   *   extraFiles: {
-   *     './base-component.ts': baseComponentSourceText,
+   *   resolveImport: (specifier, importer) => {
+   *     const resolved = require.resolve(specifier, { paths: [path.dirname(importer)] });
+   *     return { code: fs.readFileSync(resolved, 'utf8'), path: resolved };
    *   },
    * });
    * ```
    */
-  extraFiles?: Record<string, string>;
+  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;
 }
-type CompileTarget = 'latest' | 'esnext' | 'es2020' | 'es2019' | 'es2018' | 'es2017' | 'es2015' | string | undefined;
+/**
+ * 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' | 'es2022' | 'es2020' | 'es2019' | 'es2018' | 'es2017' | string | undefined;
 interface TranspileResults {
   code: string;
   data?: any[];
@@ -4348,9 +4498,16 @@ interface TransformOptions {
   styleImportData: 'queryparams' | null;
   target?: string;
   /**
-   * @see {@link TranspileOptions.extraFiles}
+   * @see {@link TranspileOptions.resolveImport}
    */
-  extraFiles?: Record<string, string>;
+  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;
@@ -4371,4 +4528,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, ConfigCompat, 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, LightDomPatches, LoadConfigInit, LoadConfigResults, LogLevel, Logger, LoggerLineUpdater, LoggerTimeSpan, NodeResolveConfig, OptimizeCssInput, OptimizeCssOutput, OptimizeJsInput, OptimizeJsOutput, OutputTarget, OutputTargetAssets, OutputTargetBase, OutputTargetBaseNext, OutputTargetBuild, OutputTargetCollection, OutputTargetCopy, OutputTargetCustom, OutputTargetDistLazy, 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 };
+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 };

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

@@ -1,3 +1,5 @@
+import "rolldown";
+import "typescript";
 //#region src/declarations/stencil-private.d.ts
 /**
  * Information about a type used in a Stencil component or exported
@@ -123,6 +125,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
    */