@rindo/core 3.2.0 → 3.2.1

package/compiler/rindo.js

@@ -1,5 +1,5 @@
 /*!
- Rindo Compiler v3.2.0 | MIT Licensed | https://rindojs.web.app
+ Rindo Compiler v3.2.1 | MIT Licensed | https://rindojs.web.app
  */
 (function(exports) {
 'use strict';
@@ -72,6 +72,97 @@ const DEFAULT_STYLE_MODE = '$';
  * File names and value
  */
 const COLLECTION_MANIFEST_FILE_NAME = 'collection-manifest.json';
+/**
+ * Constant for the 'copy' output target
+ */
+const COPY = 'copy';
+/**
+ * Constant for the 'custom' output target
+ */
+const CUSTOM = 'custom';
+/**
+ * Constant for the 'dist' output target
+ */
+const DIST = 'dist';
+/**
+ * Constant for the 'dist-collection' output target
+ */
+const DIST_COLLECTION = 'dist-collection';
+/**
+ * Constant for the 'dist-custom-elements' output target
+ */
+const DIST_CUSTOM_ELEMENTS = 'dist-custom-elements';
+/**
+ * Constant for the 'dist-types' output target
+ */
+const DIST_TYPES = 'dist-types';
+/**
+ * Constant for the 'dist-hydrate-script' output target
+ */
+const DIST_HYDRATE_SCRIPT = 'dist-hydrate-script';
+/**
+ * Constant for the 'dist-lazy' output target
+ */
+const DIST_LAZY = 'dist-lazy';
+/**
+ * Constant for the 'dist-lazy-loader' output target
+ */
+const DIST_LAZY_LOADER = 'dist-lazy-loader';
+/**
+ * Constant for the 'dist-global-styles' output target
+ */
+const DIST_GLOBAL_STYLES = 'dist-global-styles';
+/**
+ * Constant for the 'docs-custom' output target
+ */
+const DOCS_CUSTOM = 'docs-custom';
+/**
+ * Constant for the 'docs-json' output target
+ */
+const DOCS_JSON = 'docs-json';
+/**
+ * Constant for the 'docs-readme' output target
+ */
+const DOCS_README = 'docs-readme';
+/**
+ * Constant for the 'docs-vscode' output target
+ */
+const DOCS_VSCODE = 'docs-vscode';
+/**
+ * Constant for the 'stats' output target
+ */
+const STATS = 'stats';
+/**
+ * Constant for the 'www' output target
+ */
+const WWW = 'www';
+/**
+ * Valid output targets to specify in a Rindo config.
+ *
+ * Note that there are some output targets (e.g. `DIST_TYPES`) which are
+ * programmatically set as output targets by the compiler when other output
+ * targets (in that case `DIST`) are set, but which are _not_ supported in a
+ * Rindo config. This is enforced in the output target validation code.
+ */
+const VALID_CONFIG_OUTPUT_TARGETS = [
+  // DIST
+  WWW,
+  DIST,
+  DIST_COLLECTION,
+  DIST_CUSTOM_ELEMENTS,
+  DIST_LAZY,
+  DIST_HYDRATE_SCRIPT,
+  // DOCS
+  DOCS_JSON,
+  DOCS_README,
+  DOCS_VSCODE,
+  DOCS_CUSTOM,
+  // MISC
+  COPY,
+  CUSTOM,
+  STATS,
+];
+const GENERATED_DTS = 'components.d.ts';
 
 /**
  * Transform metadata about a component from the compiler to a compact form for
@@ -1199,355 +1290,6 @@ const flattenDiagnosticMessageText = (tsDiagnostic, diag) => {
   return result.trim();
 };
 
-/**
- * Converts a rollup provided source map to one that Rindo can easily understand
- * @param rollupSourceMap the sourcemap to transform
- * @returns the transformed sourcemap
- */
-const rollupToRindoSourceMap = (rollupSourceMap) => {
-  if (!rollupSourceMap) {
-    return null;
-  }
-  return {
-    file: rollupSourceMap.file,
-    mappings: rollupSourceMap.mappings,
-    names: rollupSourceMap.names,
-    sources: rollupSourceMap.sources,
-    sourcesContent: rollupSourceMap.sourcesContent,
-    version: rollupSourceMap.version,
-  };
-};
-/**
- * A JavaScript formatted string used to link generated code back to the original. This string follows the guidelines
- * found in the [Linking generated code to source maps](https://sourcemaps.info/spec.html#h.lmz475t4mvbx) section of
- * the Sourcemaps V3 specification proposal.
- */
-const JS_SOURCE_MAPPING_URL_LINKER = '//# sourceMappingURL=';
-/**
- * Generates an RFC-3986 compliant string for the given input.
- * More information about RFC-3986 can be found [here](https://datatracker.ietf.org/doc/html/rfc3986)
- * This function's original source is derived from
- * [MDN's encodeURIComponent documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent#description)
- * @param filename the filename to encode
- * @returns the encoded URI
- */
-const encodeToRfc3986 = (filename) => {
-  const encodedUri = encodeURIComponent(filename);
-  // replace all '!', single quotes, '(', ')', and '*' with their hexadecimal values (UTF-16)
-  return encodedUri.replace(/[!'()*]/g, (matchedCharacter) => {
-    return '%' + matchedCharacter.charCodeAt(0).toString(16);
-  });
-};
-/**
- * Generates a string used to link generated code with the original source, to be placed at the end of the generated
- * code.
- * @param url the url of the source map
- * @returns a linker string, of the format {@link JS_SOURCE_MAPPING_URL_LINKER}=<url>
- */
-const getSourceMappingUrlLinker = (url) => {
-  return `${JS_SOURCE_MAPPING_URL_LINKER}${encodeToRfc3986(url)}`;
-};
-/**
- * Generates a string used to link generated code with the original source, to be placed at the end of the generated
- * code as an inline source map.
- * @param sourceMapContents the sourceMapContents of the source map
- * @returns a linker string, of the format {@link JS_SOURCE_MAPPING_URL_LINKER}<dataUriPrefixAndMime><sourceMapContents>
- */
-const getInlineSourceMappingUrlLinker = (sourceMapContents) => {
-  const mapBase64 = Buffer.from(sourceMapContents, 'utf8').toString('base64');
-  // do not RFC-3986 encode an already valid base64 string. the sourcemaps will not resolve correctly when there is an
-  // allowed base64 character is encoded (because it is a disallowed RFC-3986 character)
-  return `${JS_SOURCE_MAPPING_URL_LINKER}data:application/json;charset=utf-8;base64,${mapBase64}`;
-};
-/**
- * Generates a string used to link generated code with the original source, to be placed at the end of the generated
- * code. This function prepends a newline to the string.
- * @param url the url of the source map
- * @returns a linker string, of the format {@link JS_SOURCE_MAPPING_URL_LINKER}=<url>.map, prepended with a newline
- */
-const getSourceMappingUrlForEndOfFile = (url) => {
-  return `\n${getSourceMappingUrlLinker(url)}.map`;
-};
-
-/**
- * Determines whether a string should be considered a remote url or not.
- *
- * This helper only checks the provided string to evaluate is one of a few pre-defined schemes, and should not be
- * considered all-encompassing
- *
- * @param p the string to evaluate
- * @returns `true` if the provided string is a remote url, `false` otherwise
- */
-const isRemoteUrl = (p) => {
-  if (isString$1(p)) {
-    p = p.toLowerCase();
-    return p.startsWith('https://') || p.startsWith('http://');
-  }
-  return false;
-};
-
-/**
- * A set of JSDoc tags which should be excluded from JSDoc comments
- * included in output typedefs.
- */
-const SUPPRESSED_JSDOC_TAGS = ['virtualProp', 'slot', 'part', 'internal'];
-/**
- * Create a stylistically-appropriate JS variable name from a filename
- *
- * If the filename has any of the special characters "?", "#", "&" and "=" it
- * will take the string before the left-most instance of one of those
- * characters.
- *
- * @param fileName the filename which serves as starting material
- * @returns a JS variable name based on the filename
- */
-const createJsVarName = (fileName) => {
-  if (isString$1(fileName)) {
-    fileName = fileName.split('?')[0];
-    fileName = fileName.split('#')[0];
-    fileName = fileName.split('&')[0];
-    fileName = fileName.split('=')[0];
-    fileName = toDashCase(fileName);
-    fileName = fileName.replace(/[|;$%@"<>()+,.{}_\!\/\\]/g, '-');
-    fileName = dashToPascalCase$1(fileName);
-    if (fileName.length > 1) {
-      fileName = fileName[0].toLowerCase() + fileName.slice(1);
-    }
-    else {
-      fileName = fileName.toLowerCase();
-    }
-    if (fileName.length > 0 && !isNaN(fileName[0])) {
-      fileName = '_' + fileName;
-    }
-  }
-  return fileName;
-};
-/**
- * Determines if a given file path points to a type declaration file (ending in .d.ts) or not. This function is
- * case-insensitive in its heuristics.
- * @param filePath the path to check
- * @returns `true` if the given `filePath` points to a type declaration file, `false` otherwise
- */
-const isDtsFile$1 = (filePath) => {
-  const parts = filePath.toLowerCase().split('.');
-  if (parts.length > 2) {
-    return parts[parts.length - 2] === 'd' && parts[parts.length - 1] === 'ts';
-  }
-  return false;
-};
-/**
- * Generate the preamble to be placed atop the main file of the build
- * @param config the Rindo configuration file
- * @returns the generated preamble
- */
-const generatePreamble = (config) => {
-  const { preamble } = config;
-  if (!preamble) {
-    return '';
-  }
-  // generate the body of the JSDoc-style comment
-  const preambleComment = preamble.split('\n').map((l) => ` * ${l}`);
-  preambleComment.unshift(`/*!`);
-  preambleComment.push(` */`);
-  return preambleComment.join('\n');
-};
-const lineBreakRegex = /\r?\n|\r/g;
-function getTextDocs(docs) {
-  if (docs == null) {
-    return '';
-  }
-  return `${docs.text.replace(lineBreakRegex, ' ')}
-${docs.tags
-    .filter((tag) => tag.name !== 'internal')
-    .map((tag) => `@${tag.name} ${(tag.text || '').replace(lineBreakRegex, ' ')}`)
-    .join('\n')}`.trim();
-}
-/**
- * Adds a doc block to a string
- * @param str the string to add a doc block to
- * @param docs the compiled JS docs
- * @param indentation number of spaces to indent the block with
- * @returns the doc block
- */
-function addDocBlock(str, docs, indentation = 0) {
-  if (!docs) {
-    return str;
-  }
-  return [formatDocBlock(docs, indentation), str].filter(Boolean).join(`\n`);
-}
-/**
- * Formats the given compiled docs to a JavaScript doc block
- * @param docs the compiled JS docs
- * @param indentation number of spaces to indent the block with
- * @returns the formatted doc block
- */
-function formatDocBlock(docs, indentation = 0) {
-  const textDocs = getDocBlockLines(docs);
-  if (!textDocs.filter(Boolean).length) {
-    return '';
-  }
-  const spaces = new Array(indentation + 1).join(' ');
-  return [spaces + '/**', ...textDocs.map((line) => spaces + ` * ${line}`), spaces + ' */'].join(`\n`);
-}
-/**
- * Get all lines which are part of the doc block
- *
- * @param docs the compiled JS docs
- * @returns list of lines part of the doc block
- */
-function getDocBlockLines(docs) {
-  return [
-    ...docs.text.split(lineBreakRegex),
-    ...docs.tags
-      .filter((tag) => !SUPPRESSED_JSDOC_TAGS.includes(tag.name))
-      .map((tag) => `@${tag.name} ${tag.text || ''}`.split(lineBreakRegex)),
-  ]
-    .flat()
-    .filter(Boolean);
-}
-/**
- * Retrieve a project's dependencies from the current build context
- * @param buildCtx the current build context to query for a specific package
- * @returns a list of package names the project is dependent on
- */
-const getDependencies = (buildCtx) => {
-  if (buildCtx.packageJson != null && buildCtx.packageJson.dependencies != null) {
-    return Object.keys(buildCtx.packageJson.dependencies).filter((pkgName) => !SKIP_DEPS.includes(pkgName));
-  }
-  return [];
-};
-/**
- * Utility to determine whether a project has a dependency on a package
- * @param buildCtx the current build context to query for a specific package
- * @param depName the name of the dependency/package
- * @returns `true` if the project has a dependency a packaged with the provided name, `false` otherwise
- */
-const hasDependency = (buildCtx, depName) => {
-  return getDependencies(buildCtx).includes(depName);
-};
-// TODO: Remove code related to the dynamic import shim
-const getDynamicImportFunction$1 = (namespace) => `__sc_import_${namespace.replace(/\s|-/g, '_')}`;
-const readPackageJson = async (config, compilerCtx, buildCtx) => {
-  try {
-    const pkgJson = await compilerCtx.fs.readFile(config.packageJsonFilePath);
-    if (pkgJson) {
-      const parseResults = parsePackageJson(pkgJson, config.packageJsonFilePath);
-      if (parseResults.diagnostic) {
-        buildCtx.diagnostics.push(parseResults.diagnostic);
-      }
-      else {
-        buildCtx.packageJson = parseResults.data;
-      }
-    }
-  }
-  catch (e) {
-    if (!config.outputTargets.some((o) => o.type.includes('dist'))) {
-      const diagnostic = buildError(buildCtx.diagnostics);
-      diagnostic.header = `Missing "package.json"`;
-      diagnostic.messageText = `Valid "package.json" file is required for distribution: ${config.packageJsonFilePath}`;
-    }
-  }
-};
-/**
- * Parse a string read from a `package.json` file
- * @param pkgJsonStr the string read from a `package.json` file
- * @param pkgJsonFilePath the path to the already read `package.json` file
- * @returns the results of parsing the provided contents of the `package.json` file
- */
-const parsePackageJson = (pkgJsonStr, pkgJsonFilePath) => {
-  const parseResult = {
-    diagnostic: null,
-    data: null,
-    filePath: pkgJsonFilePath,
-  };
-  try {
-    parseResult.data = JSON.parse(pkgJsonStr);
-  }
-  catch (e) {
-    parseResult.diagnostic = buildError();
-    parseResult.diagnostic.absFilePath = isString$1(pkgJsonFilePath) ? pkgJsonFilePath : undefined;
-    parseResult.diagnostic.header = `Error Parsing JSON`;
-    if (e instanceof Error) {
-      parseResult.diagnostic.messageText = e.message;
-    }
-  }
-  return parseResult;
-};
-const SKIP_DEPS = ['@rindo/core'];
-/**
- * Check whether a string is a member of a ReadonlyArray<string>
- *
- * We need a little helper for this because unfortunately `includes` is typed
- * on `ReadonlyArray<T>` as `(el: T): boolean` so a `string` cannot be passed
- * to `includes` on a `ReadonlyArray` 😢 thus we have a little helper function
- * where we do the type coercion just once.
- *
- * see microsoft/TypeScript#31018 for some discussion of this
- *
- * @param readOnlyArray the array we're checking
- * @param maybeMember a value which is possibly a member of the array
- * @returns whether the array contains the member or not
- */
-const readOnlyArrayHasStringMember = (readOnlyArray, maybeMember) => readOnlyArray.includes(maybeMember);
-
-/**
- * Validates that a component tag meets required naming conventions to be used for a web component
- * @param tag the tag to validate
- * @returns an error message if the tag has an invalid name, undefined if the tag name passes all checks
- */
-const validateComponentTag = (tag) => {
-  // we want to check this first since we call some String.prototype methods below
-  if (typeof tag !== 'string') {
-    return `Tag "${tag}" must be a string type`;
-  }
-  if (tag !== tag.trim()) {
-    return `Tag can not contain white spaces`;
-  }
-  if (tag !== tag.toLowerCase()) {
-    return `Tag can not contain upper case characters`;
-  }
-  if (tag.length === 0) {
-    return `Received empty tag value`;
-  }
-  if (tag.indexOf(' ') > -1) {
-    return `"${tag}" tag cannot contain a space`;
-  }
-  if (tag.indexOf(',') > -1) {
-    return `"${tag}" tag cannot be used for multiple tags`;
-  }
-  const invalidChars = tag.replace(/\w|-/g, '');
-  if (invalidChars !== '') {
-    return `"${tag}" tag contains invalid characters: ${invalidChars}`;
-  }
-  if (tag.indexOf('-') === -1) {
-    return `"${tag}" tag must contain a dash (-) to work as a valid web component`;
-  }
-  if (tag.indexOf('--') > -1) {
-    return `"${tag}" tag cannot contain multiple dashes (--) next to each other`;
-  }
-  if (tag.indexOf('-') === 0) {
-    return `"${tag}" tag cannot start with a dash (-)`;
-  }
-  if (tag.lastIndexOf('-') === tag.length - 1) {
-    return `"${tag}" tag cannot end with a dash (-)`;
-  }
-  return undefined;
-};
-
-const EOL = '\n';
-const platform = () => OS_PLATFORM;
-const os$2 = {
-  EOL,
-  platform,
-};
-
-const os$3 = {
-  __proto__: null,
-  EOL: EOL,
-  platform: platform,
-  'default': os$2
-};
-
 // 'path' module extracted from Node.js v8.11.1 (only the posix part)
 
 function assertPath(path) {
@@ -2117,6 +1859,407 @@ const path$6 = {
   'default': path$5
 };
 
+const relativeImport = (pathFrom, pathTo, ext, addPrefix = true) => {
+  let relativePath = relative$1(dirname(pathFrom), dirname(pathTo));
+  if (addPrefix) {
+    if (relativePath === '') {
+      relativePath = '.';
+    }
+    else if (relativePath[0] !== '.') {
+      relativePath = './' + relativePath;
+    }
+  }
+  return normalizePath$2(`${relativePath}/${basename(pathTo, ext)}`);
+};
+const getComponentsDtsSrcFilePath = (config) => join(config.srcDir, GENERATED_DTS);
+const getComponentsDtsTypesFilePath = (outputTarget) => join(outputTarget.typesDir, GENERATED_DTS);
+const isOutputTargetDist = (o) => o.type === DIST;
+const isOutputTargetDistCollection = (o) => o.type === DIST_COLLECTION;
+const isOutputTargetDistCustomElements = (o) => o.type === DIST_CUSTOM_ELEMENTS;
+const isOutputTargetCopy = (o) => o.type === COPY;
+const isOutputTargetDistLazy = (o) => o.type === DIST_LAZY;
+const isOutputTargetDistLazyLoader = (o) => o.type === DIST_LAZY_LOADER;
+const isOutputTargetDistGlobalStyles = (o) => o.type === DIST_GLOBAL_STYLES;
+const isOutputTargetHydrate = (o) => o.type === DIST_HYDRATE_SCRIPT;
+const isOutputTargetCustom = (o) => o.type === CUSTOM;
+const isOutputTargetDocs = (o) => o.type === DOCS_README || o.type === DOCS_JSON || o.type === DOCS_CUSTOM || o.type === DOCS_VSCODE;
+const isOutputTargetDocsReadme = (o) => o.type === DOCS_README;
+const isOutputTargetDocsJson = (o) => o.type === DOCS_JSON;
+const isOutputTargetDocsCustom = (o) => o.type === DOCS_CUSTOM;
+const isOutputTargetDocsVscode = (o) => o.type === DOCS_VSCODE;
+const isOutputTargetWww = (o) => o.type === WWW;
+const isOutputTargetStats = (o) => o.type === STATS;
+const isOutputTargetDistTypes = (o) => o.type === DIST_TYPES;
+/**
+ * Retrieve the Rindo component compiler metadata from a collection of Rindo {@link Module}s
+ * @param moduleFiles the collection of `Module`s to retrieve the metadata from
+ * @returns the metadata, lexicographically sorted by the tag names of the components
+ */
+const getComponentsFromModules = (moduleFiles) => sortBy(flatOne(moduleFiles.map((m) => m.cmps)), (c) => c.tagName);
+/**
+ * Check whether a given output target is a valid one to be set in a Rindo config
+ *
+ * @param targetType the type which we want to check
+ * @returns whether or not the targetType is a valid, configurable output target.
+ */
+function isValidConfigOutputTarget(targetType) {
+  // unfortunately `includes` is typed on `ReadonlyArray<T>` as `(el: T):
+  // boolean` so a `string` cannot be passed to `includes` on a
+  // `ReadonlyArray` 😢 thus we `as any`
+  //
+  // see microsoft/TypeScript#31018 for some discussion of this
+  return VALID_CONFIG_OUTPUT_TARGETS.includes(targetType);
+}
+
+/**
+ * Converts a rollup provided source map to one that Rindo can easily understand
+ * @param rollupSourceMap the sourcemap to transform
+ * @returns the transformed sourcemap
+ */
+const rollupToRindoSourceMap = (rollupSourceMap) => {
+  if (!rollupSourceMap) {
+    return null;
+  }
+  return {
+    file: rollupSourceMap.file,
+    mappings: rollupSourceMap.mappings,
+    names: rollupSourceMap.names,
+    sources: rollupSourceMap.sources,
+    sourcesContent: rollupSourceMap.sourcesContent,
+    version: rollupSourceMap.version,
+  };
+};
+/**
+ * A JavaScript formatted string used to link generated code back to the original. This string follows the guidelines
+ * found in the [Linking generated code to source maps](https://sourcemaps.info/spec.html#h.lmz475t4mvbx) section of
+ * the Sourcemaps V3 specification proposal.
+ */
+const JS_SOURCE_MAPPING_URL_LINKER = '//# sourceMappingURL=';
+/**
+ * Generates an RFC-3986 compliant string for the given input.
+ * More information about RFC-3986 can be found [here](https://datatracker.ietf.org/doc/html/rfc3986)
+ * This function's original source is derived from
+ * [MDN's encodeURIComponent documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent#description)
+ * @param filename the filename to encode
+ * @returns the encoded URI
+ */
+const encodeToRfc3986 = (filename) => {
+  const encodedUri = encodeURIComponent(filename);
+  // replace all '!', single quotes, '(', ')', and '*' with their hexadecimal values (UTF-16)
+  return encodedUri.replace(/[!'()*]/g, (matchedCharacter) => {
+    return '%' + matchedCharacter.charCodeAt(0).toString(16);
+  });
+};
+/**
+ * Generates a string used to link generated code with the original source, to be placed at the end of the generated
+ * code.
+ * @param url the url of the source map
+ * @returns a linker string, of the format {@link JS_SOURCE_MAPPING_URL_LINKER}=<url>
+ */
+const getSourceMappingUrlLinker = (url) => {
+  return `${JS_SOURCE_MAPPING_URL_LINKER}${encodeToRfc3986(url)}`;
+};
+/**
+ * Generates a string used to link generated code with the original source, to be placed at the end of the generated
+ * code as an inline source map.
+ * @param sourceMapContents the sourceMapContents of the source map
+ * @returns a linker string, of the format {@link JS_SOURCE_MAPPING_URL_LINKER}<dataUriPrefixAndMime><sourceMapContents>
+ */
+const getInlineSourceMappingUrlLinker = (sourceMapContents) => {
+  const mapBase64 = Buffer.from(sourceMapContents, 'utf8').toString('base64');
+  // do not RFC-3986 encode an already valid base64 string. the sourcemaps will not resolve correctly when there is an
+  // allowed base64 character is encoded (because it is a disallowed RFC-3986 character)
+  return `${JS_SOURCE_MAPPING_URL_LINKER}data:application/json;charset=utf-8;base64,${mapBase64}`;
+};
+/**
+ * Generates a string used to link generated code with the original source, to be placed at the end of the generated
+ * code. This function prepends a newline to the string.
+ * @param url the url of the source map
+ * @returns a linker string, of the format {@link JS_SOURCE_MAPPING_URL_LINKER}=<url>.map, prepended with a newline
+ */
+const getSourceMappingUrlForEndOfFile = (url) => {
+  return `\n${getSourceMappingUrlLinker(url)}.map`;
+};
+
+/**
+ * Determines whether a string should be considered a remote url or not.
+ *
+ * This helper only checks the provided string to evaluate is one of a few pre-defined schemes, and should not be
+ * considered all-encompassing
+ *
+ * @param p the string to evaluate
+ * @returns `true` if the provided string is a remote url, `false` otherwise
+ */
+const isRemoteUrl = (p) => {
+  if (isString$1(p)) {
+    p = p.toLowerCase();
+    return p.startsWith('https://') || p.startsWith('http://');
+  }
+  return false;
+};
+
+/**
+ * A set of JSDoc tags which should be excluded from JSDoc comments
+ * included in output typedefs.
+ */
+const SUPPRESSED_JSDOC_TAGS = ['virtualProp', 'slot', 'part', 'internal'];
+/**
+ * Create a stylistically-appropriate JS variable name from a filename
+ *
+ * If the filename has any of the special characters "?", "#", "&" and "=" it
+ * will take the string before the left-most instance of one of those
+ * characters.
+ *
+ * @param fileName the filename which serves as starting material
+ * @returns a JS variable name based on the filename
+ */
+const createJsVarName = (fileName) => {
+  if (isString$1(fileName)) {
+    fileName = fileName.split('?')[0];
+    fileName = fileName.split('#')[0];
+    fileName = fileName.split('&')[0];
+    fileName = fileName.split('=')[0];
+    fileName = toDashCase(fileName);
+    fileName = fileName.replace(/[|;$%@"<>()+,.{}_\!\/\\]/g, '-');
+    fileName = dashToPascalCase$1(fileName);
+    if (fileName.length > 1) {
+      fileName = fileName[0].toLowerCase() + fileName.slice(1);
+    }
+    else {
+      fileName = fileName.toLowerCase();
+    }
+    if (fileName.length > 0 && !isNaN(fileName[0])) {
+      fileName = '_' + fileName;
+    }
+  }
+  return fileName;
+};
+/**
+ * Determines if a given file path points to a type declaration file (ending in .d.ts) or not. This function is
+ * case-insensitive in its heuristics.
+ * @param filePath the path to check
+ * @returns `true` if the given `filePath` points to a type declaration file, `false` otherwise
+ */
+const isDtsFile$1 = (filePath) => {
+  const parts = filePath.toLowerCase().split('.');
+  if (parts.length > 2) {
+    return parts[parts.length - 2] === 'd' && parts[parts.length - 1] === 'ts';
+  }
+  return false;
+};
+/**
+ * Generate the preamble to be placed atop the main file of the build
+ * @param config the Rindo configuration file
+ * @returns the generated preamble
+ */
+const generatePreamble = (config) => {
+  const { preamble } = config;
+  if (!preamble) {
+    return '';
+  }
+  // generate the body of the JSDoc-style comment
+  const preambleComment = preamble.split('\n').map((l) => ` * ${l}`);
+  preambleComment.unshift(`/*!`);
+  preambleComment.push(` */`);
+  return preambleComment.join('\n');
+};
+const lineBreakRegex = /\r?\n|\r/g;
+function getTextDocs(docs) {
+  if (docs == null) {
+    return '';
+  }
+  return `${docs.text.replace(lineBreakRegex, ' ')}
+${docs.tags
+    .filter((tag) => tag.name !== 'internal')
+    .map((tag) => `@${tag.name} ${(tag.text || '').replace(lineBreakRegex, ' ')}`)
+    .join('\n')}`.trim();
+}
+/**
+ * Adds a doc block to a string
+ * @param str the string to add a doc block to
+ * @param docs the compiled JS docs
+ * @param indentation number of spaces to indent the block with
+ * @returns the doc block
+ */
+function addDocBlock(str, docs, indentation = 0) {
+  if (!docs) {
+    return str;
+  }
+  return [formatDocBlock(docs, indentation), str].filter(Boolean).join(`\n`);
+}
+/**
+ * Formats the given compiled docs to a JavaScript doc block
+ * @param docs the compiled JS docs
+ * @param indentation number of spaces to indent the block with
+ * @returns the formatted doc block
+ */
+function formatDocBlock(docs, indentation = 0) {
+  const textDocs = getDocBlockLines(docs);
+  if (!textDocs.filter(Boolean).length) {
+    return '';
+  }
+  const spaces = new Array(indentation + 1).join(' ');
+  return [spaces + '/**', ...textDocs.map((line) => spaces + ` * ${line}`), spaces + ' */'].join(`\n`);
+}
+/**
+ * Get all lines which are part of the doc block
+ *
+ * @param docs the compiled JS docs
+ * @returns list of lines part of the doc block
+ */
+function getDocBlockLines(docs) {
+  return [
+    ...docs.text.split(lineBreakRegex),
+    ...docs.tags
+      .filter((tag) => !SUPPRESSED_JSDOC_TAGS.includes(tag.name))
+      .map((tag) => `@${tag.name} ${tag.text || ''}`.split(lineBreakRegex)),
+  ]
+    .flat()
+    .filter(Boolean);
+}
+/**
+ * Retrieve a project's dependencies from the current build context
+ * @param buildCtx the current build context to query for a specific package
+ * @returns a list of package names the project is dependent on
+ */
+const getDependencies = (buildCtx) => {
+  if (buildCtx.packageJson != null && buildCtx.packageJson.dependencies != null) {
+    return Object.keys(buildCtx.packageJson.dependencies).filter((pkgName) => !SKIP_DEPS.includes(pkgName));
+  }
+  return [];
+};
+/**
+ * Utility to determine whether a project has a dependency on a package
+ * @param buildCtx the current build context to query for a specific package
+ * @param depName the name of the dependency/package
+ * @returns `true` if the project has a dependency a packaged with the provided name, `false` otherwise
+ */
+const hasDependency = (buildCtx, depName) => {
+  return getDependencies(buildCtx).includes(depName);
+};
+// TODO: Remove code related to the dynamic import shim
+const getDynamicImportFunction$1 = (namespace) => `__sc_import_${namespace.replace(/\s|-/g, '_')}`;
+const readPackageJson = async (config, compilerCtx, buildCtx) => {
+  try {
+    const pkgJson = await compilerCtx.fs.readFile(config.packageJsonFilePath);
+    if (pkgJson) {
+      const parseResults = parsePackageJson(pkgJson, config.packageJsonFilePath);
+      if (parseResults.diagnostic) {
+        buildCtx.diagnostics.push(parseResults.diagnostic);
+      }
+      else {
+        buildCtx.packageJson = parseResults.data;
+      }
+    }
+  }
+  catch (e) {
+    if (!config.outputTargets.some((o) => o.type.includes('dist'))) {
+      const diagnostic = buildError(buildCtx.diagnostics);
+      diagnostic.header = `Missing "package.json"`;
+      diagnostic.messageText = `Valid "package.json" file is required for distribution: ${config.packageJsonFilePath}`;
+    }
+  }
+};
+/**
+ * Parse a string read from a `package.json` file
+ * @param pkgJsonStr the string read from a `package.json` file
+ * @param pkgJsonFilePath the path to the already read `package.json` file
+ * @returns the results of parsing the provided contents of the `package.json` file
+ */
+const parsePackageJson = (pkgJsonStr, pkgJsonFilePath) => {
+  const parseResult = {
+    diagnostic: null,
+    data: null,
+    filePath: pkgJsonFilePath,
+  };
+  try {
+    parseResult.data = JSON.parse(pkgJsonStr);
+  }
+  catch (e) {
+    parseResult.diagnostic = buildError();
+    parseResult.diagnostic.absFilePath = isString$1(pkgJsonFilePath) ? pkgJsonFilePath : undefined;
+    parseResult.diagnostic.header = `Error Parsing JSON`;
+    if (e instanceof Error) {
+      parseResult.diagnostic.messageText = e.message;
+    }
+  }
+  return parseResult;
+};
+const SKIP_DEPS = ['@rindo/core'];
+/**
+ * Check whether a string is a member of a ReadonlyArray<string>
+ *
+ * We need a little helper for this because unfortunately `includes` is typed
+ * on `ReadonlyArray<T>` as `(el: T): boolean` so a `string` cannot be passed
+ * to `includes` on a `ReadonlyArray` 😢 thus we have a little helper function
+ * where we do the type coercion just once.
+ *
+ * see microsoft/TypeScript#31018 for some discussion of this
+ *
+ * @param readOnlyArray the array we're checking
+ * @param maybeMember a value which is possibly a member of the array
+ * @returns whether the array contains the member or not
+ */
+const readOnlyArrayHasStringMember = (readOnlyArray, maybeMember) => readOnlyArray.includes(maybeMember);
+
+/**
+ * Validates that a component tag meets required naming conventions to be used for a web component
+ * @param tag the tag to validate
+ * @returns an error message if the tag has an invalid name, undefined if the tag name passes all checks
+ */
+const validateComponentTag = (tag) => {
+  // we want to check this first since we call some String.prototype methods below
+  if (typeof tag !== 'string') {
+    return `Tag "${tag}" must be a string type`;
+  }
+  if (tag !== tag.trim()) {
+    return `Tag can not contain white spaces`;
+  }
+  if (tag !== tag.toLowerCase()) {
+    return `Tag can not contain upper case characters`;
+  }
+  if (tag.length === 0) {
+    return `Received empty tag value`;
+  }
+  if (tag.indexOf(' ') > -1) {
+    return `"${tag}" tag cannot contain a space`;
+  }
+  if (tag.indexOf(',') > -1) {
+    return `"${tag}" tag cannot be used for multiple tags`;
+  }
+  const invalidChars = tag.replace(/\w|-/g, '');
+  if (invalidChars !== '') {
+    return `"${tag}" tag contains invalid characters: ${invalidChars}`;
+  }
+  if (tag.indexOf('-') === -1) {
+    return `"${tag}" tag must contain a dash (-) to work as a valid web component`;
+  }
+  if (tag.indexOf('--') > -1) {
+    return `"${tag}" tag cannot contain multiple dashes (--) next to each other`;
+  }
+  if (tag.indexOf('-') === 0) {
+    return `"${tag}" tag cannot start with a dash (-)`;
+  }
+  if (tag.lastIndexOf('-') === tag.length - 1) {
+    return `"${tag}" tag cannot end with a dash (-)`;
+  }
+  return undefined;
+};
+
+const EOL = '\n';
+const platform = () => OS_PLATFORM;
+const os$2 = {
+  EOL,
+  platform,
+};
+
+const os$3 = {
+  __proto__: null,
+  EOL: EOL,
+  platform: platform,
+  'default': os$2
+};
+
 var commonjsGlobal$1 = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
 
 function createCommonjsModule$1(fn, basedir, module) {
@@ -2155,7 +2298,7 @@ const process$3 = /*#__PURE__*/Object.assign(/*#__PURE__*/Object.create(null), p
   'default': process_1
 });
 
-const buildId = '1680872033';
+const buildId = '1682086722';
 const minfyJsId = 'terser5.16.1_7';
 const optimizeCssId = 'autoprefixer10.4.13_postcss8.4.21_7';
 const parse5Version = '7.1.2';
@@ -2163,8 +2306,8 @@ const rollupVersion = '2.42.3';
 const sizzleVersion = '2.42.3';
 const terserVersion = '5.16.1';
 const typescriptVersion = '4.9.4';
-const vermoji = '🏙';
-const version$3 = '3.2.0';
+const vermoji = '🎉';
+const version$3 = '3.2.1';
 const versions = {
   rindo: version$3,
   parse5: parse5Version,
@@ -13344,6 +13487,7 @@ const getModuleLegacy = (_config, compilerCtx, sourceFilePath) => {
       jsFilePath: jsFilePath,
       cmps: [],
       coreRuntimeApis: [],
+      outputTargetCoreRuntimeApis: {},
       collectionName: null,
       dtsFilePath: null,
       excludeFromCollection: false,
@@ -13403,100 +13547,6 @@ const resetModuleLegacy = (moduleFile) => {
   moduleFile.potentialCmpRefs.length = 0;
 };
 
-const relativeImport = (pathFrom, pathTo, ext, addPrefix = true) => {
-  let relativePath = relative$1(dirname(pathFrom), dirname(pathTo));
-  if (addPrefix) {
-    if (relativePath === '') {
-      relativePath = '.';
-    }
-    else if (relativePath[0] !== '.') {
-      relativePath = './' + relativePath;
-    }
-  }
-  return normalizePath$2(`${relativePath}/${basename(pathTo, ext)}`);
-};
-const getComponentsDtsSrcFilePath = (config) => join(config.srcDir, GENERATED_DTS);
-const getComponentsDtsTypesFilePath = (outputTarget) => join(outputTarget.typesDir, GENERATED_DTS);
-const isOutputTargetDist = (o) => o.type === DIST;
-const isOutputTargetDistCollection = (o) => o.type === DIST_COLLECTION;
-const isOutputTargetDistCustomElements = (o) => o.type === DIST_CUSTOM_ELEMENTS;
-// TODO: fully delete dist-custom-elements-bundle code
-const isOutputTargetDistCustomElementsBundle = (o) => o.type === DIST_CUSTOM_ELEMENTS_BUNDLE;
-const isOutputTargetCopy = (o) => o.type === COPY;
-const isOutputTargetDistLazy = (o) => o.type === DIST_LAZY;
-const isOutputTargetDistLazyLoader = (o) => o.type === DIST_LAZY_LOADER;
-const isOutputTargetDistGlobalStyles = (o) => o.type === DIST_GLOBAL_STYLES;
-const isOutputTargetHydrate = (o) => o.type === DIST_HYDRATE_SCRIPT;
-const isOutputTargetCustom = (o) => o.type === CUSTOM;
-const isOutputTargetDocs = (o) => o.type === DOCS_README || o.type === DOCS_JSON || o.type === DOCS_CUSTOM || o.type === DOCS_VSCODE;
-const isOutputTargetDocsReadme = (o) => o.type === DOCS_README;
-const isOutputTargetDocsJson = (o) => o.type === DOCS_JSON;
-const isOutputTargetDocsCustom = (o) => o.type === DOCS_CUSTOM;
-const isOutputTargetDocsVscode = (o) => o.type === DOCS_VSCODE;
-const isOutputTargetWww = (o) => o.type === WWW;
-const isOutputTargetStats = (o) => o.type === STATS;
-const isOutputTargetDistTypes = (o) => o.type === DIST_TYPES;
-const getComponentsFromModules = (moduleFiles) => sortBy(flatOne(moduleFiles.map((m) => m.cmps)), (c) => c.tagName);
-const COPY = 'copy';
-const CUSTOM = 'custom';
-const DIST = 'dist';
-const DIST_COLLECTION = 'dist-collection';
-const DIST_CUSTOM_ELEMENTS = 'dist-custom-elements';
-// TODO: fully delete dist-custom-elements-bundle code
-const DIST_CUSTOM_ELEMENTS_BUNDLE = 'dist-custom-elements-bundle';
-const DIST_TYPES = 'dist-types';
-const DIST_HYDRATE_SCRIPT = 'dist-hydrate-script';
-const DIST_LAZY = 'dist-lazy';
-const DIST_LAZY_LOADER = 'dist-lazy-loader';
-const DIST_GLOBAL_STYLES = 'dist-global-styles';
-const DOCS_CUSTOM = 'docs-custom';
-const DOCS_JSON = 'docs-json';
-const DOCS_README = 'docs-readme';
-const DOCS_VSCODE = 'docs-vscode';
-const STATS = 'stats';
-const WWW = 'www';
-/**
- * Valid output targets to specify in a Rindo config.
- *
- * Note that there are some output targets (e.g. `DIST_TYPES`) which are
- * programmatically set as output targets by the compiler when other output
- * targets (in that case `DIST`) are set, but which are _not_ supported in a
- * Rindo config. This is enforced in the output target validation code.
- */
-const VALID_CONFIG_OUTPUT_TARGETS = [
-  // DIST
-  WWW,
-  DIST,
-  DIST_COLLECTION,
-  DIST_CUSTOM_ELEMENTS,
-  DIST_LAZY,
-  DIST_HYDRATE_SCRIPT,
-  // DOCS
-  DOCS_JSON,
-  DOCS_README,
-  DOCS_VSCODE,
-  DOCS_CUSTOM,
-  // MISC
-  COPY,
-  CUSTOM,
-  STATS,
-];
-/**
- * Check whether a given output target is a valid one to be set in a Rindo config
- *
- * @param targetType the type which we want to check
- * @returns whether or not the targetType is a valid, configurable output target.
- */
-function isValidConfigOutputTarget(targetType) {
-  // unfortunately `includes` is typed on `ReadonlyArray<T>` as `(el: T):
-  // boolean` so a `string` cannot be passed to `includes` on a
-  // `ReadonlyArray` 😢 thus we `as any`
-  //
-  // see microsoft/TypeScript#31018 for some discussion of this
-  return VALID_CONFIG_OUTPUT_TARGETS.includes(targetType);
-}
-const GENERATED_DTS = 'components.d.ts';
-
 /**
  * Derive a {@link ts.CompilerOptions} object from the options currently set
  * on the user-supplied configuration object.
@@ -17509,9 +17559,14 @@ class MockWindow {
       this.__location = val;
     }
   }
-  matchMedia() {
+  matchMedia(media) {
     return {
+      media,
       matches: false,
+      addEventListener,
+      dispatchEvent,
+      removeEventListener,
+      onchange: null,
     };
   }
   get Node() {
@@ -19801,6 +19856,13 @@ const objectToObjectLiteral = (obj, refs) => {
 const createStaticGetter = (propName, returnExpression) => {
   return t.factory.createGetAccessorDeclaration([t.factory.createToken(t.SyntaxKind.StaticKeyword)], propName, [], undefined, t.factory.createBlock([t.factory.createReturnStatement(returnExpression)]));
 };
+/**
+ * Retrieves a value represented by TypeScript's syntax tree by name of a static getter. The value is transformed to a
+ * runtime value.
+ * @param staticMembers a collection of static getters to search
+ * @param staticName the name of the static getter to pull a value from
+ * @returns a TypeScript value, converted from its TypeScript syntax tree representation
+ */
 const getStaticValue = (staticMembers, staticName) => {
   const staticMember = staticMembers.find((member) => member.name.escapedText === staticName);
   if (!staticMember || !staticMember.body || !staticMember.body.statements) {
@@ -20195,15 +20257,32 @@ const parseDocsType = (checker, type, parts) => {
     parts.add(text);
   }
 };
+/**
+ * Retrieves a Rindo `Module` entity from the compiler context for a given TypeScript `SourceFile`
+ * @param compilerCtx the current compiler context to retrieve the `Module` from
+ * @param tsSourceFile the TypeScript compiler `SourceFile` entity to use to retrieve the `Module`
+ * @returns the `Module`, or `undefined` if it cannot be found
+ */
 const getModuleFromSourceFile = (compilerCtx, tsSourceFile) => {
   const sourceFilePath = normalizePath$2(tsSourceFile.fileName);
   const moduleFile = compilerCtx.moduleMap.get(sourceFilePath);
   if (moduleFile != null) {
     return moduleFile;
   }
+  // a key with the `Module`'s filename could not be found, attempt to resolve it by iterating over all modules in the
+  // compiler context
   const moduleFiles = Array.from(compilerCtx.moduleMap.values());
   return moduleFiles.find((m) => m.jsFilePath === sourceFilePath);
 };
+/**
+ * Retrieve the Rindo metadata for a component from the current compiler context, based on the provided TypeScript
+ * syntax tree node. The TypeScript source file is used as a fallback in the event the metadata cannot be found based
+ * on the TypeScript node.
+ * @param compilerCtx the current compiler context
+ * @param tsSourceFile the TypeScript `SourceFile` entity
+ * @param node a TypeScript class representation of a Rindo component
+ * @returns the found metadata, or `undefined` if it cannot be found
+ */
 const getComponentMeta = (compilerCtx, tsSourceFile, node) => {
   const meta = compilerCtx.nodeMap.get(node);
   if (meta) {
@@ -20219,6 +20298,11 @@ const getComponentMeta = (compilerCtx, tsSourceFile, node) => {
   }
   return undefined;
 };
+/**
+ * Retrieves the tag name associated with a Rindo component, based on the 'is' static getter assigned to the class at compile time
+ * @param staticMembers the static getters belonging to the Rindo component class
+ * @returns the tage name, or null if one cannot be found
+ */
 const getComponentTagName = (staticMembers) => {
   if (staticMembers.length > 0) {
     const tagName = getStaticValue(staticMembers, 'is');
@@ -58669,8 +58753,23 @@ const getTsResolveExtension = (p) => {
 };
 const shouldPatchRemoteTypeScript = (compilerExe) => !IS_NODE_ENV && isRemoteUrl(compilerExe);
 
+/**
+ * Helper function for retrieving a Rindo {@link Module} from the provided compiler context
+ * @param compilerCtx the compiler context to retrieve the `Module` from
+ * @param filePath the path of the file corresponding to the `Module` to lookup
+ * @returns the `Module`, or `undefined` if one cannot be found
+ */
 const getModule = (compilerCtx, filePath) => compilerCtx.moduleMap.get(normalizePath$2(filePath));
-const createModule = (staticSourceFile, // this is NOT the original
+/**
+ * Creates a {@link Module} entity with reasonable defaults
+ * @param staticSourceFile the TypeScript representation of the source file. This may not be the original
+ * representation of the file, but instead a new `SourceFile` created using the TypeScript API
+ * @param staticSourceFileText the text from the `SourceFile`. This text may originate from the original representation
+ * of the file.
+ * @param emitFilepath the path of the JavaScript file that should be emitted after transpilation
+ * @returns the created `Module`
+ */
+const createModule = (staticSourceFile, // this may NOT be the original
 staticSourceFileText, emitFilepath) => ({
   sourceFilePath: normalizePath$2(staticSourceFile.fileName),
   jsFilePath: emitFilepath,
@@ -58678,6 +58777,7 @@ staticSourceFileText, emitFilepath) => ({
   staticSourceFileText,
   cmps: [],
   coreRuntimeApis: [],
+  outputTargetCoreRuntimeApis: {},
   collectionName: null,
   dtsFilePath: null,
   excludeFromCollection: false,
@@ -59479,11 +59579,37 @@ const RUNTIME_APIS = {
   registerHost: `registerHost as ${REGISTER_HOST}`,
   registerInstance: `registerInstance as ${REGISTER_INSTANCE}`,
 };
+/**
+ * Update a Rindo Module entity to include a {@link RUNTIME_APIS} entry if it does not already exist.
+ * This allows Rindo to keep `moduleFile` easily serializable, where this helper function treats the data structure
+ * that stores {@link Module#coreRuntimeApis} similar to a JS `Set`.
+ * @param moduleFile the Module entity to update
+ * @param coreRuntimeApi the API to add to the provided module
+ */
 const addCoreRuntimeApi = (moduleFile, coreRuntimeApi) => {
   if (!moduleFile.coreRuntimeApis.includes(coreRuntimeApi)) {
     moduleFile.coreRuntimeApis.push(coreRuntimeApi);
   }
 };
+/**
+ * Update a Rindo Module entity to include a {@link RUNTIME_APIS} entry for a specific output target, if it does not
+ * already exist.
+ * This allows Rindo to keep `moduleFile` easily serializable, where this helper function treats the data structure
+ * that stores {@link Module#outputTargetCoreRuntimeApis} similar to a JS `Set`.
+ * @param moduleFile the Module entity to update
+ * @param outputTarget the output target to assign the provided runtime api under
+ * @param coreRuntimeApi the API to add to the provided module
+ */
+const addOutputTargetCoreRuntimeApi = (moduleFile, outputTarget, coreRuntimeApi) => {
+  if (!moduleFile.outputTargetCoreRuntimeApis[outputTarget]) {
+    // no such output target-specific collection exists, create the empty collection
+    moduleFile.outputTargetCoreRuntimeApis[outputTarget] = [];
+  }
+  if (!moduleFile.outputTargetCoreRuntimeApis[outputTarget].includes(coreRuntimeApi)) {
+    // add the api to the collection
+    moduleFile.outputTargetCoreRuntimeApis[outputTarget].push(coreRuntimeApi);
+  }
+};
 const addLegacyApis = (moduleFile) => {
   addCoreRuntimeApi(moduleFile, RUNTIME_APIS.legacyH);
 };
@@ -59491,12 +59617,9 @@ const addLegacyApis = (moduleFile) => {
 const addModuleMetadataProxies = (tsSourceFile, moduleFile) => {
   const statements = tsSourceFile.statements.slice();
   addCoreRuntimeApi(moduleFile, RUNTIME_APIS.proxyCustomElement);
-  statements.push(...moduleFile.cmps.map(addComponentMetadataProxy));
+  statements.push(...moduleFile.cmps.map(createComponentMetadataProxy));
   return t.factory.updateSourceFile(tsSourceFile, statements);
 };
-const addComponentMetadataProxy = (compilerMeta) => {
-  return t.factory.createExpressionStatement(createComponentMetadataProxy(compilerMeta));
-};
 /**
  * Create a call expression for wrapping a component in a proxy. This call expression takes a form:
  * ```ts
@@ -59504,7 +59627,7 @@ const addComponentMetadataProxy = (compilerMeta) => {
  * ```
  * where
  * - `PROXY_CUSTOM_ELEMENT` is a Rindo internal identifier that will be replaced with the name of the actual function
- * name at compile name
+ * name at compile time
  * - `ComponentClassName` is the name Rindo component's class
  * - `Metadata` is the compiler metadata associated with the Rindo component
  *
@@ -59515,30 +59638,49 @@ const createComponentMetadataProxy = (compilerMeta) => {
   const compactMeta = formatComponentRuntimeMeta(compilerMeta, true);
   const literalCmpClassName = t.factory.createIdentifier(compilerMeta.componentClassName);
   const literalMeta = convertValueToLiteral(compactMeta);
-  return t.factory.createCallExpression(t.factory.createIdentifier(PROXY_CUSTOM_ELEMENT), [], [literalCmpClassName, literalMeta]);
+  return t.factory.createExpressionStatement(t.factory.createCallExpression(t.factory.createIdentifier(PROXY_CUSTOM_ELEMENT), [], [literalCmpClassName, literalMeta]));
 };
 /**
- * Create a call expression for wrapping a component represented as an anonymous class in a proxy. This call expression
- * takes a form:
+ * Create a call expression for wrapping a component represented as a class
+ * expression in a proxy. This call expression takes the form:
+ *
  * ```ts
  * PROXY_CUSTOM_ELEMENT(Clazz, Metadata);
  * ```
+ *
  * where
- * - `PROXY_CUSTOM_ELEMENT` is a Rindo internal identifier that will be replaced with the name of the actual function
- * name at compile name
- * - `Clazz` is an anonymous class to be proxied
+ * - `PROXY_CUSTOM_ELEMENT` is a Rindo internal identifier that will be
+ *   replaced with the name of the actual function name at compile time
+ * - `Clazz` is a class expression to be proxied
  * - `Metadata` is the compiler metadata associated with the Rindo component
  *
- * @param compilerMeta compiler metadata associated with the component to be wrapped in a proxy
- * @param clazz the anonymous class to proxy
+ * @param compilerMeta compiler metadata associated with the component to be
+ * wrapped in a proxy
+ * @param clazz the class expression to proxy
  * @returns the generated call expression
  */
-const createAnonymousClassMetadataProxy = (compilerMeta, clazz) => {
+const createClassMetadataProxy = (compilerMeta, clazz) => {
   const compactMeta = formatComponentRuntimeMeta(compilerMeta, true);
   const literalMeta = convertValueToLiteral(compactMeta);
   return t.factory.createCallExpression(t.factory.createIdentifier(PROXY_CUSTOM_ELEMENT), [], [clazz, literalMeta]);
 };
 
+/**
+ * Create a new import statement, and update the provided source file with the newly created statement.
+ *
+ * The generated import statement will be placed at the beginning of the source file.
+ *
+ * The generated import statement will be either a commonjs require statement or esm import statement, based on the
+ * provided transform options.
+ *
+ * The import statement may include more than one named imports (identifiers) for the provided import path.
+ *
+ * @param transformOpts transform options configured for the current output target transpilation
+ * @param tsSourceFile the TypeScript source file that is being updated
+ * @param importFnNames a collection of named imports to add to the generated import statement
+ * @param importPath the path to the module that the collection of named imports should be imported from
+ * @returns the updated TypeScript source file
+ */
 const addImports = (transformOpts, tsSourceFile, importFnNames, importPath) => {
   if (importFnNames.length === 0) {
     return tsSourceFile;
@@ -59592,8 +59734,13 @@ const proxyCustomElement = (compilerCtx, transformOpts) => {
             if (declaration.name.getText() !== principalComponent.componentClassName) {
               continue;
             }
+            // to narrow the type of `declaration.initializer` to `ts.ClassExpression`
+            if (!t.isClassExpression(declaration.initializer)) {
+              continue;
+            }
+            const renamedClassExpression = t.factory.updateClassExpression(declaration.initializer, t.getModifiers(declaration.initializer), t.factory.createIdentifier(principalComponent.componentClassName), declaration.initializer.typeParameters, declaration.initializer.heritageClauses, declaration.initializer.members);
             // wrap the Rindo component's class declaration in a component proxy
-            const proxyCreationCall = createAnonymousClassMetadataProxy(principalComponent, declaration.initializer);
+            const proxyCreationCall = createClassMetadataProxy(principalComponent, renamedClassExpression);
             t.addSyntheticLeadingComment(proxyCreationCall, t.SyntaxKind.MultiLineCommentTrivia, '@__PURE__', false);
             // update the component's variable declaration to use the new initializer
             const proxiedComponentDeclaration = t.factory.updateVariableDeclaration(declaration, declaration.name, declaration.exclamationToken, declaration.type, proxyCreationCall);
@@ -59797,6 +59944,13 @@ const syntheticRender = (moduleFile, hasRender) => {
 };
 const INTERNAL_RENDER = '__rindo_render';
 
+/**
+ * Creates a new collection of class members that belong to the provided class node and that do not exist in
+ * {@link REMOVE_STATIC_GETTERS}
+ * @param classNode the class node in the syntax tree to inspect
+ * @returns a new collection of class members belonging to the provided class node, less those found in
+ * {@link REMOVE_STATIC_GETTERS}
+ */
 const removeStaticMetaProperties = (classNode) => {
   if (classNode.members == null) {
     return [];
@@ -59812,6 +59966,9 @@ const removeStaticMetaProperties = (classNode) => {
     return true;
   });
 };
+/**
+ * A list of static getter names that are specific to Rindo to exclude from a class's member list
+ */
 const REMOVE_STATIC_GETTERS = new Set([
   'is',
   'properties',
@@ -59897,9 +60054,17 @@ const addNativeConnectedCallback = (classMembers, cmp) => {
   }
 };
 
+/**
+ * For a Rindo component, generate the code to create custom emitted events, based on `@Event()` decorators
+ * @param moduleFile the 'home module' of the class for which code is being generated
+ * @param cmp the component metadata associated with the provided module
+ * @returns the generated event creation code
+ */
 const addCreateEvents = (moduleFile, cmp) => {
   return cmp.events.map((ev) => {
     addCoreRuntimeApi(moduleFile, RUNTIME_APIS.createEvent);
+    // for `@Event('eventName', { <eventOptions> }`, generate assignment to the class constructor of the form:
+    // this.eventName = createEvent(this, 'eventName', eventOptionsAsBitwiseNumber);
     return t.factory.createExpressionStatement(t.factory.createAssignment(t.factory.createPropertyAccessExpression(t.factory.createThis(), t.factory.createIdentifier(ev.method)), t.factory.createCallExpression(t.factory.createIdentifier(CREATE_EVENT), undefined, [
       t.factory.createThis(),
       t.factory.createStringLiteral(ev.name),
@@ -59907,6 +60072,15 @@ const addCreateEvents = (moduleFile, cmp) => {
     ])));
   });
 };
+/**
+ * Generate a bit flag encoded with event behavior information.
+ *
+ * This function uses the provided event metadata to determine which flags are set. {@link EVENT_FLAGS} acts as the
+ * backing data structure that sets the actual bits on the returned value.
+ *
+ * @param eventMeta the metadata associated with the event
+ * @returns the encoded event behaviors
+ */
 const computeFlags = (eventMeta) => {
   let flags = 0;
   if (eventMeta.bubbles) {
@@ -59940,7 +60114,21 @@ const getStatement = (propName, method, arg) => {
   ])));
 };
 
-const updateNativeConstructor = (classMembers, moduleFile, cmp, ensureSuper) => {
+/**
+ * Updates a constructor to include:
+ * - a `super()` call
+ * - function calls to initialize the component
+ * - function calls to create custom event emitters
+ * If a constructor does not exist, one will be created
+ *
+ * The constructor will be added to the provided list of {@link ts.ClassElement}s in place
+ *
+ * @param classMembers the class elements to modify
+ * @param moduleFile the Rindo module representation of the component class
+ * @param cmp the component metadata generated for the component
+ */
+const updateNativeConstructor = (classMembers, moduleFile, cmp) => {
+  var _a, _b;
   if (cmp.isPlain) {
     return;
   }
@@ -59948,30 +60136,28 @@ const updateNativeConstructor = (classMembers, moduleFile, cmp, ensureSuper) =>
   if (cstrMethodIndex >= 0) {
     // add to the existing constructor()
     const cstrMethod = classMembers[cstrMethodIndex];
+    // a constructor may not have a body (e.g. in the case of constructor overloads)
+    const cstrBodyStatements = (_b = (_a = cstrMethod.body) === null || _a === void 0 ? void 0 : _a.statements) !== null && _b !== void 0 ? _b : t.factory.createNodeArray();
     let statements = [
       ...nativeInit(moduleFile, cmp),
       ...addCreateEvents(moduleFile, cmp),
-      ...cstrMethod.body.statements,
+      ...cstrBodyStatements,
       ...addLegacyProps(moduleFile, cmp),
     ];
-    if (ensureSuper) {
-      const hasSuper = cstrMethod.body.statements.some((s) => s.kind === t.SyntaxKind.SuperKeyword);
-      if (!hasSuper) {
-        statements = [createNativeConstructorSuper(), ...statements];
-      }
+    const hasSuper = cstrBodyStatements.some((s) => s.kind === t.SyntaxKind.SuperKeyword);
+    if (!hasSuper) {
+      statements = [createNativeConstructorSuper(), ...statements];
     }
     classMembers[cstrMethodIndex] = t.factory.updateConstructorDeclaration(cstrMethod, retrieveTsModifiers(cstrMethod), cstrMethod.parameters, t.factory.updateBlock(cstrMethod.body, statements));
   }
   else {
     // create a constructor()
-    let statements = [
+    const statements = [
+      createNativeConstructorSuper(),
       ...nativeInit(moduleFile, cmp),
       ...addCreateEvents(moduleFile, cmp),
       ...addLegacyProps(moduleFile, cmp),
     ];
-    if (ensureSuper) {
-      statements = [createNativeConstructorSuper(), ...statements];
-    }
     const cstrMethod = t.factory.createConstructorDeclaration(undefined, [], t.factory.createBlock(statements, true));
     classMembers.unshift(cstrMethod);
   }
@@ -59989,7 +60175,13 @@ const nativeInit = (moduleFile, cmp) => {
   }
   return initStatements;
 };
+/**
+ * Generate an expression statement to register a host element with its VDOM equivalent in a global element-to-vdom
+ * mapping.
+ * @returns the generated expression statement
+ */
 const nativeRegisterHostStatement = () => {
+  // Create an expression statement, `this.__registerHost();`
   return t.factory.createExpressionStatement(t.factory.createCallExpression(t.factory.createPropertyAccessExpression(t.factory.createThis(), t.factory.createIdentifier('__registerHost')), undefined, undefined));
 };
 /**
@@ -59998,12 +60190,16 @@ const nativeRegisterHostStatement = () => {
  * @returns the generated expression statement
  */
 const nativeAttachShadowStatement = (moduleFile) => {
-  addCoreRuntimeApi(moduleFile, RUNTIME_APIS.attachShadow);
+  addOutputTargetCoreRuntimeApi(moduleFile, DIST_CUSTOM_ELEMENTS, RUNTIME_APIS.attachShadow);
   // Create an expression statement, `this.__attachShadow();`
   return t.factory.createExpressionStatement(t.factory.createCallExpression(t.factory.createPropertyAccessExpression(t.factory.createThis(), t.factory.createIdentifier('__attachShadow')), undefined, undefined));
 };
+/**
+ * Create an expression statement for calling `super()` for a class.
+ * @returns the generated expression statement
+ */
 const createNativeConstructorSuper = () => {
-  return t.factory.createExpressionStatement(t.factory.createCallExpression(t.factory.createIdentifier('super'), undefined, undefined));
+  return t.factory.createExpressionStatement(t.factory.createCallExpression(t.factory.createSuper(), undefined, undefined));
 };
 
 const addNativeElementGetter = (classMembers, cmp) => {
@@ -60107,11 +60303,19 @@ const updateNativeComponentClass = (transformOpts, classNode, moduleFile, cmp) =
   const members = updateNativeHostComponentMembers(transformOpts, classNode, moduleFile, cmp);
   return updateComponentClass(transformOpts, classNode, heritageClauses, members);
 };
+/**
+ * Generate a heritage clause (e.g. `extends [IDENTIFIER]`) for a Rindo component to extend `HTMLElement`
+ * @param classNode the syntax tree of the Rindo component class to update
+ * @param moduleFile the Rindo Module associated with the provided class node
+ * @returns the generated heritage clause
+ */
 const updateNativeHostComponentHeritageClauses = (classNode, moduleFile) => {
   if (classNode.heritageClauses != null && classNode.heritageClauses.length > 0) {
+    // the syntax tree has a heritage clause already, don't generate a new one
     return classNode.heritageClauses;
   }
   if (moduleFile.cmps.length >= 1) {
+    // we'll need to import `HTMLElement` in order to extend it
     addCoreRuntimeApi(moduleFile, RUNTIME_APIS.HTMLElement);
   }
   const heritageClause = t.factory.createHeritageClause(t.SyntaxKind.ExtendsKeyword, [
@@ -60121,7 +60325,7 @@ const updateNativeHostComponentHeritageClauses = (classNode, moduleFile) => {
 };
 const updateNativeHostComponentMembers = (transformOpts, classNode, moduleFile, cmp) => {
   const classMembers = removeStaticMetaProperties(classNode);
-  updateNativeConstructor(classMembers, moduleFile, cmp, true);
+  updateNativeConstructor(classMembers, moduleFile, cmp);
   addNativeConnectedCallback(classMembers, cmp);
   addNativeElementGetter(classMembers, cmp);
   addWatchers(classMembers, cmp);
@@ -60135,10 +60339,24 @@ const updateNativeHostComponentMembers = (transformOpts, classNode, moduleFile,
   return classMembers;
 };
 
+/**
+ * A function that returns a transformation factory. The returned factory performs a series of transformations on
+ * Rindo components, in order to generate 'native' web components.
+ * @param compilerCtx the current compiler context, which acts as the source of truth for the transformations
+ * @param transformOpts the transformation configuration to use when performing the transformations
+ * @returns a transformer factory, to be run by the TypeScript compiler
+ */
 const nativeComponentTransform = (compilerCtx, transformOpts) => {
   return (transformCtx) => {
     return (tsSourceFile) => {
+      var _a, _b;
       const moduleFile = getModuleFromSourceFile(compilerCtx, tsSourceFile);
+      /**
+       * Helper function that recursively walks the concrete syntax tree. Upon finding a class declaration that Rindo
+       * recognizes as a component, update the component class
+       * @param node the current node in the tree being inspected
+       * @returns the updated component class, or the unchanged node
+       */
       const visitNode = (node) => {
         if (t.isClassDeclaration(node)) {
           const cmp = getComponentMeta(compilerCtx, tsSourceFile, node);
@@ -60163,7 +60381,11 @@ const nativeComponentTransform = (compilerCtx, transformOpts) => {
       if (moduleFile.isLegacy) {
         addLegacyApis(moduleFile);
       }
-      tsSourceFile = addImports(transformOpts, tsSourceFile, moduleFile.coreRuntimeApis, transformOpts.coreImportPath);
+      const imports = [
+        ...((_a = moduleFile === null || moduleFile === void 0 ? void 0 : moduleFile.coreRuntimeApis) !== null && _a !== void 0 ? _a : []),
+        ...((_b = moduleFile === null || moduleFile === void 0 ? void 0 : moduleFile.outputTargetCoreRuntimeApis[DIST_CUSTOM_ELEMENTS]) !== null && _b !== void 0 ? _b : []),
+      ];
+      tsSourceFile = addImports(transformOpts, tsSourceFile, imports, transformOpts.coreImportPath);
       return tsSourceFile;
     };
   };
@@ -60380,6 +60602,14 @@ const updateBuildConditionals = (config, b) => {
   }
 };
 
+/**
+ * Get build conditions appropriate for the `dist-custom-elements` Output
+ * Target, including disabling lazy loading and hydration.
+ *
+ * @param config a validated user-supplied config
+ * @param cmps metadata about the components currently being compiled
+ * @returns build conditionals appropriate for the `dist-custom-elements` OT
+ */
 const getCustomElementsBuildConditionals = (config, cmps) => {
   // because custom elements bundling does not customize the build conditionals by default
   // then the default in "import { BUILD, NAMESPACE } from '@rindo/core/internal/app-data'"
@@ -60414,9 +60644,9 @@ const outputCustomElements = async (config, compilerCtx, buildCtx) => {
   if (outputTargets.length === 0) {
     return;
   }
-  const bundlingEventMessage = 'generate custom elements';
+  const bundlingEventMessage = `generate custom elements${config.sourceMap ? ' + source maps' : ''}`;
   const timespan = buildCtx.createTimeSpan(`${bundlingEventMessage} started`);
-  await Promise.all(outputTargets.map((target) => bundleCustomElements$1(config, compilerCtx, buildCtx, target)));
+  await Promise.all(outputTargets.map((target) => bundleCustomElements(config, compilerCtx, buildCtx, target)));
   timespan.finish(`${bundlingEventMessage} finished`);
 };
 /**
@@ -60458,7 +60688,7 @@ const getBundleOptions = (config, buildCtx, compilerCtx, outputTarget) => ({
  * @param outputTarget the outputTarget we're currently dealing with
  * @returns an empty promise
  */
-const bundleCustomElements$1 = async (config, compilerCtx, buildCtx, outputTarget) => {
+const bundleCustomElements = async (config, compilerCtx, buildCtx, outputTarget) => {
   try {
     const bundleOpts = getBundleOptions(config, buildCtx, compilerCtx, outputTarget);
     addCustomElementInputs(buildCtx, bundleOpts, outputTarget);
@@ -60564,7 +60794,7 @@ const addCustomElementInputs = (buildCtx, bundleOpts, outputTarget) => {
     bundleOpts.loader[coreKey] = exp.join('\n');
   });
   // Generate the contents of the entry file to be created by the bundler
-  bundleOpts.loader['\0core'] = generateEntryPoint$1(outputTarget, indexImports, indexExports, exportNames);
+  bundleOpts.loader['\0core'] = generateEntryPoint(outputTarget, indexImports, indexExports, exportNames);
 };
 /**
  * Generate the entrypoint (`index.ts` file) contents for the `dist-custom-elements` output target
@@ -60574,7 +60804,7 @@ const addCustomElementInputs = (buildCtx, bundleOpts, outputTarget) => {
  * @param cmpNames The exported component names (could be aliased) from local component modules.
  * @returns the stringified contents to be placed in the entrypoint
  */
-const generateEntryPoint$1 = (outputTarget, cmpImports = [], cmpExports = [], cmpNames = []) => {
+const generateEntryPoint = (outputTarget, cmpImports = [], cmpExports = [], cmpNames = []) => {
   const body = [];
   const imports = [];
   const exports = [];
@@ -60635,134 +60865,6 @@ const getCustomElementCustomTransformer = (config, compilerCtx, components, outp
   ];
 };
 
-// TODO: fully delete dist-custom-elements-bundle code
-const outputCustomElementsBundle = async (config, compilerCtx, buildCtx) => {
-  if (!config.buildDist) {
-    return;
-  }
-  const outputTargets = config.outputTargets.filter(isOutputTargetDistCustomElementsBundle);
-  if (outputTargets.length === 0) {
-    return;
-  }
-  const bundlingEventMessage = `generate custom elements bundle${config.sourceMap ? ' + source maps' : ''}`;
-  const timespan = buildCtx.createTimeSpan(`${bundlingEventMessage} started`);
-  await Promise.all(outputTargets.map((o) => bundleCustomElements(config, compilerCtx, buildCtx, o)));
-  timespan.finish(`${bundlingEventMessage} finished`);
-};
-const bundleCustomElements = async (config, compilerCtx, buildCtx, outputTarget) => {
-  try {
-    const bundleOpts = {
-      id: 'customElementsBundle',
-      platform: 'client',
-      conditionals: getCustomElementsBuildConditionals(config, buildCtx.components),
-      customTransformers: getCustomElementBundleCustomTransformer(config, compilerCtx),
-      externalRuntime: !!outputTarget.externalRuntime,
-      inlineWorkers: true,
-      inputs: {
-        index: '\0core',
-      },
-      loader: {
-        '\0core': generateEntryPoint(outputTarget, buildCtx),
-      },
-      preserveEntrySignatures: 'allow-extension',
-    };
-    const build = await bundleOutput(config, compilerCtx, buildCtx, bundleOpts);
-    if (build) {
-      const rollupOutput = await build.generate({
-        banner: generatePreamble(config),
-        format: 'esm',
-        sourcemap: config.sourceMap,
-        chunkFileNames: outputTarget.externalRuntime || !config.hashFileNames ? '[name].js' : 'p-[hash].js',
-        entryFileNames: '[name].js',
-        hoistTransitiveImports: false,
-        preferConst: true,
-      });
-      const minify = outputTarget.externalRuntime || outputTarget.minify !== true ? false : config.minifyJs;
-      const files = rollupOutput.output.map(async (bundle) => {
-        if (bundle.type === 'chunk') {
-          let code = bundle.code;
-          let sourceMap = rollupToRindoSourceMap(bundle.map);
-          const optimizeResults = await optimizeModule(config, compilerCtx, {
-            input: code,
-            isCore: bundle.isEntry,
-            minify,
-            sourceMap,
-          });
-          buildCtx.diagnostics.push(...optimizeResults.diagnostics);
-          if (!hasError(optimizeResults.diagnostics) && typeof optimizeResults.output === 'string') {
-            code = optimizeResults.output;
-            sourceMap = optimizeResults.sourceMap;
-          }
-          if (sourceMap) {
-            code = code + getSourceMappingUrlForEndOfFile(bundle.fileName);
-            await compilerCtx.fs.writeFile(join(outputTarget.dir, bundle.fileName + '.map'), JSON.stringify(sourceMap), {
-              outputTargetType: outputTarget.type,
-            });
-          }
-          await compilerCtx.fs.writeFile(join(outputTarget.dir, bundle.fileName), code, {
-            outputTargetType: outputTarget.type,
-          });
-        }
-      });
-      await Promise.all(files);
-    }
-  }
-  catch (e) {
-    catchError(buildCtx.diagnostics, e);
-  }
-};
-const generateEntryPoint = (outputTarget, buildCtx) => {
-  const imp = [];
-  const exp = [];
-  const exportNames = [];
-  imp.push(`import { proxyCustomElement } from '${RINDO_INTERNAL_CLIENT_ID}';`, `export { setAssetPath, setPlatformOptions } from '${RINDO_INTERNAL_CLIENT_ID}';`, `export * from '${USER_INDEX_ENTRY_ID}';`);
-  if (outputTarget.includeGlobalScripts !== false) {
-    imp.push(`import { globalScripts } from '${RINDO_APP_GLOBALS_ID}';`, `globalScripts();`);
-  }
-  buildCtx.components.forEach((cmp) => {
-    const exportName = dashToPascalCase$1(cmp.tagName);
-    const importName = cmp.componentClassName;
-    const importAs = `$Cmp${exportName}`;
-    if (cmp.isPlain) {
-      exp.push(`export { ${importName} as ${exportName} } from '${cmp.sourceFilePath}';`);
-    }
-    else {
-      const meta = stringifyRuntimeData(formatComponentRuntimeMeta(cmp, false));
-      imp.push(`import { ${importName} as ${importAs} } from '${cmp.sourceFilePath}';`);
-      exp.push(`export const ${exportName} = /*@__PURE__*/proxyCustomElement(${importAs}, ${meta});`);
-    }
-    exportNames.push(exportName);
-  });
-  exp.push(`export const defineCustomElements = (opts) => {`);
-  exp.push(`  if (typeof customElements !== 'undefined') {`);
-  exp.push(`    [`);
-  exp.push(`      ${exportNames.join(',\n  ')}`);
-  exp.push(`    ].forEach(cmp => {`);
-  exp.push(`      if (!customElements.get(cmp.is)) {`);
-  exp.push(`        customElements.define(cmp.is, cmp, opts);`);
-  exp.push(`      }`);
-  exp.push(`    });`);
-  exp.push(`  }`);
-  exp.push(`};`);
-  return [...imp, ...exp].join('\n') + '\n';
-};
-const getCustomElementBundleCustomTransformer = (config, compilerCtx) => {
-  const transformOpts = {
-    coreImportPath: RINDO_INTERNAL_CLIENT_ID,
-    componentExport: null,
-    componentMetadata: null,
-    currentDirectory: config.sys.getCurrentDirectory(),
-    proxy: null,
-    style: 'static',
-    styleImportData: 'queryparams',
-  };
-  return [
-    updateRindoCoreImports(transformOpts.coreImportPath),
-    nativeComponentTransform(compilerCtx, transformOpts),
-    removeCollectionImports(compilerCtx),
-  ];
-};
-
 const updateLazyComponentConstructor = (classMembers, moduleFile, cmp) => {
   const cstrMethodArgs = [
     t.factory.createParameterDeclaration(undefined, undefined, t.factory.createIdentifier(HOST_REF_ARG)),
@@ -63727,7 +63829,7 @@ export interface CustomElementsDefineOptions {
 export declare function defineCustomElements(win?: Window, opts?: CustomElementsDefineOptions): Promise<void>;
 export declare function applyPolyfills(): Promise<void>;
 
-/** 
+/**
  * Used to specify a nonce value that corresponds with an application's CSP.
  * When set, the nonce will be added to all dynamically created script and style tags at runtime.
  * Alternatively, the nonce value can be set on a meta tag in the DOM head
@@ -63748,7 +63850,7 @@ export declare function setNonce(nonce: string): void;
  */
 const generateCustomElementsTypes = async (config, compilerCtx, buildCtx, typesDir) => {
   const outputTargets = config.outputTargets.filter(isOutputTargetDistCustomElements);
-  await Promise.all(outputTargets.map((outputTarget) => generateCustomElementsTypesOutput$1(config, compilerCtx, buildCtx, typesDir, outputTarget)));
+  await Promise.all(outputTargets.map((outputTarget) => generateCustomElementsTypesOutput(config, compilerCtx, buildCtx, typesDir, outputTarget)));
 };
 /**
  * Generates types for a single `dist-custom-elements` output target definition in a Rindo project's configuration
@@ -63759,7 +63861,7 @@ const generateCustomElementsTypes = async (config, compilerCtx, buildCtx, typesD
  * @param typesDir path to the directory where type declarations are saved
  * @param outputTarget the output target for which types are being currently generated
  */
-const generateCustomElementsTypesOutput$1 = async (config, compilerCtx, buildCtx, typesDir, outputTarget) => {
+const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx, typesDir, outputTarget) => {
   const isBarrelExport = outputTarget.customElementsExportBehavior === 'single-export-module';
   const isBundleExport = outputTarget.customElementsExportBehavior === 'bundle';
   // the path where we're going to write the typedef for the whole dist-custom-elements output
@@ -63785,9 +63887,20 @@ const generateCustomElementsTypesOutput$1 = async (config, compilerCtx, buildCtx
           // - get the relative path to the component's source file from the source directory
           // - join that relative path to the relative path from the `index.d.ts` file to the
           //   directory where typedefs are saved
-          const componentSourceRelPath = relative$1(config.srcDir, component.sourceFilePath).replace('.tsx', '');
+          const componentSourceRelPath = relative$1(config.srcDir, component.sourceFilePath).replace(/\.tsx$/, '');
           const componentDTSPath = join(componentsTypeDirectoryRelPath, componentSourceRelPath);
-          return `export { ${importName} as ${exportName} } from '${componentDTSPath}';`;
+          const defineFunctionExportName = `defineCustomElement${exportName}`;
+          // Get the path to the sibling typedef file for the current component
+          // When we bundle the code to generate the component JS files it generates
+          // the JS and typedef files based on the component tag name. So, we can
+          // just use the tagname to create the relative path
+          const localComponentTypeDefFilePath = `./${component.tagName}`;
+          return [
+            `export { ${importName} as ${exportName} } from '${componentDTSPath}';`,
+            // We need to alias each `defineCustomElement` function typedef to match the aliased name given to the
+            // function in the `index.js`
+            `export { defineCustomElement as ${defineFunctionExportName} } from '${localComponentTypeDefFilePath}';`,
+          ].join('\n');
         }),
         ``,
       ]
@@ -63836,7 +63949,7 @@ const generateCustomElementsTypesOutput$1 = async (config, compilerCtx, buildCtx
       ]
       : []),
   ];
-  const componentsDtsRelPath = relDts$1(outputTarget.dir, join(typesDir, 'components.d.ts'));
+  const componentsDtsRelPath = relDts(outputTarget.dir, join(typesDir, 'components.d.ts'));
   // To mirror the index.js file and only export the typedefs for the
   // entities exported there, we will re-export the typedefs iff
   // the `customElementsExportBehavior` is set to barrel component exports
@@ -63859,7 +63972,7 @@ const generateCustomElementsTypesOutput$1 = async (config, compilerCtx, buildCtx
     outputTargetType: outputTarget.type,
   });
   await Promise.all(components.map(async (cmp) => {
-    const dtsCode = generateCustomElementType$1(componentsDtsRelPath, cmp);
+    const dtsCode = generateCustomElementType(componentsDtsRelPath, cmp);
     const fileName = `${cmp.tagName}.d.ts`;
     const filePath = join(outputTarget.dir, fileName);
     await compilerCtx.fs.writeFile(filePath, dtsCode, { outputTargetType: outputTarget.type });
@@ -63872,7 +63985,7 @@ const generateCustomElementsTypesOutput$1 = async (config, compilerCtx, buildCtx
  * @param cmp the component to generate the type declaration file for
  * @returns the contents of the type declaration file for the provided `cmp`
  */
-const generateCustomElementType$1 = (componentsDtsRelPath, cmp) => {
+const generateCustomElementType = (componentsDtsRelPath, cmp) => {
   const tagNameAsPascal = dashToPascalCase$1(cmp.tagName);
   const o = [
     `import type { Components, JSX } from "${componentsDtsRelPath}";`,
@@ -63897,89 +64010,6 @@ const generateCustomElementType$1 = (componentsDtsRelPath, cmp) => {
  * @param dtsPath the destination path
  * @returns the relative path from the provided `fromPath` to the `dtsPath`
  */
-const relDts$1 = (fromPath, dtsPath) => {
-  dtsPath = relative$1(fromPath, dtsPath);
-  if (!dtsPath.startsWith('.')) {
-    dtsPath = '.' + dtsPath;
-  }
-  return normalizePath$2(dtsPath.replace('.d.ts', ''));
-};
-
-// TODO: fully delete dist-custom-elements-bundle code
-const generateCustomElementsBundleTypes = async (config, compilerCtx, buildCtx, distDtsFilePath) => {
-  const outputTargets = config.outputTargets.filter(isOutputTargetDistCustomElementsBundle);
-  await Promise.all(outputTargets.map((outputTarget) => generateCustomElementsTypesOutput(config, compilerCtx, buildCtx, distDtsFilePath, outputTarget)));
-};
-const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx, distDtsFilePath, outputTarget) => {
-  const customElementsDtsPath = join(outputTarget.dir, 'index.d.ts');
-  const componentsDtsRelPath = relDts(outputTarget.dir, distDtsFilePath);
-  const components = buildCtx.components.filter((m) => !m.isCollectionDependency);
-  const code = [
-    `/* ${config.namespace} custom elements bundle */`,
-    ``,
-    `import type { Components, JSX } from "${componentsDtsRelPath}";`,
-    ``,
-    ...components.map(generateCustomElementType),
-    `/**`,
-    ` * Utility to define all custom elements within this package using the tag name provided in the component's source. `,
-    ` * When defining each custom element, it will also check it's safe to define by:`,
-    ` *`,
-    ` * 1. Ensuring the "customElements" registry is available in the global context (window).`,
-    ` * 2. The component tag name is not already defined.`,
-    ` *`,
-    ` * Use the standard [customElements.define()](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) `,
-    ` * method instead to define custom elements individually, or to provide a different tag name.`,
-    ` */`,
-    `export declare const defineCustomElements: (opts?: any) => void;`,
-    ``,
-    `/**`,
-    ` * Used to manually set the base path where assets can be found.`,
-    ` * If the script is used as "module", it's recommended to use "import.meta.url",`,
-    ` * such as "setAssetPath(import.meta.url)". Other options include`,
-    ` * "setAssetPath(document.currentScript.src)", or using a bundler's replace plugin to`,
-    ` * dynamically set the path at build time, such as "setAssetPath(process.env.ASSET_PATH)".`,
-    ` * But do note that this configuration depends on how your script is bundled, or lack of`,
-    ` * bunding, and where your assets can be loaded from. Additionally custom bundling`,
-    ` * will have to ensure the static assets are copied to its build directory.`,
-    ` */`,
-    `export declare const setAssetPath: (path: string) => void;`,
-    ``,
-    `export interface SetPlatformOptions {`,
-    `  raf?: (c: FrameRequestCallback) => number;`,
-    `  ael?: (el: EventTarget, eventName: string, listener: EventListenerOrEventListenerObject, options: boolean | AddEventListenerOptions) => void;`,
-    `  rel?: (el: EventTarget, eventName: string, listener: EventListenerOrEventListenerObject, options: boolean | AddEventListenerOptions) => void;`,
-    `  ce?: (eventName: string, opts?: any) => CustomEvent;`,
-    `}`,
-    `export declare const setPlatformOptions: (opts: SetPlatformOptions) => void;`,
-    ``,
-    `export type { Components, JSX };`,
-    ``,
-  ];
-  const usersIndexJsPath = join(config.srcDir, 'index.ts');
-  const hasUserIndex = await compilerCtx.fs.access(usersIndexJsPath);
-  if (hasUserIndex) {
-    const userIndexRelPath = normalizePath$2(dirname(componentsDtsRelPath));
-    code.push(`export * from '${userIndexRelPath}';`);
-  }
-  else {
-    code.push(`export * from '${componentsDtsRelPath}';`);
-  }
-  await compilerCtx.fs.writeFile(customElementsDtsPath, code.join('\n') + `\n`, {
-    outputTargetType: outputTarget.type,
-  });
-};
-const generateCustomElementType = (cmp) => {
-  const tagNameAsPascal = dashToPascalCase$1(cmp.tagName);
-  const o = [
-    `interface ${tagNameAsPascal} extends Components.${tagNameAsPascal}, HTMLElement {}`,
-    `export const ${tagNameAsPascal}: {`,
-    `  prototype: ${tagNameAsPascal};`,
-    `  new (): ${tagNameAsPascal};`,
-    `};`,
-    ``,
-  ];
-  return o.join('\n');
-};
 const relDts = (fromPath, dtsPath) => {
   dtsPath = relative$1(fromPath, dtsPath);
   if (!dtsPath.startsWith('.')) {
@@ -64538,7 +64568,6 @@ const generateTypesOutput = async (config, compilerCtx, buildCtx, outputTarget)
   await generateAppTypes(config, compilerCtx, buildCtx, distPath);
   const { typesDir } = outputTarget;
   if (distDtsFilePath) {
-    await generateCustomElementsBundleTypes(config, compilerCtx, buildCtx, distDtsFilePath);
     await generateCustomElementsTypes(config, compilerCtx, buildCtx, typesDir);
   }
 };
@@ -65104,7 +65133,6 @@ const generateOutputTargets = async (config, compilerCtx, buildCtx) => {
     outputCopy(config, compilerCtx, buildCtx),
     outputCollection(config, compilerCtx, buildCtx, changedModuleFiles),
     outputCustomElements(config, compilerCtx, buildCtx),
-    outputCustomElementsBundle(config, compilerCtx, buildCtx),
     outputHydrateScript(config, compilerCtx, buildCtx),
     outputLazyLoader(config, compilerCtx),
     outputLazy(config, compilerCtx, buildCtx),
@@ -65129,7 +65157,6 @@ const invalidateRollupCaches = (compilerCtx) => {
 
 const isEmptable = (o) => isOutputTargetDist(o) ||
   isOutputTargetDistCustomElements(o) ||
-  isOutputTargetDistCustomElementsBundle(o) ||
   isOutputTargetWww(o) ||
   isOutputTargetDistLazy(o) ||
   isOutputTargetDistLazyLoader(o) ||
@@ -69051,7 +69078,6 @@ const validateModule = async (config, compilerCtx, buildCtx) => {
  * value is supplied
  */
 function recommendedModulePath(config) {
-  const customElementsBundleOT = config.outputTargets.find(isOutputTargetDistCustomElementsBundle);
   const customElementsOT = config.outputTargets.find(isOutputTargetDistCustomElements);
   const distCollectionOT = config.outputTargets.find(isOutputTargetDistCollection);
   if (distCollectionOT) {
@@ -69061,10 +69087,6 @@ function recommendedModulePath(config) {
     const componentsIndexAbs = join(customElementsOT.dir, 'index.js');
     return relative$1(config.rootDir, componentsIndexAbs);
   }
-  if (customElementsBundleOT) {
-    const customElementsAbs = join(customElementsBundleOT.dir, 'index.js');
-    return relative$1(config.rootDir, customElementsAbs);
-  }
   // if no output target for which we define a recommended output target is set
   // we return `null`
   return null;
@@ -69633,6 +69655,12 @@ const createWatchBuild = async (config, compilerCtx) => {
     buildCtx.hasStyleChanges = hasStyleChanges(buildCtx);
     buildCtx.hasHtmlChanges = hasHtmlChanges(config, buildCtx);
     buildCtx.hasServiceWorkerChanges = hasServiceWorkerChanges(config, buildCtx);
+    if (config.flags.debug) {
+      config.logger.debug(`WATCH_BUILD::watchBuild::onBuild filesAdded: ${formatFilesForDebug(buildCtx.filesAdded)}`);
+      config.logger.debug(`WATCH_BUILD::watchBuild::onBuild filesDeleted: ${formatFilesForDebug(buildCtx.filesDeleted)}`);
+      config.logger.debug(`WATCH_BUILD::watchBuild::onBuild filesUpdated: ${formatFilesForDebug(buildCtx.filesUpdated)}`);
+      config.logger.debug(`WATCH_BUILD::watchBuild::onBuild filesWritten: ${formatFilesForDebug(buildCtx.filesWritten)}`);
+    }
     dirsAdded.clear();
     dirsDeleted.clear();
     filesAdded.clear();
@@ -69645,6 +69673,21 @@ const createWatchBuild = async (config, compilerCtx) => {
       isRebuild = true;
     }
   };
+  /**
+   * Utility method for formatting a debug message that must either list a number of files, or the word 'none' if the
+   * provided list is empty
+   * @param files a list of files, the list may be empty
+   * @returns the provided list if it is not empty. otherwise, return the word 'none'
+   */
+  const formatFilesForDebug = (files) => {
+    /**
+     * In the created message, it's important that there's no whitespace prior to the file name.
+     * Rindo's logger will split messages by whitespace according to the width of the terminal window.
+     * Since file names can be fully qualified paths (and therefore quite long), putting whitespace between a '-' and
+     * the path can lead to formatted messages where the '-' is on its own line
+     */
+    return files.length > 0 ? files.map((filename) => `-${filename}`).join('\n') : 'none';
+  };
   const start = async () => {
     const srcRead = watchSrcDirectory(config, compilerCtx);
     const otherRead = watchRootFiles(config, compilerCtx);
@@ -69675,7 +69718,7 @@ const createWatchBuild = async (config, compilerCtx) => {
           filesDeleted.add(p);
           break;
       }
-      config.logger.debug(`onFsChange ${eventKind}: ${p}`);
+      config.logger.debug(`WATCH_BUILD::fs_event_change - type=${eventKind}, path=${p}, time=${new Date().getTime()}`);
       tsWatchProgram.rebuild();
     }
   };
@@ -71447,32 +71490,6 @@ const validateCustomElement = (config, userOutputs) => {
   }, []);
 };
 
-// TODO: fully delete dist-custom-elements-bundle code
-const validateCustomElementBundle = (config, userOutputs) => {
-  return userOutputs.filter(isOutputTargetDistCustomElementsBundle).reduce((arr, o) => {
-    const outputTarget = {
-      ...o,
-      dir: getAbsolutePath(config, o.dir || 'dist/custom-elements'),
-    };
-    if (!isBoolean$1(outputTarget.empty)) {
-      outputTarget.empty = true;
-    }
-    if (!isBoolean$1(outputTarget.externalRuntime)) {
-      outputTarget.externalRuntime = true;
-    }
-    outputTarget.copy = validateCopy(outputTarget.copy, []);
-    if (outputTarget.copy.length > 0) {
-      arr.push({
-        type: COPY,
-        dir: config.rootDir,
-        copy: [...outputTarget.copy],
-      });
-    }
-    arr.push(outputTarget);
-    return arr;
-  }, []);
-};
-
 const validateCustomOutput = (config, diagnostics, userOutputs) => {
   return userOutputs.filter(isOutputTargetCustom).map((o) => {
     if (o.validate) {
@@ -71974,7 +71991,6 @@ const validateOutputTargets = (config, diagnostics) => {
   config.outputTargets = [
     ...validateCollection(config, userOutputs),
     ...validateCustomElement(config, userOutputs),
-    ...validateCustomElementBundle(config, userOutputs),
     ...validateCustomOutput(config, diagnostics, userOutputs),
     ...validateLazy(config, userOutputs),
     ...validateWww(config, diagnostics, userOutputs),