js-build-tools 6.2.0 → 6.3.0

package/README.md

@@ -546,7 +546,7 @@ documentation straight from your source, with either engine:
   are not needed. `typedoc` is an optional peer dependency (like `typescript`), install it in your project with
   `npm install --save-dev typedoc` (this needs a `typescript` version it supports).
 * **jsdoc** (for a plain JavaScript project, where TypeDoc has no real types to read) - scans your source
-  recursively with jsdoc itself, rendered with a modern theme (`clean-jsdoc-theme` by default, used instead of
+  (`.js`, `.mjs` and `.cjs` files, leaving out tests and minified `.min.js` copies) recursively with jsdoc itself, rendered with a modern theme (`clean-jsdoc-theme` by default, used instead of
   jsdoc's own classic default template) instead of the manual `.jsdoc.conf.js` setup described further below.
   `jsdoc` and whichever theme you configure are optional peer dependencies, install them with
   `npm install --save-dev jsdoc clean-jsdoc-theme` (or your own chosen theme package).
@@ -558,7 +558,8 @@ Add the following to the exports in your `build-tools.config.json`:
   "docs": {
     // Generate the documentation from the source
     "enabled": true,
-    // The directory holding the source, each folder in it becomes a module (TypeDoc) or is scanned recursively (jsdoc)
+    // The directory holding the source, each folder in it becomes a module (TypeDoc) or is scanned recursively (jsdoc).
+    // jsdoc also takes a list of directories and files, for example ["functions", "gulpfile.base.mjs"]
     "from": "src",
     // The markdown file used as the front page of the documentation (a short overview of your project)
     "index": "MAIN.md",
@@ -569,6 +570,8 @@ Add the following to the exports in your `build-tools.config.json`:
     // Only meaningful when method is (or resolves to) 'jsdoc' - the theme package to render with. TypeDoc
     // always keeps its own default regardless of this setting.
     "theme": "clean-jsdoc-theme",
+    // The name of the documentation (TypeDoc's title, the theme's title for jsdoc), defaults to the package name
+    "title": "",
     // Where the HTML is generated (the directory is cleared first)
     "to": "docs"
   }
@@ -579,6 +582,35 @@ While `docs.enabled` is on, `gulp build` generates the documentation instead of
 hand-written (a short overview which links to the documentation). If you also export `docs` from your gulpfile you can
 run it on its own with `gulp docs`, and can then add the script `"docs": "gulp docs"`.
 
+### Browser automation (optional)
+
+Unlike the rest of this file, this isn't a `build-tools.config.json`-driven feature with its own task - it's a pair
+of plain functions (`partials.loadPlaywright`/`partials.launchBrowser` and `partials.serveStatic`) for whatever your
+own script needs a real browser for: verifying a page that only works correctly in a real browser (for example one
+using `<script type="module">`, which no DOM-simulation library executes at all), or taking a real screenshot.
+
+`playwright` is an optional peer dependency, install it in your project with `npm install --save-dev playwright`,
+then fetch a real browser binary once per machine (not per project) with `npx playwright install chromium` - if
+that fails with "Playwright does not support chromium on <your distro>", your OS is too old for the current
+release; either upgrade it or pin an older `playwright` version known to still support it (confirmed: `1.48.0`
+still installs and runs real headless Chromium on Ubuntu 20.04, which the current release has dropped).
+
+```js
+const { launchBrowser, serveStatic } = require('js-build-tools').partials
+
+const { server, url } = await serveStatic('browser') // serves ./browser/ over a real local HTTP server
+const browser = await launchBrowser()
+const page = await browser.newPage()
+await page.goto(`${url}/index.html`)
+await page.screenshot({ path: 'homepage.png' }) // a real screenshot, to actually look at
+await browser.close()
+server.close()
+```
+
+`serveStatic` exists because a page loaded directly from a `file://` path resolves any root-relative asset path
+(`/browser/...`) against the filesystem root instead of the page's own directory - serving it over real HTTP avoids
+that entirely, and is also the right fix for the exact same problem in a jsdom-based test.
+
 ### Configure lint rule overrides (optional)
 
 `sourceLint` lints your real source directly (not the compiled dist/browser output) with
@@ -613,7 +645,6 @@ In your `package.json` file, add the following scripts:
     "build": "gulp build",
     "dev": "gulp",
     "docs": "gulp docs",
-    "htmldocs": "jsdoc -R MAIN.md -c ./.jsdoc.conf.js -d docs",
     "publish:bundle": "gulp copyFiles",
     "readme": "gulp readme",
     "sass": "gulp sass",
@@ -629,8 +660,6 @@ In your `package.json` file, add the following scripts:
 
 Run any of the above commands with `gulp` or `npm run`.
 
-# Available functions documentation
-
 ## Modules
 
 <dl>
@@ -649,6 +678,146 @@ Export these functions to your own project to customize your build pipeline.
 
 **Version**: 3.0.0  
 **Author**: Joshua Heagle <joshuaheagle@gmail.com>  
+
+* [js-build-tools](#module_js-build-tools)
+    * [.typeScript](#module_js-build-tools.typeScript) ⇒ <code>function</code>
+    * [.typeDocs](#module_js-build-tools.typeDocs) ⇒ <code>function</code>
+    * [.jsdocDocs](#module_js-build-tools.jsdocDocs) ⇒ <code>function</code>
+    * [.compileReadme](#module_js-build-tools.compileReadme) ⇒ <code>stream.Stream</code>
+    * [.watchTest()](#module_js-build-tools.watchTest) ⇒ <code>\*</code>
+    * [.watchFull()](#module_js-build-tools.watchFull) ⇒ <code>FSWatcher</code>
+    * [.testQuick()](#module_js-build-tools.testQuick) ⇒ <code>Promise.&lt;\*&gt;</code>
+    * [.testFull()](#module_js-build-tools.testFull) ⇒ <code>Promise.&lt;\*&gt;</code>
+    * [.sourceLint()](#module_js-build-tools.sourceLint) ⇒ <code>\*</code>
+    * [.images()](#module_js-build-tools.images) ⇒ <code>stream.Stream</code>
+    * [.docs([done])](#module_js-build-tools.docs) ⇒ <code>\*</code>
+    * [.distMinify()](#module_js-build-tools.distMinify) ⇒ <code>\*</code>
+    * [.dist()](#module_js-build-tools.dist) ⇒ <code>\*</code>
+    * [.defaultCmd([done])](#module_js-build-tools.defaultCmd) ⇒ <code>stream.Stream</code>
+    * [.copyFonts()](#module_js-build-tools.copyFonts) ⇒ <code>stream.Stream</code>
+    * [.copyFiles()](#module_js-build-tools.copyFiles) ⇒ <code>Promise.&lt;void&gt;</code>
+    * [.bundleMinify()](#module_js-build-tools.bundleMinify) ⇒ <code>\*</code>
+    * [.bundle()](#module_js-build-tools.bundle) ⇒ <code>stream.Stream</code>
+    * [.build()](#module_js-build-tools.build) ⇒ <code>stream.Stream</code>
+
+<a name="module_js-build-tools.typeScript"></a>
+
+### js-build-tools.typeScript ⇒ <code>function</code>
+Simplified typescript task using tsFor.
+
+**Kind**: static constant of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.typeDocs"></a>
+
+### js-build-tools.typeDocs ⇒ <code>function</code>
+Generate the HTML documentation of a TypeScript project from its source, with the modules mirroring the source
+
+**Kind**: static constant of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.jsdocDocs"></a>
+
+### js-build-tools.jsdocDocs ⇒ <code>function</code>
+Generate the HTML documentation of a plain-JavaScript project from its source, with a modern jsdoc theme
+
+**Kind**: static constant of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.compileReadme"></a>
+
+### js-build-tools.compileReadme ⇒ <code>stream.Stream</code>
+Generate the README.md file based off of the template, then append the generated documentation.
+
+**Kind**: static constant of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.watchTest"></a>
+
+### js-build-tools.watchTest() ⇒ <code>\*</code>
+Watch for changes and run the tests.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.watchFull"></a>
+
+### js-build-tools.watchFull() ⇒ <code>FSWatcher</code>
+Watch for changes and run the distribution for the changed files, then bundle and test the changed files.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.testQuick"></a>
+
+### js-build-tools.testQuick() ⇒ <code>Promise.&lt;\*&gt;</code>
+Run the Jest tests for files which have been modified (based on git status).
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.testFull"></a>
+
+### js-build-tools.testFull() ⇒ <code>Promise.&lt;\*&gt;</code>
+Run all tests with jest.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.sourceLint"></a>
+
+### js-build-tools.sourceLint() ⇒ <code>\*</code>
+Applies neostandard linting (js-build-tools' chosen style) to the real, hand-written source - not the compiled
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.images"></a>
+
+### js-build-tools.images() ⇒ <code>stream.Stream</code>
+Move and optimize the images into the browser folder using configured settings.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.docs"></a>
+
+### js-build-tools.docs([done]) ⇒ <code>\*</code>
+Generate the HTML documentation with whichever engine docs.method (or its typescript.enabled-based default)
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+
+| Param | Type | Default |
+| --- | --- | --- |
+| [done] | <code>function</code> | <code></code> | 
+
+<a name="module_js-build-tools.distMinify"></a>
+
+### js-build-tools.distMinify() ⇒ <code>\*</code>
+Creates minified versions of the dist files.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.dist"></a>
+
+### js-build-tools.dist() ⇒ <code>\*</code>
+Simplified distribution tasks which will use arguments from distFor.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.defaultCmd"></a>
+
+### js-build-tools.defaultCmd([done]) ⇒ <code>stream.Stream</code>
+Recommended as the default task, runs the simple dist and bundle tasks.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+
+| Param | Type | Default |
+| --- | --- | --- |
+| [done] | <code>function</code> | <code></code> | 
+
+<a name="module_js-build-tools.copyFonts"></a>
+
+### js-build-tools.copyFonts() ⇒ <code>stream.Stream</code>
+Move the font files into the browser directory.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.copyFiles"></a>
+
+### js-build-tools.copyFiles() ⇒ <code>Promise.&lt;void&gt;</code>
+Copy files from one place to another - any number of { from, to, base? } entries, configured via copyFiles.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.bundleMinify"></a>
+
+### js-build-tools.bundleMinify() ⇒ <code>\*</code>
+Creates the minified file for every bundle (the primary bundle, plus any additional ones from
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.bundle"></a>
+
+### js-build-tools.bundle() ⇒ <code>stream.Stream</code>
+Starting at each bundle's own entry point (dist.main for the primary bundle, or its own
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
 <a name="module_js-build-tools.build"></a>
 
 ### js-build-tools.build() ⇒ <code>stream.Stream</code>
@@ -804,7 +973,8 @@ Configurations for building the browser files.
 <a name="module_gulpConfig..AdditionalBundleConfig"></a>
 
 ### gulpConfig~AdditionalBundleConfig : <code>Object.&lt;string, Setting&gt;</code>
-One additional bundle - everything but `name` falls back to the primary bundle's own value when omitted, so an
+One additional bundle - everything but `name` falls back to the primary bundle's own value when omitted, so an
+additional bundle only has to specify what's actually different about it.
 
 **Kind**: inner typedef of [<code>gulpConfig</code>](#module_gulpConfig)  
 **Properties**
@@ -861,7 +1031,7 @@ Configurations to minify and copy the images.
 <a name="module_gulpConfig..LintConfig"></a>
 
 ### gulpConfig~LintConfig : <code>Object.&lt;string, Setting&gt;</code>
-Configurations for linting (see [module:partials.neostandardLint](module:partials.neostandardLint)).
+Configurations for linting (see [neostandardLint](#module_partials.neostandardLint)).
 
 **Kind**: inner typedef of [<code>gulpConfig</code>](#module_gulpConfig)  
 **Properties**
@@ -890,7 +1060,8 @@ Configurations to compile and generate the Readme file.
 <a name="module_gulpConfig..DocsConfig"></a>
 
 ### gulpConfig~DocsConfig : <code>Object.&lt;string, Setting&gt;</code>
-Configurations for generating the HTML documentation of a project's own source, with either TypeDoc (real
+Configurations for generating the HTML documentation of a project's own source, with either TypeDoc (real
+TypeScript types) or jsdoc (a modern theme over jsdoc's own classic default) - see docs.method.
 
 **Kind**: inner typedef of [<code>gulpConfig</code>](#module_gulpConfig)  
 **Properties**
@@ -898,7 +1069,7 @@ Configurations for generating the HTML documentation of a project's own source,
 | Name | Type | Description |
 | --- | --- | --- |
 | enabled | <code>BooleanSetting</code> | Toggle generating the documentation from the source. When it is on the build does this instead of generating the readme from the jsdoc comments of the compiled files. |
-| from | <code>StringSetting</code> | The directory holding the source, each folder in it becomes a module (TypeDoc) or is scanned recursively (jsdoc). |
+| from | <code>ArrayableSetting</code> | The directory holding the source, each folder in it becomes a module (TypeDoc) or is scanned recursively (jsdoc). jsdoc also takes a list of directories and files. |
 | index | <code>StringSetting</code> | The markdown file used as the front page of the documentation. |
 | logLevel | <code>StringSetting</code> | How much TypeDoc reports: Verbose, Info, Warn, Error or None. Not used by jsdoc. |
 | method | <code>FlagStringSetting</code> | 'typedoc' or 'jsdoc'. False (the default) infers it from typescript.enabled - 'typedoc' when on, 'jsdoc' when off - so an existing TypeScript project's config needs no change to keep working exactly as it already does; set this explicitly to override that inference either way. |

package/dist/build.js

@@ -17,6 +17,7 @@ var _gulp = require("gulp");
 var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
 var _copyFonts = require("./copyFonts.js");
 var _images = require("./images.js");
+var _resolveDocsMethod = require("./partials/resolveDocsMethod.js");
 var _sass = require("./sass.js");
 var _testFull = require("./testFull.js");
 var cache;
@@ -31,10 +32,7 @@ function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e;
 const build = (done = null) => {
   const buildActions = [(0, _partials.distSeries)(), _distMinify.distMinify];
   const generateDocs = gulpConfig.get('docs.enabled');
-  // docs.method picks the engine explicitly; left unset (false, the default), it's inferred from
-  // typescript.enabled - every existing TypeScript project's config, which never sets method, keeps producing
-  // TypeDoc output exactly as it always has.
-  const docsMethod = gulpConfig.get('docs.method') || (gulpConfig.get('typescript.enabled') ? 'typedoc' : 'jsdoc');
+  const docsMethod = (0, _resolveDocsMethod.resolveDocsMethod)();
   if (generateDocs) {
     // The documentation is generated from the source itself, the readme is written by hand
     buildActions.push(docsMethod === 'jsdoc' ? _jsdocDocs.jsdocDocs : _typeDocs.typeDocs);

package/dist/build.min.js

@@ -1 +1 @@
-"use strict";require("core-js/modules/esnext.weak-map.delete-all.js"),Object.defineProperty(exports,"__esModule",{value:!0}),exports.build=void 0;var cache,_bundle=require("./bundle.js"),_bundleMinify=require("./bundleMinify.js"),_partials=require("./partials.js"),_compileReadme=require("./compileReadme.js"),_typeDocs=require("./typeDocs.js"),_jsdocDocs=require("./jsdocDocs.js"),_distMinify=require("./distMinify.js"),_sourceLint=require("./sourceLint.js"),_gulp=require("gulp"),gulpConfig=_interopRequireWildcard(require("../gulp.config.js")),_copyFonts=require("./copyFonts.js"),_images=require("./images.js"),_sass=require("./sass.js"),_testFull=require("./testFull.js");function _interopRequireWildcard(e,s){if(!s&&e&&e.__esModule)return e;var i,t,r=Object.defineProperty,l={__proto__:null,default:e};if(Object(e)!==e)return l;if(cache||"function"!=typeof WeakMap||(cache=new WeakMap),cache){if(cache.has(e))return cache.get(e);cache.set(e,l)}for(t in e)"default"!==t&&{}.hasOwnProperty.call(e,t)&&((i=r&&Object.getOwnPropertyDescriptor(e,t))&&(i.get||i.set)?r(l,t,i):l[t]=e[t]);return l}const build=(e=null)=>{const s=[(0,_partials.distSeries)(),_distMinify.distMinify],i=gulpConfig.get("docs.enabled"),t=gulpConfig.get("docs.method")||(gulpConfig.get("typescript.enabled")?"typedoc":"jsdoc");i?s.push("jsdoc"===t?_jsdocDocs.jsdocDocs:_typeDocs.typeDocs):gulpConfig.get("typescript.enabled")&&s.push(_compileReadme.compileReadme),gulpConfig.get("browser.enabled")&&(s.push(_bundle.bundle),s.push(_bundleMinify.bundleMinify));const r=[(0,_gulp.series)(...s)];return i||gulpConfig.get("typescript.enabled")||r.push(_compileReadme.compileReadme),r.push(_testFull.testFull),gulpConfig.get("fonts.enabled")&&r.push(_copyFonts.copyFonts),gulpConfig.get("images.enabled")&&r.push(_images.images),gulpConfig.get("sass.enabled")&&r.push(_sass.sass),(0,_gulp.series)((0,_gulp.parallel)(_partials.clean,_sourceLint.sourceLint),(0,_gulp.parallel)(...r))(e)};exports.build=build;
+"use strict";require("core-js/modules/esnext.weak-map.delete-all.js"),Object.defineProperty(exports,"__esModule",{value:!0}),exports.build=void 0;var cache,_bundle=require("./bundle.js"),_bundleMinify=require("./bundleMinify.js"),_partials=require("./partials.js"),_compileReadme=require("./compileReadme.js"),_typeDocs=require("./typeDocs.js"),_jsdocDocs=require("./jsdocDocs.js"),_distMinify=require("./distMinify.js"),_sourceLint=require("./sourceLint.js"),_gulp=require("gulp"),gulpConfig=_interopRequireWildcard(require("../gulp.config.js")),_copyFonts=require("./copyFonts.js"),_images=require("./images.js"),_resolveDocsMethod=require("./partials/resolveDocsMethod.js"),_sass=require("./sass.js"),_testFull=require("./testFull.js");function _interopRequireWildcard(e,s){if(!s&&e&&e.__esModule)return e;var i,r,t=Object.defineProperty,l={__proto__:null,default:e};if(Object(e)!==e)return l;if(cache||"function"!=typeof WeakMap||(cache=new WeakMap),cache){if(cache.has(e))return cache.get(e);cache.set(e,l)}for(r in e)"default"!==r&&{}.hasOwnProperty.call(e,r)&&((i=t&&Object.getOwnPropertyDescriptor(e,r))&&(i.get||i.set)?t(l,r,i):l[r]=e[r]);return l}const build=(e=null)=>{const s=[(0,_partials.distSeries)(),_distMinify.distMinify],i=gulpConfig.get("docs.enabled"),r=(0,_resolveDocsMethod.resolveDocsMethod)();i?s.push("jsdoc"===r?_jsdocDocs.jsdocDocs:_typeDocs.typeDocs):gulpConfig.get("typescript.enabled")&&s.push(_compileReadme.compileReadme),gulpConfig.get("browser.enabled")&&(s.push(_bundle.bundle),s.push(_bundleMinify.bundleMinify));const t=[(0,_gulp.series)(...s)];return i||gulpConfig.get("typescript.enabled")||t.push(_compileReadme.compileReadme),t.push(_testFull.testFull),gulpConfig.get("fonts.enabled")&&t.push(_copyFonts.copyFonts),gulpConfig.get("images.enabled")&&t.push(_images.images),gulpConfig.get("sass.enabled")&&t.push(_sass.sass),(0,_gulp.series)((0,_gulp.parallel)(_partials.clean,_sourceLint.sourceLint),(0,_gulp.parallel)(...t))(e)};exports.build=build;

package/dist/bundle.js

@@ -25,7 +25,7 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
  *
  * A bundle's name does double duty: it names the output file (name.js) and, via browserify's
  * `standalone` option, is also the name its exports are exposed under - as a global when loaded
- * with a bare <script> tag, or as the module when required via CommonJS/AMD. Without this, a
+ * with a bare `<script>` tag, or as the module when required via CommonJS/AMD. Without this, a
  * bundle built from a real entry point (one that actually exports something) builds successfully
  * but exposes nothing a consumer can reach.
  *

package/dist/docs.js

@@ -0,0 +1,19 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.docs = void 0;
+var _jsdocDocs = require("./jsdocDocs.js");
+var _resolveDocsMethod = require("./partials/resolveDocsMethod.js");
+var _typeDocs = require("./typeDocs.js");
+/**
+ * Generate the HTML documentation with whichever engine docs.method (or its typescript.enabled-based default)
+ * resolves to - see {@link module:partials.resolveDocsMethod}. The standalone counterpart to build's own
+ * internal branching, for running `gulp docs` directly instead of as part of a full build.
+ * @memberOf module:js-build-tools
+ * @param {Function} [done]
+ * @returns {*}
+ */
+const docs = (done = null) => ((0, _resolveDocsMethod.resolveDocsMethod)() === 'jsdoc' ? _jsdocDocs.jsdocDocs : _typeDocs.typeDocs)(done);
+exports.docs = docs;

package/dist/docs.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.docs=void 0;var _jsdocDocs=require("./jsdocDocs.js"),_resolveDocsMethod=require("./partials/resolveDocsMethod.js"),_typeDocs=require("./typeDocs.js");const docs=(o=null)=>("jsdoc"===(0,_resolveDocsMethod.resolveDocsMethod)()?_jsdocDocs.jsdocDocs:_typeDocs.typeDocs)(o);exports.docs=docs;

package/dist/partials/jsdocDocsFor.js

@@ -21,12 +21,13 @@ var _jsdocBase = _interopRequireDefault(require("../../jsdoc.base.js"));
 var cache;
 function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// jsdoc.base.js is CommonJS (it's also required directly by consuming projects' own .jsdoc.conf.js, and by this
-// project's own legacy htmldocs script) - Node's ESM loader imports a CJS module's module.exports as the default
-// export directly, no createRequire/import.meta needed (import.meta.url tripped up this project's own Babel CJS
-// transform, which Jest relies on to run .mjs test files - confirmed by removing it and nothing else changing).
+// jsdoc.base.js is CommonJS (it's also required directly by consuming projects' own .jsdoc.conf.js) - Node's ESM
+// loader imports a CJS module's module.exports as the default export directly, no createRequire/import.meta needed
+// (import.meta.url tripped up this project's own Babel CJS transform, which Jest relies on to run .mjs test files -
+// confirmed by removing it and nothing else changing).
 
 const execFileAsync = (0, _nodeUtil.promisify)(_nodeChild_process.execFile);
+const escapeHtml = text => String(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 const jsdocInstallHint = 'Install it in your project with: npm install --save-dev jsdoc';
 const themeInstallHint = name => `Install it in your project with: npm install --save-dev ${name}`;
 
@@ -78,11 +79,9 @@ const resolveJsdocBin = (projectPath = process.cwd()) => _nodePath.default.join(
 }), 'jsdoc.js');
 
 /**
- * Resolve a jsdoc theme package's own template directory, for jsdoc's own opts.template config key. Not
- * necessarily the package's own root - clean-jsdoc-theme's own docs say to point opts.template at its `dist`
- * subdirectory specifically, confirmed by reading its real README rather than assuming every theme follows the
- * classic jsdoc template layout (a bare package root with its own tmpl/static folders) - clean-jsdoc-theme does
- * not (it is a modern, self-contained, server-rendered theme with no such folders at its package root at all).
+ * Resolve a jsdoc theme package's own template directory, for jsdoc's own opts.template config key: the folder
+ * holding its publish.js. That is the package root for a classic jsdoc template (clean-jsdoc-theme 4.x included),
+ * but `dist` for a bundled one (clean-jsdoc-theme 5.x).
  * @memberOf module:partials
  * @param {string} name
  * @param {string} [projectPath=process.cwd()]
@@ -95,7 +94,8 @@ const resolveJsdocTheme = (name, projectPath = process.cwd()) => {
     installHint: themeInstallHint(name),
     projectPath
   });
-  return name === 'clean-jsdoc-theme' ? _nodePath.default.join(packageDir, 'dist') : packageDir;
+  const distDir = _nodePath.default.join(packageDir, 'dist');
+  return _nodeFs.default.existsSync(_nodePath.default.join(distDir, 'publish.js')) ? distDir : packageDir;
 };
 
 /**
@@ -105,7 +105,8 @@ const resolveJsdocTheme = (name, projectPath = process.cwd()) => {
  * options generated here instead of hand-maintained per project. Configure this with 'docs.from', 'docs.to',
  * 'docs.index', 'docs.theme' and 'docs.title'.
  * @memberOf module:partials
- * @param {string} [srcPath=gulpConfig.get('docs.from')] - The directory (or glob) holding the JS source.
+ * @param {string|Array<string>} [srcPath=gulpConfig.get('docs.from')] - The directory (or directories and files) holding
+ * the JS source.
  * @param {string} [outPath=gulpConfig.get('docs.to')] - The directory the documentation is generated into (cleared first).
  * @param {function(string, Array<string>): Promise<Object>} [runJsdoc] - Runs the jsdoc CLI, tests can inject a stand-in.
  * @returns {Function} A gulp task, it accepts an optional callback and returns a promise.
@@ -120,12 +121,13 @@ const jsdocDocsFor = (srcPath = gulpConfig.get('docs.from'), outPath = gulpConfi
       const theme = gulpConfig.get('docs.theme') || 'clean-jsdoc-theme';
       const themeDir = resolveJsdocTheme(theme);
       const indexFile = gulpConfig.get('docs.index');
+      const title = gulpConfig.get('docs.title');
       await (0, _removeDirectory.removeDirectory)(outPath);
       const config = {
         ..._jsdocBase.default,
         source: {
           ..._jsdocBase.default.source,
-          include: [_nodePath.default.resolve(srcPath)]
+          include: [].concat(srcPath).map(includePath => _nodePath.default.resolve(includePath))
         },
         opts: {
           destination: _nodePath.default.resolve(outPath),
@@ -134,6 +136,13 @@ const jsdocDocsFor = (srcPath = gulpConfig.get('docs.from'), outPath = gulpConfi
           // quick-start example, which sets this explicitly, not assumed from jsdoc's own classic defaults.
           recurse: true,
           template: themeDir,
+          // clean-jsdoc-theme's own option for the name in its header. Given as a link: a plain-text title links to the
+          // site root ("/"), while every page is in one folder, so index.html is the home page wherever they are served
+          ...(title ? {
+            theme_opts: {
+              title: `<a href="index.html" class="sidebar-title sidebar-title-anchor">${escapeHtml(title)}</a>`
+            }
+          } : {}),
           ...(indexFile && _nodeFs.default.existsSync(indexFile) ? {
             readme: _nodePath.default.resolve(indexFile)
           } : {})
@@ -144,7 +153,16 @@ const jsdocDocsFor = (srcPath = gulpConfig.get('docs.from'), outPath = gulpConfi
         const configPath = _nodePath.default.join(workDir, 'jsdoc.conf.json');
         _nodeFs.default.writeFileSync(configPath, JSON.stringify(config));
         const bin = resolveJsdocBin();
-        await runJsdoc(bin, ['-c', configPath]);
+        // Pass on what jsdoc and the theme report (warnings such as a page which failed to render), which would
+        // otherwise be lost with the captured output
+        const {
+          stdout = '',
+          stderr = ''
+        } = (await runJsdoc(bin, ['-c', configPath])) || {};
+        const report = `${stdout}${stderr}`.trim();
+        if (report) {
+          console.warn(report);
+        }
       } finally {
         await (0, _removeDirectory.removeDirectory)(workDir);
       }

package/dist/partials/loadPlaywright.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.loadPlaywright = exports.launchBrowser = void 0;
+var _loadPeer = require("./loadPeer.js");
+const installHint = 'Install it in your project with: npm install --save-dev playwright';
+
+/**
+ * Find Playwright (headless-browser automation) of the project being built, an optional peer dependency only
+ * needed by whatever actually drives a real browser - projects which never do never need it installed.
+ * @memberOf module:partials
+ * @param {string} [projectPath=process.cwd()] The folder of the project (which has the package.json) being built.
+ * @returns {Object} The Playwright module.
+ * @throws {Error} With install instructions when playwright is not installed.
+ */
+const loadPlaywright = (projectPath = process.cwd()) => (0, _loadPeer.requirePeer)('playwright', {
+  task: 'browser automation',
+  installHint,
+  projectPath
+});
+
+/**
+ * Launch a real headless Chromium browser via Playwright. See {@link loadPlaywright}.
+ * @memberOf module:partials
+ * @param {Function} [load=loadPlaywright] Which Playwright to launch - swappable in tests.
+ * @param {string} [projectPath=process.cwd()] The folder of the project (which has the package.json) being built.
+ * @returns {Promise<Browser>} The running Playwright browser - close it yourself (browser.close()) once done with it.
+ * @throws {Error} With install instructions when playwright is not installed.
+ */
+exports.loadPlaywright = loadPlaywright;
+const launchBrowser = (load = loadPlaywright, projectPath = process.cwd()) => load(projectPath).chromium.launch();
+exports.launchBrowser = launchBrowser;

package/dist/partials/neostandardLint.js

@@ -21,6 +21,7 @@ const importNeostandard = () => (0, _loadPeer.importModule)('neostandard');
  * migrating from `standard` keeps its globals (jest, browser, ...) without touching package.json.
  * @param {string} cwd
  * @returns {Array<string>}
+ * @private
  */
 const readEnv = cwd => {
   try {
@@ -42,7 +43,8 @@ const readEnv = cwd => {
  * @param {boolean} options.ts
  * @param {boolean} options.fix
  * @param {Object<string, *>} [options.rules={}]
- * @returns {Promise<import('eslint').ESLint>}
+ * @returns {Promise<ESLint>} eslint's ESLint instance
+ * @private
  */
 const buildEslint = async ({
   cwd,
@@ -75,7 +77,7 @@ const buildEslint = async ({
 /**
  * Print a file's lint messages, if it has any.
  * @memberOf module:partials
- * @param {import('vinyl')} file
+ * @param {Vinyl} file
  * @param {{messages: Array<{line: number, column: number, message: string}>, errorCount: number, warningCount: number}} result
  * @returns {undefined}
  */
@@ -108,7 +110,7 @@ const printFileReport = (file, result) => {
  * @param {function(Object): Promise<{lintText: Function}>} [loadEslint] - Resolves an ESLint-shaped linter. Real
  * callers should never need to pass this - it exists so tests can supply a stand-in, since this project's
  * CommonJS-transform-based Jest setup cannot execute a real dynamic import() of neostandard (ESM-only).
- * @returns {import('stream').Transform}
+ * @returns {stream.Transform}
  */
 const neostandardLint = ({
   fix = true,

package/dist/partials/resolveDocsMethod.js

@@ -0,0 +1,19 @@
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveDocsMethod = void 0;
+var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+/**
+ * Pick which engine generates the HTML documentation: docs.method picks it explicitly; left unset (false, the
+ * default), it's inferred from typescript.enabled - every existing TypeScript project's config, which never
+ * sets method, keeps producing TypeDoc output exactly as it always has.
+ * @memberOf module:partials
+ * @returns {'typedoc'|'jsdoc'}
+ */
+const resolveDocsMethod = () => gulpConfig.get('docs.method') || (gulpConfig.get('typescript.enabled') ? 'typedoc' : 'jsdoc');
+exports.resolveDocsMethod = resolveDocsMethod;

package/dist/partials/serveStatic.js

@@ -0,0 +1,57 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.serveStatic = void 0;
+var _nodeFs = _interopRequireDefault(require("node:fs"));
+var _nodeHttp = _interopRequireDefault(require("node:http"));
+var _nodePath = _interopRequireDefault(require("node:path"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// A real, previously-undiscovered bug fixed here: without a Content-Type header, a browser enforces strict MIME
+// checking on <script type="module"> and refuses to load it at all - exactly the case this partial exists for.
+const contentTypes = {
+  '.css': 'text/css',
+  '.gif': 'image/gif',
+  '.html': 'text/html',
+  '.ico': 'image/x-icon',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript',
+  '.json': 'application/json',
+  '.mjs': 'text/javascript',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2'
+};
+
+/**
+ * Serve a directory's real files over plain HTTP, for anything that needs a page loaded from a real URL rather
+ * than a bare file:// path - most commonly, a page using root-relative asset paths (/browser/...), which a
+ * file:// load resolves against the filesystem root instead of the page's own directory.
+ * @memberOf module:partials
+ * @param {string} rootDir - The directory to serve.
+ * @param {number} [port=0] - The port to listen on; 0 picks any free port.
+ * @returns {Promise<{server: http.Server, url: string}>} The running server, and its base URL - close the
+ * server yourself (server.close()) once done with it.
+ */
+const serveStatic = (rootDir, port = 0) => new Promise((resolve, reject) => {
+  const server = _nodeHttp.default.createServer((req, res) => {
+    const filePath = _nodePath.default.join(rootDir, decodeURIComponent(req.url.split('?')[0]));
+    _nodeFs.default.readFile(filePath, (error, data) => {
+      if (error) {
+        res.statusCode = 404;
+        return res.end(`Not found: ${req.url}`);
+      }
+      res.setHeader('Content-Type', contentTypes[_nodePath.default.extname(filePath)] || 'application/octet-stream');
+      res.end(data);
+    });
+  });
+  server.once('error', reject);
+  server.listen(port, '127.0.0.1', () => resolve({
+    server,
+    url: `http://127.0.0.1:${server.address().port}`
+  }));
+});
+exports.serveStatic = serveStatic;

package/dist/partials/tsFor.js

@@ -18,7 +18,7 @@ const importGulpTsCompile = () => (0, _loadPeer.importModule)('gulp-ts-compile')
 /**
  * Wrap a stream in a promise that resolves once it finishes writing.
  * @memberOf module:partials
- * @param {import('node:stream').Stream} stream
+ * @param {stream.Stream} stream
  * @returns {Promise<void>}
  */
 const installHint = 'Install it in your project with: npm install --save-dev typescript';
@@ -49,7 +49,7 @@ const streamToPromise = stream => new Promise((resolve, reject) => {
  * gulp-typescript when a removed API call started throwing under TypeScript 7.
  * @memberOf module:partials
  * @param {string} configPath - Path to a tsconfig.json file.
- * @returns {import('typescript').CompilerOptions}
+ * @returns {ts.CompilerOptions} TypeScript's compiler options
  */
 const readCompilerOptions = (ts, configPath) => {
   const configFile = ts.readConfigFile(configPath, ts.sys.readFile);