@staticbolt/core 1.0.0-beta.3 → 1.0.0-beta.31

package/lib/plugins/index.d.mts

@@ -1,9 +1,8 @@
 import postcss from "postcss";
-import { Config } from "svgo";
 import * as babel from "@babel/core";
 import { Pluggable } from "unified";
 import { Plugin } from "@staticbolt/core";
-
+import { Config } from "svgo";
 //#region src/plugins/analyze-output/analyze-output-plugin.d.ts
 interface AnalyzeOutputOptions {
   /**
@@ -31,18 +30,28 @@ interface AnalyzeOutputOptions {
    */
   maxFileSize?: Record<string, number> | false;
 }
+/**
+ * Analyzes the production build output and reports three things:
+ *
+ * - Missing: files the HTML pages reference but that are not in the output directory (errors).
+ * - Unused: files in the output directory no page reaches (warnings, deleted when "deleteUnused" is set).
+ * - Oversized: files above the per-extension limit in "maxFileSize" (warnings, largest first).
+ *
+ * Notes:
+ *
+ * - Runs after the build and only in production.
+ * - Reachability is walked from HTML pages only, so anything reachable through another entry point counts as unused.
+ * - HTML files are never listed as unused or deleted.
+ * - Empty directories under the output are removed on every run, not just when deleting unused files.
+ * - "exclude" is matched against paths relative to the output directory and applies to every report, so a file a later plugin
+ *   writes (a service worker, say) can be referenced without being reported missing.
+ */
 declare function analyzeOutputPlugin(options?: AnalyzeOutputOptions): Plugin;
 //#endregion
 //#region src/plugins/bundle-packages/bundle-packages-plugin.d.ts
 interface BundlePackagesOptions {
   /** Output directory for bundled `node_modules` packages, relative to the build output directory. */
   packagesDir?: string;
-  /**
-   * Whether to use Terser for minification to reduce the final bundle size.
-   *
-   * @default false
-   */
-  minifyUsingTerser?: boolean;
   /**
    * Bundles specific packages into a single chunk for optimized loading.
    *
@@ -80,8 +89,22 @@ interface BundlePackagesOptions {
   }>>;
 }
 /**
- * Bundles each `node_modules` package and its dependencies into separate files under `packagesDir`. The plugin scans files for
- * imports and uses esbuild's tree-shaking capabilities to generate the bundles.
+ * Bundles every "node_modules" package imported anywhere in the project into its own file under "packagesDir" and rewrites the
+ * imports to point at it. Specifiers are collected across the whole codebase first, so esbuild can tree-shake each package down
+ * to what is actually used.
+ *
+ * Notes:
+ *
+ * - Runs in both modes; minification and tree-shaking are production-only.
+ * - Bare imports in scripts and "<script src>" tags resolving into "node_modules" are both redirected; a script tag is counted as a
+ *   side-effect import.
+ * - A "<link rel=stylesheet>" shipped by a package is moved next to the package output, keeping its path inside the package. Other
+ *   file types stay where they resolve, under "node_modules".
+ * - Dots in the output path become underscores ("highlight.js" becomes "highlight_js"), so a package cannot collide with the file
+ *   bundled from it.
+ * - "chunks" merges packages into one file and renames their default imports to "default_<package>" so they share a module scope,
+ *   which is what CommonJS packages need to work in the browser.
+ * - A package first discovered while bundling another one is bundled right away, then re-bundled once its specifiers are known.
  */
 declare function bundlePackagesPlugin(options?: BundlePackagesOptions): Plugin;
 //#endregion
@@ -120,6 +143,22 @@ interface ConvertImageOptions {
    */
   exclude?: string[];
 }
+/**
+ * Converts the images matched by "include" to a single target format with sharp, and rewrites every reference to them.
+ *
+ * References are updated wherever the sources pipeline sees them (HTML attributes, styles, scripts, web manifest); an "image/*"
+ * type on the tag or manifest entry is rewritten too. In scripts, "_img.<ext>" expressions are replaced with the format string,
+ * so the same code resolves to the original extension in development and to the converted one in production.
+ *
+ * Quality and preset can be overridden per file through the filename: "hero-q:75-p:picture.jpg".
+ *
+ * Notes:
+ *
+ * - Conversion happens after the build and only in production; development keeps serving the originals untouched.
+ * - The output mirrors the source path relative to the project root, with only the extension replaced.
+ * - Converted sources are published on "pluginData.convertedImages" so copy-assets does not copy the originals over them.
+ * - "preset" is a WebP-only option and is ignored by the other formats.
+ */
 declare function convertImagePlugin(options?: ConvertImageOptions): Plugin;
 //#endregion
 //#region src/plugins/copy-assets/copy-assets-plugin.d.ts
@@ -143,6 +182,19 @@ interface CopyAssetsOptions {
    */
   publicDirectory?: string;
 }
+/**
+ * Copies asset files into the output directory at the end of a production build.
+ *
+ * Two passes: files matching "include" keep their path relative to the project root, while everything under "publicDirectory" is
+ * copied to the output root with that prefix dropped (e.g. "public/favicon.ico" becomes "<outdir>/favicon.ico").
+ *
+ * Notes:
+ *
+ * - Runs after the build and only in production.
+ * - Existing output files are never overwritten, and assets other plugins already emitted (converted images, optimized SVGs) are
+ *   skipped so the originals cannot replace them.
+ * - "exclude" applies to both passes; the public pass also copies dotfiles.
+ */
 declare function copyAssetsPlugin(options?: CopyAssetsOptions): Plugin;
 //#endregion
 //#region src/plugins/custom-ease/easing-functions/types.d.ts
@@ -264,6 +316,22 @@ interface CustomEasePluginOptions {
    */
   samples?: number;
 }
+/**
+ * Replaces named easing calls with plain CSS values at build time, so there is nothing to resolve at runtime. Simple curves
+ * become a "cubic-bezier()" string, computed ones (springs, bounces, elastics) are sampled into a "linear()" function.
+ *
+ * Three places, each with its own switch: CSS declarations (on by default, "--ease-*()" calls), JavaScript
+ * ("cssLinear.outCubic()", opt-in) and inline HTML "style" attributes (opt-in).
+ *
+ * Notes:
+ *
+ * - Runs in development and production alike.
+ * - JS call names are camelCase and matched kebab-cased, so "cssLinear.outCubic()" resolves the "out-cubic" definition.
+ * - Anything that does not resolve is left exactly as written: unknown names, unbalanced parentheses, or arguments that are not
+ *   plain numbers (in JS they must be numeric literals).
+ * - "customEase" entries are merged over the predefined set, so reusing a name overrides it.
+ * - "samples" trades output size for accuracy; it only affects easings that end up as "linear()".
+ */
 declare function customEasePlugin(options?: CustomEasePluginOptions): Plugin;
 //#endregion
 //#region src/plugins/i18n/i18n-plugin.d.ts
@@ -305,6 +373,18 @@ interface I18nPluginOptions {
    */
   placeholderPrefix?: string;
 }
+/**
+ * Adds internationalization: every page is emitted once per locale with its translation markers resolved, and scripts get a set
+ * of compile-time helpers. Returns the three plugins that do the work (HTML, scripts, CLI) sharing the same resolved options.
+ *
+ * Translations live in one JSON file per locale inside "localesDirectory" ("en.json", "ar.json", ...). Nested objects turn into
+ * dot-notated keys, and values can carry "{{ name=fallback }}" placeholders.
+ *
+ * Notes:
+ *
+ * - The default locale is emitted at the original paths; the others go under a directory named after the locale.
+ * - Locale files are read once and cached for the whole process, so a running dev server does not pick up edits to them.
+ */
 declare function i18nPlugin(options?: I18nPluginOptions): Plugin[];
 //#endregion
 //#region src/plugins/import-as-string/types.d.ts
@@ -334,6 +414,23 @@ interface ImportAsStringOptions {
 type import_as_string = (filePath: string, options?: ImportAsStringOptions) => string;
 //#endregion
 //#region src/plugins/import-as-string/import-as-string-plugin.d.ts
+/**
+ * Replaces "import_as_string(path, options?)" calls in scripts with the contents of that file, inlined as a string literal at
+ * build time.
+ *
+ * By default the file is taken from the build, so what lands in the string is the processed version, and "minify" and "format"
+ * control how it is printed. With "process: false" the file is read straight from disk instead, untouched, and with
+ * "templateLiteral: true" the value is inlined as a template literal rather than a quoted string.
+ *
+ * Notes:
+ *
+ * - The path and the options object have to be statically resolvable; anything dynamic is reported and the call is left in the
+ *   code, where it will fail at runtime.
+ * - The path is resolved relative to the file doing the importing.
+ * - "minify" and "format" only apply in production; in development the file is inlined as it is.
+ * - An inlined file is dropped from the output unless it is an entry point in its own right.
+ * - Editing an inlined file recompiles the scripts that inline it.
+ */
 declare function importAsStringPlugin(): Plugin;
 //#endregion
 //#region src/plugins/load-sources/load-sources-plugin.d.ts
@@ -341,6 +438,16 @@ interface LoadSourcesPluginOptions {
   include: string[];
   exclude?: string[];
 }
+/**
+ * Registers the files matched by "include" as entry points: the roots the build starts from, with everything they reference
+ * discovered, transformed and emitted along with them.
+ *
+ * Notes:
+ *
+ * - Patterns are matched from the project root at startup, and matching nothing is reported as an error.
+ * - Matched files are watched, so creating or deleting one updates the entry point set without a restart.
+ * - Any file type staticbolt can load works as an entry point, HTML, markdown, scripts and styles alike.
+ */
 declare function loadSourcesPlugin(options: LoadSourcesPluginOptions): Plugin;
 //#endregion
 //#region src/plugins/robots-text/robots-text-plugin.d.ts
@@ -364,6 +471,16 @@ interface RobotsTextOptions {
   /** The path to the sitemap file. */
   sitemapUrl?: string;
 }
+/**
+ * Writes a "robots.txt" into the output directory from the rules given in the options.
+ *
+ * Notes:
+ *
+ * - Production only, and only when at least one rule is configured; with an empty "rules" list nothing is written.
+ * - Every rule becomes a "User-agent" block followed by its "Allow" and "Disallow" lines, in the order they are listed.
+ * - "sitemapUrl" appends a "Sitemap:" line as given, so pass the full URL.
+ * - The file is written straight to disk after the build and is not part of the build graph.
+ */
 declare function robotsTextPlugin(options?: RobotsTextOptions): Plugin;
 //#endregion
 //#region src/plugins/service-worker/service-worker-plugin.d.ts
@@ -371,13 +488,13 @@ interface ServiceWorkerOptions {
   /**
    * Glob patterns for matching files.
    *
-   * @default ["**\/*"]
+   * @default ["**\/*.{js,wasm,css,html}"]
    */
   globPatterns?: string[];
   /**
    * Glob patterns for files to ignore.
    *
-   * @default ["**\/node_modules/**\/*"]
+   * @default ["**\/node_modules\/**\/*"]
    */
   globIgnores?: string[];
   /**
@@ -407,13 +524,13 @@ interface ServiceWorkerOptions {
   /**
    * Whether to skip waiting and immediately activate the service worker.
    *
-   * @default true
+   * @default false
    */
   skipWaiting?: boolean;
   /**
    * Whether the service worker should claim all available clients.
    *
-   * @default true
+   * @default false
    */
   clientsClaim?: boolean;
   /**
@@ -425,7 +542,7 @@ interface ServiceWorkerOptions {
   /**
    * Cleans up outdated caches during service worker activation.
    *
-   * @default true
+   * @default false
    */
   cleanupOutdatedCaches?: boolean;
   /**
@@ -448,7 +565,12 @@ interface ServiceWorkerOptions {
   modifyURLPrefix?: Record<string, string>;
 }
 /**
- * Please don't forget to register the service worker in your HTML file.
+ * Generates a Workbox service worker from the finished output directory, precaching every file that matches "globPatterns".
+ *
+ * The options are handed to workbox-build's "generateSW", with "swDest" resolved inside the output directory and the project's
+ * browserslist used as the Babel target.
+ *
+ * Registering it is up to the page:
  *
  * ```ts
  * import { Workbox } from "workbox-window";
@@ -458,6 +580,13 @@ interface ServiceWorkerOptions {
  *   wb.register();
  * }
  * ```
+ *
+ * Notes:
+ *
+ * - Production only, and it runs after the build, so it sees the final files, copied assets included.
+ * - The precache manifest is built from the output directory; files larger than "maximumFileSizeToCacheInBytes" (2 MB by default)
+ *   are left out.
+ * - The worker is written straight to disk and is not part of the build graph.
  */
 declare function serviceWorkerPlugin(options?: ServiceWorkerOptions): Plugin;
 //#endregion
@@ -488,6 +617,18 @@ interface SitemapOptions {
    */
   exclude?: string[];
 }
+/**
+ * Writes a "sitemap.xml" listing the HTML pages that ended up in the output directory.
+ *
+ * Notes:
+ *
+ * - Production only, and only when "sitemapUrl" is set; without it nothing is generated.
+ * - The pages are globbed from the output directory after the build, so the list reflects what was really emitted, and "include"
+ *   and "exclude" are matched there as well.
+ * - Each entry is the URL of the file's directory with a trailing slash: "blog/post/index.html" becomes ".../blog/post/", and a
+ *   page that is not an "index.html" collapses onto the URL of its parent directory.
+ * - Only "<loc>" is emitted, no "lastmod", "changefreq" or "priority".
+ */
 declare function sitemapPlugin(options?: SitemapOptions): Plugin;
 //#endregion
 //#region src/plugins/svgo/svgo-plugin.d.ts
@@ -514,11 +655,17 @@ interface svgoOptions {
   svgoConfig?: Config;
 }
 /**
- * Optimize SVG files and SVG tags in HTML using `svgo`.
+ * Optimizes SVGs with svgo, both the inline "<svg>" tags of a page and the files matched by "include", which are optimized and
+ * written to the output directory.
  *
- * For CSS inlined SVGs, use a PostCSS plugin like `cssnano` instead.
+ * Notes:
  *
- * **Production Only**
+ * - Production only.
+ * - Results are cached per SVG string, so an icon repeated across many pages goes through svgo once per build.
+ * - Files it wrote are published on "pluginData.optimizedSvgList" so copy-assets does not put the originals over them.
+ * - The default config is svgo's "preset-default" with id cleanup, hidden-element removal and unknown-attribute removal turned off,
+ *   so ids and hooks the rest of the page relies on survive. Passing "svgoConfig" replaces that default entirely.
+ * - SVGs inlined in CSS are out of reach; use a PostCSS plugin such as cssnano for those.
  */
 declare function svgoPlugin(options?: svgoOptions): Plugin;
 //#endregion
@@ -533,6 +680,16 @@ interface TransformCssOptions {
    */
   loadConfig?: boolean;
 }
+/**
+ * Runs PostCSS plugins over every stylesheet in the build, the "<style>" tags of a page included.
+ *
+ * Notes:
+ *
+ * - The plugins given in the options run first, followed by the ones from the PostCSS config file when "loadConfig" is on.
+ * - That config is read once at startup, with the build mode and the project's browserslist as its context.
+ * - With no plugins at all the pass is skipped.
+ * - A plugin error is reported for the stylesheet it happened in and the build carries on.
+ */
 declare function transformCssPlugin(options?: TransformCssOptions): Plugin;
 //#endregion
 //#region src/plugins/transform-js/transform-js-plugin.d.ts
@@ -540,6 +697,18 @@ interface TransformJsPluginOptions {
   presets?: babel.PluginItem[];
   plugins?: babel.PluginItem[];
 }
+/**
+ * Runs Babel over every script in the build, TypeScript and JSX included.
+ *
+ * Presets are applied in order: TypeScript (all extensions, JSX enabled), preset-env against the project's browserslist, then the
+ * project's own Babel config, then whatever the options add.
+ *
+ * Notes:
+ *
+ * - "_production" is substituted with the build mode, so a check like "if (_production)" is resolved at build time.
+ * - Module syntax is preserved; ".ts", ".jsx" and ".tsx" files only change their output path to ".js".
+ * - The result is resolved and loaded again, so imports a Babel plugin introduces still become part of the build.
+ */
 declare function transformJsPlugin(options?: TransformJsPluginOptions): Plugin;
 //#endregion
 //#region src/plugins/web-manifest/web-manifest-plugin.d.ts
@@ -557,6 +726,15 @@ interface WebManifestOptions {
    */
   outfile?: string;
 }
+/**
+ * Emits the web app manifest at "outfile" and repoints the links to it.
+ *
+ * Notes:
+ *
+ * - Only the file at "manifestPath" counts as the manifest; links to any other JSON are left alone.
+ * - It is rebased once the transforms are done, so the paths inside it (icons, screenshots) keep resolving from the new location.
+ * - The links are rewritten in production only; while serving, the manifest stays at its source path.
+ */
 declare function webManifestPlugin(options?: WebManifestOptions): Plugin;
 //#endregion
 //#region src/plugins/write-files/write-files-plugin.d.ts
@@ -575,6 +753,12 @@ interface WriteFilesOptions {
    * @default [ ]
    */
   exclude?: string[];
+  /**
+   * How many worker threads may minify or format output files at once.
+   *
+   * @default One per core, up to eight
+   */
+  concurrency?: number;
   minify?: {
     /**
      * Whether to minify output.
@@ -616,6 +800,22 @@ interface WriteFilesOptions {
     exclude?: string[];
   };
 }
+/**
+ * Emits the build: everything that survived the pipeline is stringified and written under the output directory, with binary
+ * assets copied over as they are.
+ *
+ * Notes:
+ *
+ * - Production only. The dev server serves from memory and writes nothing.
+ * - "clean" removes the output directory before the build starts.
+ * - "include" and "exclude" are matched against the source path, and anything a plugin excluded from emitting is skipped.
+ * - "minify" and "format" carry their own patterns; turning both on for the same file logs a warning.
+ * - A file whose path would land outside the output directory is reported and skipped.
+ * - Formatting and minifying are the slow part of printing a file, so any plugin willing to hand its final pass over gets taken up
+ *   on it: the file is written as it came out and its pass goes to a pool of worker threads chewing through them while the files
+ *   behind it are still being written. The pool is drained before this hook returns, so the output directory is settled by the
+ *   time anything else runs.
+ */
 declare function writeFilesPlugin(options: WriteFilesOptions): Plugin;
 //#endregion
 //#region src/plugins/html-build-time-script/html-build-time-script.d.ts
@@ -633,8 +833,33 @@ interface HtmlBuildTimeScriptOptions {
    * @default "full-dom"
    */
   fullDomAttribute?: string;
+  /**
+   * The name of the attribute on the script tag that holds a JSON object, whose entries are exposed as globals to the script
+   * during execution.
+   *
+   * @default "context"
+   */
   contextAttribute?: string;
 }
+/**
+ * Executes script tags marked with "build-time" during the build and keeps whatever they did to the page. The tag itself never
+ * reaches the output.
+ *
+ * Attributes (names configurable via HtmlBuildTimeScriptOptions):
+ *
+ * - "build-time": execute this tag, inline or through "src".
+ * - "full-dom": run against a jsdom document instead of the lighter node-html-parser AST.
+ * - "context": a JSON object whose entries become globals for that script.
+ *
+ * Scripts run in "node:vm" with "document", "window", "StaticBolt" (the app), "__filepath" and "__id" in scope. "context" entries
+ * are applied last, so they can shadow those names; if the JSON fails to parse the script still runs without them.
+ *
+ * Notes:
+ *
+ * - "full-dom" needs a fully constructed page (a head and a body), so place this plugin last when using it.
+ * - Failures are per tag: the error is logged and the rest of the page carries on.
+ * - In development the files each page executed are tracked, so editing one of them recompiles the pages that used it.
+ */
 declare function htmlBuildTimeScript(options?: HtmlBuildTimeScriptOptions): Plugin;
 //#endregion
 //#region src/plugins/html-bundle-script/html-bundle-script-plugin.d.ts
@@ -664,6 +889,8 @@ interface HtmlBundleScriptOptions {
   /**
    * The HTML attribute name that specifies the output file path for the bundled script.
    *
+   * The attribute value is always resolved relative to the output directory, regardless of where the HTML file lives.
+   *
    * @default "bundle-out"
    */
   bundleOutAttribute?: string;
@@ -683,24 +910,33 @@ interface HtmlBundleScriptOptions {
    * @default "bundle-externals-exclude"
    */
   externalsExcludeAttribute?: string;
+  /**
+   * The HTML attribute name that switches the bundle output format from ESM to IIFE.
+   *
+   * The attribute is a boolean flag; its value is ignored.
+   *
+   * @default "iife"
+   */
+  iifeAttribute?: string;
 }
 /**
- * A plugin that bundles `<script>` tags in HTML files using esbuild.
+ * Bundles script tags in HTML files with esbuild. Opt-in per tag.
  *
- * Bundling is opt-in per script tag via the `bundle` attribute (configurable via {@link HtmlBundleScriptOptions.bundleAttribute}).
+ * Attributes (names configurable via HtmlBundleScriptOptions):
  *
- * **Inlining vs. separate file**
+ * - "bundle": bundle this tag.
+ * - "bundle-out": output path, resolved from the output directory, not from the HTML file.
+ * - "bundle-externals" / "bundle-externals-exclude": semicolon-separated globs, override the plugin defaults for this tag.
+ * - "iife": emit an IIFE instead of ESM.
  *
- * - Inline script, no `bundle-out` attribute —> bundled output replaces the tag's content in place.
- * - Inline script, `bundle-out` attribute set —> tag content is cleared and `src` is set to the output file.
- * - `src` script, no `bundle-out` attribute —> bundle is written to `{filename}.bundle.js` and `src` is updated to point to it.
- * - `src` script, `bundle-out` attribute set —> bundle is written to the specified path and `src` is updated to point to it.
+ * Without "bundle-out", an inline script is bundled in place and a "src" script is written to "{filename}.bundle.js" next to the
+ * original. With it, "src" is pointed at the output path and inline content is cleared.
  *
- * **Externals resolution**
+ * Notes:
  *
- * Glob patterns in {@link HtmlBundleScriptOptions.externals} and {@link HtmlBundleScriptOptions.externalsExclude} are matched
- * against each resolved module path. A module is treated as external if it matches `externals` and does not match
- * `externalsExclude`.
+ * - Bundling only runs in production; in dev the attributes are just stripped. They never reach the output either way.
+ * - If the target output path is already bundled, the work is skipped and "src" is simply pointed at it.
+ * - "iife" only changes the esbuild format; the tag's "type" is untouched, so remove "type=module" yourself if needed.
  */
 declare function htmlBundleScriptPlugin(options?: HtmlBundleScriptOptions): Plugin;
 //#endregion
@@ -713,8 +949,62 @@ interface HtmlBundleStyleOptions {
    */
   bundleAttribute?: string;
 }
+/**
+ * Inlines the "@import" tree of a stylesheet, so the tag ends up self-contained. Opt-in per tag through the "bundle" attribute
+ * (configurable via HtmlBundleStyleOptions) on a "<link rel=stylesheet>" or a "<style>" tag.
+ *
+ * Bundling happens in place: a "<style>" tag gets the resolved CSS as its content, and a linked file is rewritten with its
+ * imports inlined while "href" stays as it is.
+ *
+ * Notes:
+ *
+ * - Production only. In development nothing runs and the "bundle" attribute is left on the tag.
+ * - "<link rel=preload as=style>" is always bundled, with or without the attribute, since a preloaded stylesheet has to carry
+ *   everything it needs.
+ * - A linked stylesheet is bundled once even when several pages link to it; they share the same file.
+ * - Imports resolve the way every other source does: relative paths, path aliases and packages, through the build's resolver.
+ * - Imported files are pulled from the build (so transforms other plugins made are included) and only read from disk when they are
+ *   not part of it. They stay in the output as separate files, now unreferenced. Their "url()" references are rebased onto the
+ *   bundle's location.
+ * - Conditions ("layer", "supports()", media) wrap the imported rules, a file imported twice under the same conditions is kept
+ *   where it was imported last, as in a browser, and imports from other origins are hoisted to the top.
+ */
 declare function htmlBundleStylePlugin(options?: HtmlBundleStyleOptions): Plugin;
 //#endregion
+//#region src/plugins/html-env-only/html-environment-only-plugin.d.ts
+interface HtmlEnvOnlyOptions {
+  /**
+   * The HTML attribute name that marks a tag as development-only.
+   *
+   * Tags with this attribute are removed at build time and kept (with the attribute stripped) during dev serve.
+   *
+   * @default "dev-only"
+   */
+  devOnlyAttribute?: string;
+  /**
+   * The HTML attribute name that marks a tag as production-only.
+   *
+   * Tags with this attribute are removed during dev serve and kept (with the attribute stripped) at build time.
+   *
+   * @default "production-only"
+   */
+  productionOnlyAttribute?: string;
+}
+/**
+ * Removes the HTML tags that do not belong in the current environment.
+ *
+ * Attributes (names configurable via HtmlEnvOnlyOptions):
+ *
+ * - "dev-only": kept while serving, removed from the production build.
+ * - "production-only": kept in the production build, removed while serving.
+ *
+ * Notes:
+ *
+ * - Works on any element, and removal takes the element's whole subtree with it.
+ * - Where the tag survives, the marker attribute is stripped from the output.
+ */
+declare function htmlEnvOnlyPlugin(options?: HtmlEnvOnlyOptions): Plugin;
+//#endregion
 //#region src/plugins/html-fragment/html-fragment-plugin.d.ts
 interface HtmlFragmentOptions {
   /**
@@ -724,6 +1014,16 @@ interface HtmlFragmentOptions {
    */
   tagName?: string;
 }
+/**
+ * Replaces every "<fragment>" element (tag name configurable via HtmlFragmentOptions) with its own content, so the wrapper leaves
+ * no trace in the output. Handy for grouping markup a layout or an insert has to treat as one node.
+ *
+ * Notes:
+ *
+ * - Runs in development and production alike.
+ * - The content is re-parsed from the element's inner HTML and trimmed, so surrounding whitespace is dropped.
+ * - Fragments nest: the page is rescanned after each replacement, so a fragment inside another one is unwrapped as well.
+ */
 declare function htmlFragmentPlugin(options?: HtmlFragmentOptions): Plugin;
 //#endregion
 //#region src/plugins/html-iife-script/html-iife-script-plugin.d.ts
@@ -735,6 +1035,16 @@ interface HtmlIifeScriptOptions {
    */
   iifeAttribute?: string;
 }
+/**
+ * Wraps the body of a script tag marked with "iife" (attribute configurable via HtmlIifeScriptOptions) in an immediately invoked
+ * function expression, so its declarations stay out of the global scope.
+ *
+ * Notes:
+ *
+ * - The attribute is stripped in both modes, but the wrapping only happens in production.
+ * - Inline scripts only: a tag with a "src" attribute is reported as an error and left alone.
+ * - Meant for classic scripts. A module already has its own scope, so wrapping one buys nothing.
+ */
 declare function htmlIifeScriptPlugin(options?: HtmlIifeScriptOptions): Plugin;
 //#endregion
 //#region src/plugins/html-inline-script/html-inline-script-plugin.d.ts
@@ -746,6 +1056,22 @@ interface HtmlInlineScriptOptions {
    */
   inlineAttribute?: string;
 }
+/**
+ * Replaces a script tag marked with "inline" (attribute configurable via HtmlInlineScriptOptions) with the code it points at, so
+ * the page ships one request fewer. The "src" attribute is dropped and the code becomes the tag's content.
+ *
+ * The source can be a local file or a remote URL; a URL is downloaded at build time, cached per page directory and URL, and kept
+ * out of the output.
+ *
+ * Notes:
+ *
+ * - The attribute is stripped in both modes, but the inlining only happens in production.
+ * - The tag must have a "src" and no content of its own; anything else is reported as an error and left alone.
+ * - A local file has to be part of the build already, otherwise its metadata is not found and nothing is inlined.
+ * - The inlined copy is rebased onto the HTML file, so its relative imports keep resolving, and the original file stays in the
+ *   output unless something removes it.
+ * - The tag's "type" decides whether the inlined code is treated as a module, not the original file.
+ */
 declare function htmlInlineScriptPlugin(options?: HtmlInlineScriptOptions): Plugin;
 //#endregion
 //#region src/plugins/html-inline-style/html-inline-style-plugin.d.ts
@@ -757,6 +1083,21 @@ interface HtmlInlineStyleOptions {
    */
   inlineAttribute?: string;
 }
+/**
+ * Turns a "<link rel=stylesheet>" marked with "inline" (attribute configurable via HtmlInlineStyleOptions) into a "<style>" tag
+ * holding the stylesheet itself, so the page ships one request fewer.
+ *
+ * The "href" can point at a local file or a remote URL; a URL is downloaded at build time, cached per page directory and URL, and
+ * kept out of the output.
+ *
+ * Notes:
+ *
+ * - The attribute is stripped in both modes, but the inlining only happens in production.
+ * - The link's remaining attributes are copied onto the "<style>" tag; "href" and "rel" are dropped.
+ * - A local file has to be part of the build already, otherwise its metadata is not found and nothing is inlined.
+ * - The inlined copy is rebased onto the HTML file, so relative "url()" and "@import" paths keep resolving, and the original file
+ *   stays in the output unless something removes it.
+ */
 declare function htmlInlineStylePlugin(options?: HtmlInlineStyleOptions): Plugin;
 //#endregion
 //#region src/plugins/html-inline-svg/html-inline-svg-plugin.d.ts
@@ -768,6 +1109,21 @@ interface HtmlInlineSvgOptions {
    */
   inlineAttribute?: string;
 }
+/**
+ * Replaces an "<svg inline src=...>" placeholder (attribute configurable via HtmlInlineSvgOptions) with the actual SVG element
+ * from the file, so it can be styled and scripted like any other markup.
+ *
+ * The "src" can point at a local file or a remote URL; a URL is downloaded at build time, cached per page directory and URL, and
+ * kept out of the output.
+ *
+ * Notes:
+ *
+ * - Runs in development and production alike.
+ * - Every attribute left on the placeholder is copied onto the inlined element and overrides what the file declares, "viewBox" and
+ *   "fill" included.
+ * - A local file has to be part of the build already, otherwise its metadata is not found and the placeholder is left as it is.
+ * - Only the "<svg>" element of the file is taken; anything around it in the file is dropped.
+ */
 declare function HtmlInlineSvgPlugin(options?: HtmlInlineSvgOptions): Plugin;
 //#endregion
 //#region src/plugins/html-inline-text/html-inline-text-plugin.d.ts
@@ -791,6 +1147,18 @@ interface HtmlInlineTextOptions {
    */
   noEscapeAttribute?: string;
 }
+/**
+ * Replaces an "<inline-text src=...>" tag with the contents of the file it points at (tag and attribute names configurable via
+ * HtmlInlineTextOptions). The text is HTML-escaped unless the tag carries "no-escape", which inserts it as markup.
+ *
+ * Notes:
+ *
+ * - Runs in development and production alike.
+ * - The file is read straight from disk, so it is not a build source and no other plugin transforms it.
+ * - Contents are cached per path for the whole build, escaping included: when two tags point at the same file, the first one
+ *   decides whether both end up escaped.
+ * - The cache is dropped when the file changes, and pages that inlined it are recompiled, so the dev server stays in sync.
+ */
 declare function htmlInlineTextPlugin(options?: HtmlInlineTextOptions): Plugin;
 //#endregion
 //#region src/plugins/html-insert/html-insert-plugin.d.ts
@@ -820,9 +1188,26 @@ interface HtmlInsertOptions {
    */
   whereAttribute?: string;
 }
+/**
+ * Moves the content of an "<insert>" tag into any element on the same page, addressed by a CSS selector, then removes the tag
+ * itself (names configurable via HtmlInsertOptions).
+ *
+ * Attributes:
+ *
+ * - "selector": the CSS selector of the target element.
+ * - "where": where the content lands, one of "beforebegin", "afterbegin", "beforeend" (the default) or "afterend".
+ * - "replace": swap the target element for the content instead of inserting into it.
+ *
+ * Notes:
+ *
+ * - Runs in development and production alike, and only searches the page the tag lives on.
+ * - A tag whose target is not on the page yet is left untouched, since layouts and pages are assembled in several passes. Any tag
+ *   still unresolved at the end of the build is reported and stays in the output.
+ * - An "<insert>" with no content or no selector is reported and left alone.
+ */
 declare function htmlInsertPlugin(options?: HtmlInsertOptions): Plugin;
 //#endregion
-//#region src/plugins/html-layout/html-layout-plugin.d.ts
+//#region src/plugins/html-layout/options.d.ts
 interface HtmlLayoutOptions {
   /**
    * Tag names registered as valid HTML elements. Each name is also the required file suffix — e.g. `"layout"` means files must
@@ -849,7 +1234,7 @@ interface HtmlLayoutOptions {
    * attributes and any keys loaded via `dataSource`. Inline attributes take priority over `dataJson` keys; `dataJson` keys take
    * priority over `dataSource` keys.
    *
-   * @default "data"
+   * @default "dataJson"
    */
   dataJsonAttribute?: string;
   /**
@@ -886,6 +1271,33 @@ interface HtmlLayoutOptions {
    */
   removeAttributeAttribute?: string;
 }
+//#endregion
+//#region src/plugins/html-layout/html-layout-plugin.d.ts
+/**
+ * Composes pages out of reusable "<layout>" and "<part>" files (tag names configurable via HtmlLayoutOptions). The tag is
+ * replaced by the file it points at, the tag's children are distributed into the file's "<slot>" elements, and the scripts and
+ * styles the file declares are merged into the page.
+ *
+ * Attributes on the tag:
+ *
+ * - "src": the file to inline. Its name must end with ".<tag>.html", so "<part>" loads "*.part.html".
+ * - "dataSource" and "dataJson": data for the file's placeholders, as a path to a JSON file and as an inline JSON string.
+ * - Anything else on the tag is data as well.
+ *
+ * Inside the file, "{{ expression }}" is evaluated as JavaScript with the data exposed as "$data" (a leading backslash escapes a
+ * placeholder, and an expression returning undefined or an object is an error), while "add-attr-<name>" and "remove-attr-<name>"
+ * toggle a boolean attribute when their value is non-empty and not "false".
+ *
+ * Notes:
+ *
+ * - Data precedence, lowest first: the "dataSource" file, then "dataJson", then the tag's own attributes.
+ * - Layouts nest, and a page is rescanned after each expansion, so a layout can pull in further layouts and parts.
+ * - Markdown pages take their layout from front matter: a "layout" or "part" key names the file, the other keys are data.
+ * - Using the same layout twice on one page emits its scripts, styles and stylesheet links once; "always-include" opts a tag out of
+ *   that and gives it one copy per instance.
+ * - Layout files never reach the output on their own, and editing one recompiles every page and layout that pulls it in.
+ * - In production an instance is rendered once per file and attribute set, then cloned for the identical ones.
+ */
 declare function htmlLayoutPlugin(options?: HtmlLayoutOptions): Plugin;
 //#endregion
 //#region src/plugins/html-markdown/html-markdown-plugin.d.ts
@@ -909,9 +1321,32 @@ interface HtmlMarkdownOptions {
    */
   sourceAttribute?: string;
 }
+/**
+ * Renders markdown inside HTML pages, from a file or from the element's own text (names configurable via HtmlMarkdownOptions).
+ *
+ * - An element carrying the "markdown" attribute has its text rendered and replaced by the resulting HTML, and loses the attribute.
+ * - A "<markdown src=...>" tag is replaced by the rendered contents of the file it points at.
+ *
+ * Notes:
+ *
+ * - Runs in development and production alike.
+ * - The rendered HTML goes through the normal pipeline (resolve, load, transform), so its own tags are processed like the rest of
+ *   the page and a referenced file's links are rebased onto the page that renders it.
+ * - Editing a referenced markdown file recompiles the pages that render it.
+ */
 declare function htmlMarkdownPlugin(options?: HtmlMarkdownOptions): Plugin;
 //#endregion
 //#region src/plugins/html-merge-styles/html-merge-styles-plugin.d.ts
+/**
+ * Merges consecutive "<style>" tags in the "<head>" into a single tag, cutting the number of style blocks a page ships.
+ *
+ * Notes:
+ *
+ * - Production only, and only inside "<head>"; styles anywhere else are left alone.
+ * - A run is only merged when the tags carry identical attributes, and a "<link rel=stylesheet>" between them breaks the run, so
+ *   the cascade order never changes.
+ * - The merged rules are appended to the first tag of the run and the others are removed.
+ */
 declare function htmlMergeStylesPlugin(): Plugin;
 //#endregion
 //#region src/plugins/html-pages/html-pages-plugin.d.ts
@@ -929,6 +1364,23 @@ interface HtmlPagesOptions {
    */
   outputDir?: string;
 }
+/**
+ * Turns the files under the pages directory into routes: every ".html" and ".md" file in "pagesDir" is emitted at its clean URL
+ * path, and the links pointing into the directory are rewritten to match.
+ *
+ * - "pages/home.html" becomes "home/index.html", so it is served at "/home/", while a file already named "index" keeps its place.
+ * - Markdown pages are rendered to HTML first, and the markdown itself is kept out of the output.
+ * - Square brackets mark a dynamic route: "pages/users/[id].html" is expanded into one page per entry returned by the
+ *   "getStaticPaths" export of its "<script params>" tag, with "{{ $params.x }}" and "{{ $props.x }}" filled in.
+ *
+ * Notes:
+ *
+ * - Rebasing goes both ways: a page's own links survive the move out of "pagesDir", and links from anywhere else pointing into it
+ *   are rewritten to the final URL.
+ * - "outputDir" puts the whole route tree under a subdirectory of the output.
+ * - The dev server resolves a request through the same computed paths, with or without the trailing "index.html", dynamic routes
+ *   included.
+ */
 declare function htmlPagesPlugin(options?: HtmlPagesOptions): Plugin;
 //#endregion
 //#region src/plugins/html-preload/html-preload-plugin.d.ts
@@ -942,16 +1394,34 @@ interface HtmlPreloadOptions {
   /**
    * Attribute name for including files.
    *
-   * @default "include"
+   * @default "preload-include"
    */
   includeAttribute?: string;
   /**
    * Attribute name for excluding files.
    *
-   * @default "exclude"
+   * @default "preload-exclude"
    */
   excludeAttribute?: string;
 }
+/**
+ * Adds "<link rel=preload>" tags to the "<head>" for the dependencies of the scripts and stylesheets marked with "preload"
+ * (attribute names configurable via HtmlPreloadOptions), so the browser starts fetching them before parsing gets that far.
+ *
+ * Attributes:
+ *
+ * - "preload": marks the tag. Its value narrows what to emit to a space-separated list of "script", "style", "fetch", "font",
+ *   "audio", "video" and "image"; an empty value means all of them.
+ * - "preload-include" and "preload-exclude": semicolon-separated glob patterns, matched against paths relative to the project root.
+ *
+ * Notes:
+ *
+ * - Production only; in development the three attributes are just stripped.
+ * - Handles "<script>", "<style>" and "<link rel=stylesheet>" tags. The attribute on any other tag emits nothing.
+ * - The dependency walk covers the whole graph behind the tag (imports, "@import", "url()") plus the file it points at, and files
+ *   whose extension has no known "as" type are skipped.
+ * - The links are appended at the end of "<head>", so they come after whatever the page already has there.
+ */
 declare function htmlPreloadPlugin(options?: HtmlPreloadOptions): Plugin;
 //#endregion
 //#region src/plugins/core-plugins/html-metadata/html-metadata-plugin.d.ts
@@ -963,6 +1433,19 @@ interface CoreHtmlPluginOptions {
    */
   minifyAttribute?: string;
 }
+/**
+ * The HTML half of the core pipeline: parses a page into a document, splits its "<script>" and "<style>" tags into metadata of
+ * their own, and prints the whole thing back out.
+ *
+ * Notes:
+ *
+ * - Each inline script or style is tied to its tag by an internal id attribute, which is stripped from the printed output.
+ * - Sources come from the page's links plus the sources of every extracted script and style, so an import inside an inline script
+ *   counts as a dependency of the page.
+ * - A "minify" attribute on a single tag minifies just that tag regardless of the build settings, and when the rest of the page is
+ *   formatted such a tag is preceded by a "prettier-ignore" comment so it stays that way.
+ * - Rebasing a page carries its inline scripts and styles along with it.
+ */
 declare function coreHtmlPlugin(options?: CoreHtmlPluginOptions): Plugin;
 //#endregion
 //#region src/plugins/core-plugins/markdown-metadata/markdown-metadata-plugin.d.ts
@@ -996,28 +1479,85 @@ interface CoreMarkdownPluginOptions {
    */
   allowDangerousHtml?: boolean;
 }
+/**
+ * The markdown half of the core pipeline: parses ".md" files with remark, exposes their YAML front matter, and renders them to
+ * HTML on demand through "ast.render()".
+ *
+ * The remark chain is front matter, GFM and smartypants, then "remarkPlugins"; rendering runs remark-rehype, heading slugs and
+ * external links (opened in a new tab, with "noopener noreferrer"), then "rehypePlugins".
+ *
+ * Notes:
+ *
+ * - Raw HTML inside the markdown is dropped unless "allowDangerousHtml" is on.
+ * - Front matter is only read from the very first node, and only when it is a YAML block.
+ * - Links and images are reported as sources, so they get resolved and rebased; anything inside raw HTML is not.
+ * - Printing this metadata gives markdown back, not HTML.
+ */
 declare function coreMarkdownPlugin(options?: CoreMarkdownPluginOptions): Plugin;
 //#endregion
 //#region src/plugins/core-plugins/script-metadata/script-metadata-plugin.d.ts
+/**
+ * The script half of the core pipeline: loads JavaScript and TypeScript files (".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts",
+ * ".cts", ".tsx") into a Babel AST, prints them back out, and reports their imports as sources.
+ *
+ * Notes:
+ *
+ * - Loading only parses. Stripping types and JSX is transformJsPlugin's job.
+ * - Printing goes through Babel; "format" hands the result to prettier and "minify" to SWC, which is told whether the file is a
+ *   module or a classic script.
+ */
 declare function coreScriptPlugin(): Plugin;
 //#endregion
 //#region src/plugins/core-plugins/style-metadata/style-metadata-plugin.d.ts
+/**
+ * The style half of the core pipeline: loads ".css" files into a PostCSS AST, prints them back out, and reports their "@import"
+ * and "url()" references as sources.
+ *
+ * Notes:
+ *
+ * - "format" hands the result to prettier; "minify" runs Lightning CSS against the project's browserslist, resolved once and reused
+ *   for the rest of the build.
+ */
 declare function coreStylePlugin(): Plugin;
 //#endregion
 //#region src/plugins/core-plugins/svg-metadata/svg-metadata-plugin.d.ts
+/**
+ * The SVG half of the core pipeline: parses ".svg" files as documents, splits their "<style>" tags into metadata of their own,
+ * and prints them back out.
+ *
+ * Notes:
+ *
+ * - Sources come from the document's own links plus the sources of the extracted styles.
+ * - "format" runs prettier as HTML, and "minify" goes through the HTML minifier.
+ */
 declare function coreSvgPlugin(): Plugin;
 //#endregion
 //#region src/plugins/core-plugins/web-manifest-metadata/web-manifest-metadata-plugin.d.ts
+/**
+ * The web app manifest half of the core pipeline: loads a "manifest.json" as JSON data and reports the assets it points at.
+ *
+ * Notes:
+ *
+ * - Detection is by file name, so a manifest under a different name is only picked up when the type is passed explicitly.
+ * - Icons, screenshots and shortcut icons are reported as sources, so their paths are resolved and rebased with everything else.
+ * - Printing gives compact JSON, or indented when formatting.
+ */
 declare function coreWebManifestPlugin(): Plugin;
 //#endregion
 //#region src/plugins/core-plugins/development-server/development-server-plugin.d.ts
+/** What the serve command hands over through `app.pluginData`, taking precedence over the plugin options for that run. */
+interface DevelopmentServerOverrides {
+  host?: boolean | string;
+}
+declare const DEVELOPMENT_SERVER_OVERRIDES = "development-server";
 interface DevelopmentServerOptions {
   /**
-   * The dev server host.
+   * Where the dev server listens. `true` listens on every address, so the site is reachable from other devices on the network; a
+   * string is a specific address to listen on. The `--host` flag of the serve command turns this on for one run.
    *
-   * @default 0.0.0.0
+   * @default false
    */
-  host?: string;
+  host?: boolean | string;
   /**
    * The dev server port.
    *
@@ -1030,7 +1570,30 @@ interface DevelopmentServerOptions {
    * @default /
    */
   entry?: string;
+  /**
+   * Files in the public directory are served from the root as a fallback.
+   *
+   * @default "public"
+   */
+  publicDirectory?: string;
 }
+/**
+ * The dev server: serves the build from memory over Fastify, compiles pages on demand, and pushes updates to the browser over a
+ * web socket.
+ *
+ * Notes:
+ *
+ * - Development only.
+ * - A request is answered from what is already compiled; otherwise the path is resolved to an entry point and compiled on the spot,
+ *   with a directory path getting "index.html" appended. Anything that is not an entry point falls through to the static handler,
+ *   which serves the project root and the public directory.
+ * - The reload script is injected into HTML entry points as they are served, so it never exists in the built output.
+ * - On a change, the affected pages are recompiled in dependency order and metadata nothing references any more is dropped. If only
+ *   CSS changed the stylesheets are swapped in place, otherwise the page reloads.
+ * - Compiled pages are trimmed to the number of connected clients, dropping the least recently served ones.
+ * - Closing the app drops the connected clients and stops the server, which frees the port for the next one; the browser reloads
+ *   itself as soon as it reconnects.
+ */
 declare function developmentServerPlugin(options?: DevelopmentServerOptions): Plugin;
 //#endregion
 //#region src/plugins/cli-plugins/build/build-cli-plugin.d.ts
@@ -1048,6 +1611,14 @@ interface BuildCliPluginOptions {
    */
   aliases?: string[];
 }
+/**
+ * Adds the "build" command (aliased "b"): runs the pipeline once in production mode and reports how long it took.
+ *
+ * Notes:
+ *
+ * - The command owns the run. It forces production mode onto the config and creates its own App.
+ * - "--measure" turns on per-plugin hook timing and prints the report when the build finishes.
+ */
 declare function buildCliPlugin(options?: BuildCliPluginOptions): Plugin;
 //#endregion
 //#region src/plugins/cli-plugins/convert-fonts/convert-fonts-cli-plugin.d.ts
@@ -1083,6 +1654,15 @@ interface ConvertFontsCliPluginOptions {
    */
   outDir?: string;
 }
+/**
+ * Adds the "convert-fonts" command (aliased "woff2"): converts the TTF files matched by "--fonts" to WOFF2.
+ *
+ * Notes:
+ *
+ * - The options given here become the defaults of the matching flags; a flag left without one has to be passed on the command line.
+ * - Every font lands directly in "--out-dir" under its own name, so the source directory structure is flattened and fonts that
+ *   share a name overwrite each other.
+ */
 declare function convertFontsCliPlugin(options?: ConvertFontsCliPluginOptions): Plugin;
 //#endregion
 //#region src/plugins/cli-plugins/generate-font-face/generate-font-face-cli-plugin.d.ts
@@ -1120,10 +1700,20 @@ interface GenerateFontFacesCliPluginOptions {
   /**
    * The default value of the `fontDisplay` option.
    *
-   * @default "auto"
+   * @default "swap"
    */
   fontDisplay?: "auto" | "block" | "swap" | "fallback" | "optional";
 }
+/**
+ * Adds the "fontface" command (aliased "font"): writes one stylesheet of "@font-face" rules for the fonts matched by "--fonts".
+ *
+ * Notes:
+ *
+ * - Family, weight and style are read from the font's own tables, not from its file name, and the format comes from the extension.
+ * - The "src" path of each rule is written relative to "--css-out", and the file is overwritten as a whole on every run.
+ * - The options given here become the defaults of the matching flags; "--font-display" falls back to "swap".
+ * - Matching no font at all is reported and nothing is written.
+ */
 declare function generateFontFacesCliPlugin(options?: GenerateFontFacesCliPluginOptions): Plugin;
 //#endregion
 //#region src/plugins/cli-plugins/material-you/material-you/types.d.ts
@@ -1164,6 +1754,17 @@ interface MaterialYouCliPluginOptions {
    */
   raw?: boolean;
 }
+/**
+ * Adds the "palette" command (aliased "material-you"): generates a Material You palette from a seed color and prints it.
+ *
+ * Notes:
+ *
+ * - "--color" takes a full "#RRGGBB" hex; anything else is rejected.
+ * - "--format css" prints formatted custom properties ("--clr-*", with the seed and style recorded), "--format json" prints the raw
+ *   tone arrays. The pure black and white ends are left out of the CSS.
+ * - The output is syntax highlighted unless "--raw" is passed, which is what you want when redirecting into a file.
+ * - Nothing is written to disk; the palette goes to stdout.
+ */
 declare function materialYouCliPlugin(options?: MaterialYouCliPluginOptions): Plugin;
 //#endregion
 //#region src/plugins/cli-plugins/serve/serve-cli-plugin.d.ts
@@ -1181,7 +1782,19 @@ interface ServeCliPluginOptions {
    */
   aliases?: string[];
 }
+/**
+ * Adds the "serve" command (aliased "dev"): runs the pipeline in development mode, which is what starts the dev server.
+ *
+ * Notes:
+ *
+ * - The command owns the run. It forces development mode onto the config and creates its own App.
+ * - Serving itself belongs to developmentServerPlugin; this only starts the app in the right mode.
+ * - The config file is watched. When it changes it is loaded again, the running app is closed and a new one starts from the new
+ *   config. A config that fails to load leaves the running app alone; a new app that fails to start is closed, so nothing is
+ *   served until the next save. Plugins have to be created inside the config file: only that file is evaluated again, so plugin
+ *   objects imported from elsewhere would be the same ones the closed app used, and those are refused.
+ */
 declare function serveCliPlugin(options?: ServeCliPluginOptions): Plugin;
 //#endregion
-export { AnalyzeOutputOptions, BuildCliPluginOptions, BundlePackagesOptions, ConvertFontsCliPluginOptions, ConvertImageOptions, CopyAssetsOptions, CoreHtmlPluginOptions, CoreMarkdownPluginOptions, type CssLinear, CustomEasePluginOptions, DevelopmentServerOptions, GenerateFontFacesCliPluginOptions, HtmlBuildTimeScriptOptions, HtmlBundleScriptOptions, HtmlBundleStyleOptions, HtmlFragmentOptions, HtmlIifeScriptOptions, HtmlInlineScriptOptions, HtmlInlineStyleOptions, HtmlInlineSvgOptions, HtmlInlineSvgPlugin, HtmlInlineTextOptions, HtmlInsertOptions, HtmlLayoutOptions, HtmlMarkdownOptions, HtmlPagesOptions, HtmlPreloadOptions, I18nPluginOptions, ImageFormat, ImagePreset, type ImportAsStringOptions, LoadSourcesPluginOptions, MaterialYouCliPluginOptions, RobotsTextOptions, ServeCliPluginOptions, ServiceWorkerOptions, SitemapOptions, TransformCssOptions, TransformJsPluginOptions, WebManifestOptions, WriteFilesOptions, analyzeOutputPlugin, buildCliPlugin, bundlePackagesPlugin, convertFontsCliPlugin, convertImagePlugin, copyAssetsPlugin, coreHtmlPlugin, coreMarkdownPlugin, coreScriptPlugin, coreStylePlugin, coreSvgPlugin, coreWebManifestPlugin, customEasePlugin, developmentServerPlugin, generateFontFacesCliPlugin, htmlBuildTimeScript, htmlBundleScriptPlugin, htmlBundleStylePlugin, htmlFragmentPlugin, htmlIifeScriptPlugin, htmlInlineScriptPlugin, htmlInlineStylePlugin, htmlInlineTextPlugin, htmlInsertPlugin, htmlLayoutPlugin, htmlMarkdownPlugin, htmlMergeStylesPlugin, htmlPagesPlugin, htmlPreloadPlugin, svgoPlugin as htmlSvgoPlugin, svgoPlugin, i18nPlugin, importAsStringPlugin, type import_as_string, loadSourcesPlugin, materialYouCliPlugin, robotsTextPlugin, serveCliPlugin, serviceWorkerPlugin, sitemapPlugin, svgoOptions, transformCssPlugin, transformJsPlugin, webManifestPlugin, writeFilesPlugin };
+export { type AnalyzeOutputOptions, type BuildCliPluginOptions, type BundlePackagesOptions, type ConvertFontsCliPluginOptions, type ConvertImageOptions, type CopyAssetsOptions, type CoreHtmlPluginOptions, type CoreMarkdownPluginOptions, type CssLinear, type CustomEasePluginOptions, type DEVELOPMENT_SERVER_OVERRIDES, type DevelopmentServerOptions, type DevelopmentServerOverrides, type GenerateFontFacesCliPluginOptions, type HtmlBuildTimeScriptOptions, type HtmlBundleScriptOptions, type HtmlBundleStyleOptions, type HtmlEnvOnlyOptions, type HtmlFragmentOptions, type HtmlIifeScriptOptions, type HtmlInlineScriptOptions, type HtmlInlineStyleOptions, type HtmlInlineSvgOptions, HtmlInlineSvgPlugin, type HtmlInlineTextOptions, type HtmlInsertOptions, type HtmlLayoutOptions, type HtmlMarkdownOptions, type HtmlPagesOptions, type HtmlPreloadOptions, type I18nPluginOptions, type ImageFormat, type ImagePreset, type ImportAsStringOptions, type LoadSourcesPluginOptions, type MaterialYouCliPluginOptions, type RobotsTextOptions, type ServeCliPluginOptions, type ServiceWorkerOptions, type SitemapOptions, type TransformCssOptions, type TransformJsPluginOptions, type WebManifestOptions, type WriteFilesOptions, analyzeOutputPlugin, buildCliPlugin, bundlePackagesPlugin, convertFontsCliPlugin, convertImagePlugin, copyAssetsPlugin, coreHtmlPlugin, coreMarkdownPlugin, coreScriptPlugin, coreStylePlugin, coreSvgPlugin, coreWebManifestPlugin, customEasePlugin, developmentServerPlugin, generateFontFacesCliPlugin, htmlBuildTimeScript, htmlBundleScriptPlugin, htmlBundleStylePlugin, htmlEnvOnlyPlugin, htmlFragmentPlugin, htmlIifeScriptPlugin, htmlInlineScriptPlugin, htmlInlineStylePlugin, htmlInlineTextPlugin, htmlInsertPlugin, htmlLayoutPlugin, htmlMarkdownPlugin, htmlMergeStylesPlugin, htmlPagesPlugin, htmlPreloadPlugin, svgoPlugin as htmlSvgoPlugin, type svgoPlugin, i18nPlugin, importAsStringPlugin, type import_as_string, loadSourcesPlugin, materialYouCliPlugin, robotsTextPlugin, serveCliPlugin, serviceWorkerPlugin, sitemapPlugin, type svgoOptions, transformCssPlugin, transformJsPlugin, webManifestPlugin, writeFilesPlugin };
 //# sourceMappingURL=index.d.mts.map