@elenajs/bundler 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ariel Salminen https://arielsalminen.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cem-analyze.js

@@ -0,0 +1,87 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join, resolve } from "path";
+import { create, ts } from "@custom-elements-manifest/analyzer";
+import globby from "globby";
+import { customElementJsxPlugin as elenaJsxPlugin } from "custom-element-jsx-integration";
+import { elenaDefinePlugin } from "./plugins/cem-define.js";
+import { elenaTagPlugin } from "./plugins/cem-tag.js";
+import { elenaTypeScriptPlugin } from "./plugins/cem-typescript.js";
+import { color } from "./utils/color.js";
+
+/**
+ * Returns the CEM config object for the given Elena config. Useful for advanced
+ * users who still call the CEM CLI with a thin `elena.config.js` wrapper.
+ *
+ * @param {import("./utils/load-config.js").ElenaConfig} [options]
+ * @returns {object} CEM config object
+ */
+export function createCemConfig(options = {}) {
+  const src = options.input ?? "src";
+  const outdir = options.output?.dir ?? "dist";
+  const extraPlugins = options.analyze?.plugins ?? [];
+
+  return {
+    outdir,
+    watch: false,
+    dev: false,
+    globs: [`${src}/**/*.js`],
+    exclude: [`${src}/**/*.ts`, "**/*.test.js", "node_modules"],
+    plugins: [
+      elenaDefinePlugin(),
+      elenaTagPlugin("status"),
+      elenaTagPlugin("displayName"),
+      elenaJsxPlugin({ outdir, fileName: "custom-elements.d.ts" }),
+      elenaTypeScriptPlugin({ outdir }),
+      ...extraPlugins,
+    ],
+  };
+}
+
+/**
+ * Runs the CEM analyzer programmatically using `create()` from
+ * `@custom-elements-manifest/analyzer`, writes the manifest to disk.
+ *
+ * @param {import("./utils/load-config.js").ElenaConfig} config
+ * @param {string} [cwd]
+ * @returns {Promise<void>}
+ */
+export async function runCemAnalyze(config, cwd = process.cwd()) {
+  const src = config.input ?? "src";
+  const outdir = config.output?.dir ?? "dist";
+  const extraPlugins = config.analyze?.plugins ?? [];
+
+  console.log(` `);
+  console.log(color(`░█ [ELENA]: Analyzing the build output...`));
+  console.log(color(`░█ [ELENA]: Generating Custom Elements Manifest...`));
+  console.log(color(`░█ [ELENA]: Generating TypeScript types...`));
+  console.log(` `);
+
+  const globs = await globby(
+    [`${src}/**/*.js`, `!${src}/**/*.ts`, "!**/*.test.js", "!node_modules"],
+    { cwd }
+  );
+
+  const modules = globs.map(glob => {
+    const fullPath = resolve(cwd, glob);
+    const source = readFileSync(fullPath).toString();
+    return ts.createSourceFile(glob, source, ts.ScriptTarget.ES2015, true);
+  });
+
+  const plugins = [
+    elenaDefinePlugin(),
+    elenaTagPlugin("status"),
+    elenaTagPlugin("displayName"),
+    elenaJsxPlugin({ outdir, fileName: "custom-elements.d.ts" }),
+    elenaTypeScriptPlugin({ outdir: join(cwd, outdir) }),
+    ...extraPlugins,
+  ];
+
+  const manifest = create({ modules, plugins, context: { dev: false } });
+
+  const outPath = join(cwd, outdir);
+  if (!existsSync(outPath)) {
+    mkdirSync(outPath, { recursive: true });
+  }
+
+  writeFileSync(join(outPath, "custom-elements.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+}

package/dist/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { loadConfig } from "./utils/load-config.js";
+import { runRollupBuild } from "./rollup-build.js";
+import { runCemAnalyze } from "./cem-analyze.js";
+import { color } from "./utils/color.js";
+
+const BANNER = `
+ ██████████ ████
+░░███░░░░░█░░███
+ ░███  █ ░  ░███   ██████  ████████    ██████
+ ░██████    ░███  ███░░███░░███░░███  ░░░░░███
+ ░███░░█    ░███ ░███████  ░███ ░███   ███████
+ ░███ ░   █ ░███ ░███░░░   ░███ ░███  ███░░███
+ ██████████ █████░░██████  ████ █████░░████████
+░░░░░░░░░░ ░░░░░  ░░░░░░  ░░░░ ░░░░░  ░░░░░░░░
+`;
+
+const [, , command = "build"] = process.argv;
+
+async function main() {
+  if (command !== "build") {
+    console.error(`Unknown command: ${command}. Usage: elena [build]`);
+    process.exit(1);
+  }
+
+  console.log(color(BANNER));
+
+  const config = await loadConfig(process.cwd());
+
+  await runRollupBuild(config);
+  await runCemAnalyze(config);
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createRollupConfig, runRollupBuild } from "./rollup-build.js";
+export { createCemConfig, runCemAnalyze } from "./cem-analyze.js";
+export { cssBundlePlugin } from "./plugins/css-bundle.js";
+export { elenaDefinePlugin } from "./plugins/cem-define.js";
+export { elenaTagPlugin } from "./plugins/cem-tag.js";
+export { elenaTypeScriptPlugin } from "./plugins/cem-typescript.js";

package/dist/plugins/cem-define.js

@@ -0,0 +1,93 @@
+/**
+ * CEM analyzer plugin that reads `tagName` from the options object passed to
+ * `Elena(superClass, { tagName: "...", ... })` and registers the element in the manifest.
+ *
+ * Supports both inline objects and variable references:
+ * - `Elena(HTMLElement, { tagName: "elena-button", ... })`
+ * - `const options = { tagName: "elena-button", ... }; Elena(HTMLElement, options)`
+ *
+ * @returns {import("@custom-elements-manifest/analyzer").Plugin}
+ */
+export function elenaDefinePlugin() {
+  /** @type {Map<string, string>} variable name → tag name */
+  const optionsMap = new Map();
+
+  return {
+    name: "define-element",
+
+    analyzePhase({ ts, node, moduleDoc }) {
+      // Collect variable declarations: const options = { tagName: "...", ... }
+      if (
+        ts.isVariableDeclaration(node) &&
+        node.initializer &&
+        ts.isObjectLiteralExpression(node.initializer)
+      ) {
+        const varName = node.name.getText();
+        const tagNameProp = node.initializer.properties.find(
+          p => ts.isPropertyAssignment(p) && p.name.getText() === "tagName"
+        );
+        if (tagNameProp && ts.isStringLiteral(tagNameProp.initializer)) {
+          optionsMap.set(varName, tagNameProp.initializer.text);
+        }
+        return;
+      }
+
+      if (!ts.isClassDeclaration(node)) {
+        return;
+      }
+
+      const className = node.name?.getText();
+      if (!className) {
+        return;
+      }
+
+      const heritageClause = node.heritageClauses?.[0];
+      if (!heritageClause) {
+        return;
+      }
+
+      for (const type of heritageClause.types) {
+        const expr = type.expression;
+        if (!ts.isCallExpression(expr) || expr.expression.getText() !== "Elena") {
+          continue;
+        }
+
+        const optionsArg = expr.arguments[1];
+        if (!optionsArg) {
+          continue;
+        }
+
+        let tagName;
+
+        if (ts.isObjectLiteralExpression(optionsArg)) {
+          // Inline: Elena(HTMLElement, { tagName: "...", ... })
+          const tagNameProp = optionsArg.properties.find(
+            p => ts.isPropertyAssignment(p) && p.name.getText() === "tagName"
+          );
+          if (tagNameProp && ts.isStringLiteral(tagNameProp.initializer)) {
+            tagName = tagNameProp.initializer.text;
+          }
+        } else if (ts.isIdentifier(optionsArg)) {
+          // Variable reference: Elena(HTMLElement, options)
+          tagName = optionsMap.get(optionsArg.getText());
+        }
+
+        if (!tagName) {
+          continue;
+        }
+
+        const declaration = moduleDoc.declarations?.find(d => d.name === className);
+        if (declaration) {
+          declaration.tagName = tagName;
+        }
+
+        moduleDoc.exports ??= [];
+        moduleDoc.exports.push({
+          kind: "custom-element-definition",
+          name: tagName,
+          declaration: { name: className, module: moduleDoc.path },
+        });
+      }
+    },
+  };
+}

package/dist/plugins/cem-tag.js

@@ -0,0 +1,54 @@
+/**
+ * Returns the CEM class declaration and resolved tag name for a class node,
+ * or `undefined` if the node is not a registered custom element.
+ *
+ * @param {Partial<import("@custom-elements-manifest/analyzer").JavaScriptModule>} moduleDoc
+ * @param {import("typescript").ClassDeclaration} node
+ * @returns {{ class: import("@custom-elements-manifest/analyzer").Declaration; tagName: string } | undefined}
+ */
+function getElenaElementDetails(moduleDoc, node) {
+  const declaration = moduleDoc.declarations?.find(d => d.name === node.name?.getText());
+  if (!declaration) {
+    return undefined;
+  }
+
+  const customElement = moduleDoc.exports?.find(
+    e => e.kind === "js" && e.declaration.name === declaration.name
+  );
+
+  if (!customElement) {
+    return undefined;
+  }
+
+  return { class: declaration, tagName: customElement.name };
+}
+
+/**
+ * CEM analyzer plugin that reads a non-standard JSDoc tag from each custom element class
+ * and writes its value onto the CEM class declaration under the same key.
+ *
+ * Used for Elena-specific tags like `@status` and `@displayName`.
+ *
+ * @see https://custom-elements-manifest.open-wc.org/analyzer/plugins/authoring/#example-plugin
+ * @param {string} tagName - The JSDoc tag name to extract (e.g. `"status"`, `"displayName"`).
+ * @returns {import("@custom-elements-manifest/analyzer").Plugin}
+ */
+export function elenaTagPlugin(tagName) {
+  return {
+    name: `${tagName}-tag`,
+
+    analyzePhase({ ts, node, moduleDoc }) {
+      if (!ts.isClassDeclaration(node)) {
+        return;
+      }
+
+      const details = getElenaElementDetails(moduleDoc, node);
+      if (!details) {
+        return;
+      }
+
+      const [tag] = ts.getAllJSDocTags(node, t => t.tagName.getText() === tagName);
+      details.class[tagName] = tag && ts.getTextOfJSDocComment(tag.comment);
+    },
+  };
+}

package/dist/plugins/cem-typescript.js

@@ -0,0 +1,56 @@
+import { writeFileSync } from "fs";
+import { join } from "path";
+
+/**
+ * CEM analyzer plugin that generates a per-component `.d.ts` file for each
+ * custom element in the manifest.
+ *
+ * This lets TypeScript resolve sub-path imports like
+ * `@elenajs/components/dist/button.js` without manual declaration files.
+ *
+ * @param {{ outdir?: string }} options
+ * @returns {import("@custom-elements-manifest/analyzer").Plugin}
+ */
+export function elenaTypeScriptPlugin({ outdir = "dist" } = {}) {
+  return {
+    name: "per-component-dts",
+
+    packageLinkPhase({ customElementsManifest }) {
+      for (const mod of customElementsManifest.modules) {
+        const ceDecl = mod.declarations?.find(d => d.tagName);
+        if (!ceDecl) {
+          continue;
+        }
+
+        const fields = (ceDecl.members ?? []).filter(m => m.kind === "field" && !m.static);
+        const events = ceDecl.events ?? [];
+
+        const fieldLines = fields.map(f => {
+          const lines = [];
+          if (f.description) {
+            lines.push(`  /** ${f.description} */`);
+          }
+          lines.push(`  ${f.name}?: ${f.type?.text ?? "string"};`);
+          return lines.join("\n");
+        });
+
+        const eventLines = events.map(e => {
+          const lines = [];
+          if (e.description) {
+            lines.push(`  /** ${e.description} */`);
+          }
+          lines.push(`  on${e.name}?: (e: CustomEvent<never>) => void;`);
+          return lines.join("\n");
+        });
+
+        const members = [...fieldLines, ...eventLines].join("\n");
+        const body = members ? `\n${members}\n` : "";
+        const propsType = `${ceDecl.name}Props`;
+        const content = `export type { ${propsType} } from './custom-elements.js';\n\ndeclare class ${ceDecl.name} extends HTMLElement {${body}}\n\nexport default ${ceDecl.name};\n`;
+
+        const fileName = mod.path.split("/").pop().replace(".js", ".d.ts");
+        writeFileSync(join(outdir, fileName), content);
+      }
+    },
+  };
+}

package/dist/plugins/css-bundle.js

@@ -0,0 +1,37 @@
+import { readFileSync, readdirSync } from "fs";
+import { color } from "../utils/color.js";
+
+/**
+ * Rollup plugin that concatenates and minifies all CSS files from `srcDir` into a
+ * single bundle asset emitted to the output directory.
+ *
+ * @param {string} srcDir - Source directory to scan for `.css` files (e.g. `"src"`).
+ * @param {string} fileName - Output filename relative to the output dir (e.g. `"bundle.css"`).
+ * @returns {import("rollup").Plugin}
+ */
+export function cssBundlePlugin(srcDir, fileName) {
+  return {
+    name: "css-bundle",
+    generateBundle() {
+      const cssFiles = readdirSync(srcDir, { recursive: true })
+        .filter(f => f.endsWith(".css"))
+        .map(f => `${srcDir}/${f}`);
+
+      const source = cssFiles
+        .map(f => readFileSync(f, "utf8"))
+        .join("\n")
+        // Strip block comments
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        // Collapse whitespace runs into a single space
+        .replace(/\s+/g, " ")
+        // Remove spaces around structural characters
+        .replace(/\s*([{}:;,>~+])\s*/g, "$1")
+        // Drop trailing semicolons before closing brace
+        .replace(/;}/g, "}")
+        .trim();
+
+      this.emitFile({ type: "asset", fileName, source });
+      console.log(color(`░█ [ELENA]: Generating and minifying CSS bundle...`));
+    },
+  };
+}

package/dist/rollup-build.js

@@ -0,0 +1,177 @@
+import { readdirSync } from "fs";
+import { rollup } from "rollup";
+import resolve from "@rollup/plugin-node-resolve";
+import terser from "@rollup/plugin-terser";
+import copy from "rollup-plugin-copy";
+import minifyHtmlLiterals from "rollup-plugin-minify-html-literals-v3";
+import summary from "rollup-plugin-summary";
+import { cssBundlePlugin } from "./plugins/css-bundle.js";
+import { color } from "./utils/color.js";
+
+const TREESHAKE = {
+  moduleSideEffects: false,
+  propertyReadSideEffects: false,
+};
+
+function onwarn(warning, warn) {
+  if (warning.code === "UNUSED_EXTERNAL_IMPORT") {
+    return;
+  }
+  warn(warning);
+}
+
+/**
+ * Builds the plugin list for a single Rollup build target.
+ *
+ * @param {{ src: string; outdir: string; hasSummary: boolean; includeCssBundle: boolean; extraPlugins?: import("rollup").Plugin[] }} opts
+ * @returns {import("rollup").Plugin[]}
+ */
+function buildPlugins({ src, outdir, hasSummary, includeCssBundle, extraPlugins = [] }) {
+  const plugins = [
+    resolve({ extensions: [".js", ".css"] }),
+    minifyHtmlLiterals({
+      options: {
+        // Elena components use this.template`...` rather than html`...`
+        shouldMinify: template => template.parts.some(({ text }) => /<[a-z]/i.test(text)),
+      },
+    }),
+    terser({
+      ecma: 2020,
+      module: true,
+    }),
+    copy({
+      targets: [{ src: `${src}/**/*.css`, dest: outdir }],
+      flatten: true,
+    }),
+  ];
+
+  if (includeCssBundle) {
+    plugins.push(cssBundlePlugin(src, "bundle.css"));
+  }
+
+  // User-provided plugins are appended after built-ins, before summary.
+  plugins.push(...extraPlugins);
+
+  if (hasSummary) {
+    plugins.push(summary({ showBrotliSize: true, showGzippedSize: true }));
+  }
+
+  return plugins;
+}
+
+/**
+ * Returns the Rollup config array for the given Elena config. Useful for advanced
+ * users who want to call `rollup -c` with a thin wrapper config file.
+ *
+ * @param {import("./utils/load-config.js").ElenaConfig} [options]
+ * @returns {import("rollup").RollupOptions[]}
+ */
+export function createRollupConfig(options = {}) {
+  const src = options.input ?? "src";
+  const outdir = options.output?.dir ?? "dist";
+  const format = options.output?.format ?? "esm";
+  const sourcemap = options.output?.sourcemap ?? true;
+  const bundle = options.bundle !== undefined ? options.bundle : "src/index.js";
+  const extraPlugins = options.plugins ?? [];
+
+  const entries = readdirSync(src, { recursive: true })
+    .filter(f => f.endsWith(".js"))
+    .map(f => `${src}/${f}`);
+
+  const configs = [
+    {
+      input: entries,
+      plugins: buildPlugins({
+        src,
+        outdir,
+        hasSummary: false,
+        includeCssBundle: true,
+        extraPlugins,
+      }),
+      output: { format, sourcemap, dir: outdir },
+      preserveEntrySignatures: "strict",
+      treeshake: TREESHAKE,
+      onwarn,
+    },
+  ];
+
+  if (bundle) {
+    configs.push({
+      input: bundle,
+      plugins: buildPlugins({
+        src,
+        outdir,
+        hasSummary: true,
+        includeCssBundle: false,
+        extraPlugins,
+      }),
+      output: { format, sourcemap, file: `${outdir}/bundle.js` },
+      preserveEntrySignatures: "strict",
+      treeshake: TREESHAKE,
+      onwarn,
+    });
+  }
+
+  return configs;
+}
+
+/**
+ * Runs both Rollup build targets programmatically using the Rollup Node.js API.
+ *
+ * Note: the `output` key inside `RollupOptions` is ignored by the `rollup()` API —
+ * output options must be passed separately to `build.write()`.
+ *
+ * @param {import("./utils/load-config.js").ElenaConfig} config
+ * @returns {Promise<void>}
+ */
+export async function runRollupBuild(config) {
+  const src = config.input ?? "src";
+  const outdir = config.output?.dir ?? "dist";
+  const format = config.output?.format ?? "esm";
+  const sourcemap = config.output?.sourcemap ?? true;
+  const bundle = config.bundle !== undefined ? config.bundle : "src/index.js";
+  const extraPlugins = config.plugins ?? [];
+
+  const entries = readdirSync(src, { recursive: true })
+    .filter(f => f.endsWith(".js"))
+    .map(f => `${src}/${f}`);
+
+  // Build 1: individual modules + CSS bundle
+  console.log(color(`░█ [ELENA]: Building Progressive Web Components...`));
+  console.log(` `);
+  for (const entry of entries) {
+    console.log(color(`░█ [ELENA]: Generating and minifying ${entry}...`));
+  }
+
+  const build1 = await rollup({
+    input: entries,
+    plugins: buildPlugins({ src, outdir, hasSummary: false, includeCssBundle: true, extraPlugins }),
+    preserveEntrySignatures: "strict",
+    treeshake: TREESHAKE,
+    onwarn,
+  });
+  await build1.write({ format, sourcemap, dir: outdir });
+  await build1.close();
+
+  // Build 2: single-file JS bundle (optional)
+  if (bundle) {
+    console.log(color(`░█ [ELENA]: Generating and minifying JS bundle...`));
+    console.log(` `);
+
+    const build2 = await rollup({
+      input: bundle,
+      plugins: buildPlugins({
+        src,
+        outdir,
+        hasSummary: true,
+        includeCssBundle: false,
+        extraPlugins,
+      }),
+      preserveEntrySignatures: "strict",
+      treeshake: TREESHAKE,
+      onwarn,
+    });
+    await build2.write({ format, sourcemap, file: `${outdir}/bundle.js` });
+    await build2.close();
+  }
+}

package/dist/utils/color.js

@@ -0,0 +1,2 @@
+/** Applies the Elena brand color (#f19c77) to a string using ANSI true color escape codes. */
+export const color = str => `\x1b[38;2;241;156;119m${str}\x1b[0m`;

package/dist/utils/load-config.js

@@ -0,0 +1,57 @@
+import { pathToFileURL } from "url";
+import { resolve } from "path";
+import { existsSync } from "fs";
+
+/**
+ * @typedef {object} ElenaOutputConfig
+ * @property {string} [dir]        Output directory for individual modules, CSS, and CEM artifacts.
+ * @property {string} [format]     Rollup output format (default: `"esm"`).
+ * @property {boolean} [sourcemap] Whether to emit sourcemaps (default: `true`).
+ */
+
+/**
+ * @typedef {object} ElenaAnalyzeConfig
+ * @property {import("@custom-elements-manifest/analyzer").Plugin[]} [plugins]
+ *   Additional CEM analyzer plugins appended after Elena's built-in set.
+ */
+
+/**
+ * @typedef {object} ElenaConfig
+ * @property {string}             [input]   Source directory scanned for .js and .css files.
+ * @property {ElenaOutputConfig}  [output]  Rollup output options.
+ * @property {string|false}       [bundle]  Entry for the single-file bundle; `false` to disable.
+ * @property {import("rollup").Plugin[]} [plugins] Additional Rollup plugins appended after built-ins.
+ * @property {ElenaAnalyzeConfig} [analyze] CEM analysis options.
+ */
+
+/** @type {Required<ElenaConfig>} */
+const DEFAULTS = {
+  input: "src",
+  output: { dir: "dist", format: "esm", sourcemap: true },
+  bundle: "src/index.js",
+  plugins: [],
+  analyze: { plugins: [] },
+};
+
+/**
+ * Loads the Elena config from `elena.config.mjs` or `elena.config.js` in `cwd`,
+ * falling back to defaults if no config file is found.
+ *
+ * @param {string} [cwd]
+ * @returns {Promise<Required<ElenaConfig>>}
+ */
+export async function loadConfig(cwd = process.cwd()) {
+  for (const name of ["elena.config.mjs", "elena.config.js"]) {
+    const configPath = resolve(cwd, name);
+    if (!existsSync(configPath)) continue;
+    const mod = await import(pathToFileURL(configPath).href);
+    const user = mod.default ?? {};
+    return {
+      ...DEFAULTS,
+      ...user,
+      output: { ...DEFAULTS.output, ...user.output },
+      analyze: { ...DEFAULTS.analyze, ...user.analyze },
+    };
+  }
+  return { ...DEFAULTS };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@elenajs/bundler",
+  "version": "0.0.2",
+  "description": "Bundler for Elena component libraries: Rollup + CEM analyzer in one CLI command.",
+  "author": "Ariel Salminen <info@arielsalminen.com>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "elena": "./src/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./rollup": "./dist/rollup-build.js",
+    "./cem": "./dist/cem-analyze.js",
+    "./plugins/css-bundle": "./dist/plugins/css-bundle.js",
+    "./plugins/cem-define": "./dist/plugins/cem-define.js",
+    "./plugins/cem-tag": "./dist/plugins/cem-tag.js",
+    "./plugins/cem-typescript": "./dist/plugins/cem-typescript.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">= 20"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "format": "prettier --write \"src/**/*.js\" \"test/**/*.mjs\" \"*.mjs\"",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@custom-elements-manifest/analyzer": "0.11.0",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "@rollup/plugin-terser": "0.4.4",
+    "custom-element-jsx-integration": "1.6.0",
+    "globby": "11.0.4",
+    "rollup": "4.57.1",
+    "rollup-plugin-copy": "3.5.0",
+    "rollup-plugin-minify-html-literals-v3": "^1.3.4",
+    "rollup-plugin-summary": "3.0.1"
+  },
+  "devDependencies": {
+    "vitest": "4.0.18"
+  },
+  "gitHead": "640bc98adce4748a037120e319507bb8efcb721c"
+}

package/src/cem-analyze.js

@@ -0,0 +1,87 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join, resolve } from "path";
+import { create, ts } from "@custom-elements-manifest/analyzer";
+import globby from "globby";
+import { customElementJsxPlugin as elenaJsxPlugin } from "custom-element-jsx-integration";
+import { elenaDefinePlugin } from "./plugins/cem-define.js";
+import { elenaTagPlugin } from "./plugins/cem-tag.js";
+import { elenaTypeScriptPlugin } from "./plugins/cem-typescript.js";
+import { color } from "./utils/color.js";
+
+/**
+ * Returns the CEM config object for the given Elena config. Useful for advanced
+ * users who still call the CEM CLI with a thin `elena.config.js` wrapper.
+ *
+ * @param {import("./utils/load-config.js").ElenaConfig} [options]
+ * @returns {object} CEM config object
+ */
+export function createCemConfig(options = {}) {
+  const src = options.input ?? "src";
+  const outdir = options.output?.dir ?? "dist";
+  const extraPlugins = options.analyze?.plugins ?? [];
+
+  return {
+    outdir,
+    watch: false,
+    dev: false,
+    globs: [`${src}/**/*.js`],
+    exclude: [`${src}/**/*.ts`, "**/*.test.js", "node_modules"],
+    plugins: [
+      elenaDefinePlugin(),
+      elenaTagPlugin("status"),
+      elenaTagPlugin("displayName"),
+      elenaJsxPlugin({ outdir, fileName: "custom-elements.d.ts" }),
+      elenaTypeScriptPlugin({ outdir }),
+      ...extraPlugins,
+    ],
+  };
+}
+
+/**
+ * Runs the CEM analyzer programmatically using `create()` from
+ * `@custom-elements-manifest/analyzer`, writes the manifest to disk.
+ *
+ * @param {import("./utils/load-config.js").ElenaConfig} config
+ * @param {string} [cwd]
+ * @returns {Promise<void>}
+ */
+export async function runCemAnalyze(config, cwd = process.cwd()) {
+  const src = config.input ?? "src";
+  const outdir = config.output?.dir ?? "dist";
+  const extraPlugins = config.analyze?.plugins ?? [];
+
+  console.log(` `);
+  console.log(color(`░█ [ELENA]: Analyzing the build output...`));
+  console.log(color(`░█ [ELENA]: Generating Custom Elements Manifest...`));
+  console.log(color(`░█ [ELENA]: Generating TypeScript types...`));
+  console.log(` `);
+
+  const globs = await globby(
+    [`${src}/**/*.js`, `!${src}/**/*.ts`, "!**/*.test.js", "!node_modules"],
+    { cwd }
+  );
+
+  const modules = globs.map(glob => {
+    const fullPath = resolve(cwd, glob);
+    const source = readFileSync(fullPath).toString();
+    return ts.createSourceFile(glob, source, ts.ScriptTarget.ES2015, true);
+  });
+
+  const plugins = [
+    elenaDefinePlugin(),
+    elenaTagPlugin("status"),
+    elenaTagPlugin("displayName"),
+    elenaJsxPlugin({ outdir, fileName: "custom-elements.d.ts" }),
+    elenaTypeScriptPlugin({ outdir: join(cwd, outdir) }),
+    ...extraPlugins,
+  ];
+
+  const manifest = create({ modules, plugins, context: { dev: false } });
+
+  const outPath = join(cwd, outdir);
+  if (!existsSync(outPath)) {
+    mkdirSync(outPath, { recursive: true });
+  }
+
+  writeFileSync(join(outPath, "custom-elements.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+}

package/src/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { loadConfig } from "./utils/load-config.js";
+import { runRollupBuild } from "./rollup-build.js";
+import { runCemAnalyze } from "./cem-analyze.js";
+import { color } from "./utils/color.js";
+
+const BANNER = `
+ ██████████ ████
+░░███░░░░░█░░███
+ ░███  █ ░  ░███   ██████  ████████    ██████
+ ░██████    ░███  ███░░███░░███░░███  ░░░░░███
+ ░███░░█    ░███ ░███████  ░███ ░███   ███████
+ ░███ ░   █ ░███ ░███░░░   ░███ ░███  ███░░███
+ ██████████ █████░░██████  ████ █████░░████████
+░░░░░░░░░░ ░░░░░  ░░░░░░  ░░░░ ░░░░░  ░░░░░░░░
+`;
+
+const [, , command = "build"] = process.argv;
+
+async function main() {
+  if (command !== "build") {
+    console.error(`Unknown command: ${command}. Usage: elena [build]`);
+    process.exit(1);
+  }
+
+  console.log(color(BANNER));
+
+  const config = await loadConfig(process.cwd());
+
+  await runRollupBuild(config);
+  await runCemAnalyze(config);
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/src/index.js

@@ -0,0 +1,6 @@
+export { createRollupConfig, runRollupBuild } from "./rollup-build.js";
+export { createCemConfig, runCemAnalyze } from "./cem-analyze.js";
+export { cssBundlePlugin } from "./plugins/css-bundle.js";
+export { elenaDefinePlugin } from "./plugins/cem-define.js";
+export { elenaTagPlugin } from "./plugins/cem-tag.js";
+export { elenaTypeScriptPlugin } from "./plugins/cem-typescript.js";

package/src/plugins/cem-define.js

@@ -0,0 +1,93 @@
+/**
+ * CEM analyzer plugin that reads `tagName` from the options object passed to
+ * `Elena(superClass, { tagName: "...", ... })` and registers the element in the manifest.
+ *
+ * Supports both inline objects and variable references:
+ * - `Elena(HTMLElement, { tagName: "elena-button", ... })`
+ * - `const options = { tagName: "elena-button", ... }; Elena(HTMLElement, options)`
+ *
+ * @returns {import("@custom-elements-manifest/analyzer").Plugin}
+ */
+export function elenaDefinePlugin() {
+  /** @type {Map<string, string>} variable name → tag name */
+  const optionsMap = new Map();
+
+  return {
+    name: "define-element",
+
+    analyzePhase({ ts, node, moduleDoc }) {
+      // Collect variable declarations: const options = { tagName: "...", ... }
+      if (
+        ts.isVariableDeclaration(node) &&
+        node.initializer &&
+        ts.isObjectLiteralExpression(node.initializer)
+      ) {
+        const varName = node.name.getText();
+        const tagNameProp = node.initializer.properties.find(
+          p => ts.isPropertyAssignment(p) && p.name.getText() === "tagName"
+        );
+        if (tagNameProp && ts.isStringLiteral(tagNameProp.initializer)) {
+          optionsMap.set(varName, tagNameProp.initializer.text);
+        }
+        return;
+      }
+
+      if (!ts.isClassDeclaration(node)) {
+        return;
+      }
+
+      const className = node.name?.getText();
+      if (!className) {
+        return;
+      }
+
+      const heritageClause = node.heritageClauses?.[0];
+      if (!heritageClause) {
+        return;
+      }
+
+      for (const type of heritageClause.types) {
+        const expr = type.expression;
+        if (!ts.isCallExpression(expr) || expr.expression.getText() !== "Elena") {
+          continue;
+        }
+
+        const optionsArg = expr.arguments[1];
+        if (!optionsArg) {
+          continue;
+        }
+
+        let tagName;
+
+        if (ts.isObjectLiteralExpression(optionsArg)) {
+          // Inline: Elena(HTMLElement, { tagName: "...", ... })
+          const tagNameProp = optionsArg.properties.find(
+            p => ts.isPropertyAssignment(p) && p.name.getText() === "tagName"
+          );
+          if (tagNameProp && ts.isStringLiteral(tagNameProp.initializer)) {
+            tagName = tagNameProp.initializer.text;
+          }
+        } else if (ts.isIdentifier(optionsArg)) {
+          // Variable reference: Elena(HTMLElement, options)
+          tagName = optionsMap.get(optionsArg.getText());
+        }
+
+        if (!tagName) {
+          continue;
+        }
+
+        const declaration = moduleDoc.declarations?.find(d => d.name === className);
+        if (declaration) {
+          declaration.tagName = tagName;
+        }
+
+        moduleDoc.exports ??= [];
+        moduleDoc.exports.push({
+          kind: "custom-element-definition",
+          name: tagName,
+          declaration: { name: className, module: moduleDoc.path },
+        });
+      }
+    },
+  };
+}

package/src/plugins/cem-tag.js

@@ -0,0 +1,54 @@
+/**
+ * Returns the CEM class declaration and resolved tag name for a class node,
+ * or `undefined` if the node is not a registered custom element.
+ *
+ * @param {Partial<import("@custom-elements-manifest/analyzer").JavaScriptModule>} moduleDoc
+ * @param {import("typescript").ClassDeclaration} node
+ * @returns {{ class: import("@custom-elements-manifest/analyzer").Declaration; tagName: string } | undefined}
+ */
+function getElenaElementDetails(moduleDoc, node) {
+  const declaration = moduleDoc.declarations?.find(d => d.name === node.name?.getText());
+  if (!declaration) {
+    return undefined;
+  }
+
+  const customElement = moduleDoc.exports?.find(
+    e => e.kind === "js" && e.declaration.name === declaration.name
+  );
+
+  if (!customElement) {
+    return undefined;
+  }
+
+  return { class: declaration, tagName: customElement.name };
+}
+
+/**
+ * CEM analyzer plugin that reads a non-standard JSDoc tag from each custom element class
+ * and writes its value onto the CEM class declaration under the same key.
+ *
+ * Used for Elena-specific tags like `@status` and `@displayName`.
+ *
+ * @see https://custom-elements-manifest.open-wc.org/analyzer/plugins/authoring/#example-plugin
+ * @param {string} tagName - The JSDoc tag name to extract (e.g. `"status"`, `"displayName"`).
+ * @returns {import("@custom-elements-manifest/analyzer").Plugin}
+ */
+export function elenaTagPlugin(tagName) {
+  return {
+    name: `${tagName}-tag`,
+
+    analyzePhase({ ts, node, moduleDoc }) {
+      if (!ts.isClassDeclaration(node)) {
+        return;
+      }
+
+      const details = getElenaElementDetails(moduleDoc, node);
+      if (!details) {
+        return;
+      }
+
+      const [tag] = ts.getAllJSDocTags(node, t => t.tagName.getText() === tagName);
+      details.class[tagName] = tag && ts.getTextOfJSDocComment(tag.comment);
+    },
+  };
+}

package/src/plugins/cem-typescript.js

@@ -0,0 +1,56 @@
+import { writeFileSync } from "fs";
+import { join } from "path";
+
+/**
+ * CEM analyzer plugin that generates a per-component `.d.ts` file for each
+ * custom element in the manifest.
+ *
+ * This lets TypeScript resolve sub-path imports like
+ * `@elenajs/components/dist/button.js` without manual declaration files.
+ *
+ * @param {{ outdir?: string }} options
+ * @returns {import("@custom-elements-manifest/analyzer").Plugin}
+ */
+export function elenaTypeScriptPlugin({ outdir = "dist" } = {}) {
+  return {
+    name: "per-component-dts",
+
+    packageLinkPhase({ customElementsManifest }) {
+      for (const mod of customElementsManifest.modules) {
+        const ceDecl = mod.declarations?.find(d => d.tagName);
+        if (!ceDecl) {
+          continue;
+        }
+
+        const fields = (ceDecl.members ?? []).filter(m => m.kind === "field" && !m.static);
+        const events = ceDecl.events ?? [];
+
+        const fieldLines = fields.map(f => {
+          const lines = [];
+          if (f.description) {
+            lines.push(`  /** ${f.description} */`);
+          }
+          lines.push(`  ${f.name}?: ${f.type?.text ?? "string"};`);
+          return lines.join("\n");
+        });
+
+        const eventLines = events.map(e => {
+          const lines = [];
+          if (e.description) {
+            lines.push(`  /** ${e.description} */`);
+          }
+          lines.push(`  on${e.name}?: (e: CustomEvent<never>) => void;`);
+          return lines.join("\n");
+        });
+
+        const members = [...fieldLines, ...eventLines].join("\n");
+        const body = members ? `\n${members}\n` : "";
+        const propsType = `${ceDecl.name}Props`;
+        const content = `export type { ${propsType} } from './custom-elements.js';\n\ndeclare class ${ceDecl.name} extends HTMLElement {${body}}\n\nexport default ${ceDecl.name};\n`;
+
+        const fileName = mod.path.split("/").pop().replace(".js", ".d.ts");
+        writeFileSync(join(outdir, fileName), content);
+      }
+    },
+  };
+}

package/src/plugins/css-bundle.js

@@ -0,0 +1,37 @@
+import { readFileSync, readdirSync } from "fs";
+import { color } from "../utils/color.js";
+
+/**
+ * Rollup plugin that concatenates and minifies all CSS files from `srcDir` into a
+ * single bundle asset emitted to the output directory.
+ *
+ * @param {string} srcDir - Source directory to scan for `.css` files (e.g. `"src"`).
+ * @param {string} fileName - Output filename relative to the output dir (e.g. `"bundle.css"`).
+ * @returns {import("rollup").Plugin}
+ */
+export function cssBundlePlugin(srcDir, fileName) {
+  return {
+    name: "css-bundle",
+    generateBundle() {
+      const cssFiles = readdirSync(srcDir, { recursive: true })
+        .filter(f => f.endsWith(".css"))
+        .map(f => `${srcDir}/${f}`);
+
+      const source = cssFiles
+        .map(f => readFileSync(f, "utf8"))
+        .join("\n")
+        // Strip block comments
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        // Collapse whitespace runs into a single space
+        .replace(/\s+/g, " ")
+        // Remove spaces around structural characters
+        .replace(/\s*([{}:;,>~+])\s*/g, "$1")
+        // Drop trailing semicolons before closing brace
+        .replace(/;}/g, "}")
+        .trim();
+
+      this.emitFile({ type: "asset", fileName, source });
+      console.log(color(`░█ [ELENA]: Generating and minifying CSS bundle...`));
+    },
+  };
+}

package/src/rollup-build.js

@@ -0,0 +1,177 @@
+import { readdirSync } from "fs";
+import { rollup } from "rollup";
+import resolve from "@rollup/plugin-node-resolve";
+import terser from "@rollup/plugin-terser";
+import copy from "rollup-plugin-copy";
+import minifyHtmlLiterals from "rollup-plugin-minify-html-literals-v3";
+import summary from "rollup-plugin-summary";
+import { cssBundlePlugin } from "./plugins/css-bundle.js";
+import { color } from "./utils/color.js";
+
+const TREESHAKE = {
+  moduleSideEffects: false,
+  propertyReadSideEffects: false,
+};
+
+function onwarn(warning, warn) {
+  if (warning.code === "UNUSED_EXTERNAL_IMPORT") {
+    return;
+  }
+  warn(warning);
+}
+
+/**
+ * Builds the plugin list for a single Rollup build target.
+ *
+ * @param {{ src: string; outdir: string; hasSummary: boolean; includeCssBundle: boolean; extraPlugins?: import("rollup").Plugin[] }} opts
+ * @returns {import("rollup").Plugin[]}
+ */
+function buildPlugins({ src, outdir, hasSummary, includeCssBundle, extraPlugins = [] }) {
+  const plugins = [
+    resolve({ extensions: [".js", ".css"] }),
+    minifyHtmlLiterals({
+      options: {
+        // Elena components use this.template`...` rather than html`...`
+        shouldMinify: template => template.parts.some(({ text }) => /<[a-z]/i.test(text)),
+      },
+    }),
+    terser({
+      ecma: 2020,
+      module: true,
+    }),
+    copy({
+      targets: [{ src: `${src}/**/*.css`, dest: outdir }],
+      flatten: true,
+    }),
+  ];
+
+  if (includeCssBundle) {
+    plugins.push(cssBundlePlugin(src, "bundle.css"));
+  }
+
+  // User-provided plugins are appended after built-ins, before summary.
+  plugins.push(...extraPlugins);
+
+  if (hasSummary) {
+    plugins.push(summary({ showBrotliSize: true, showGzippedSize: true }));
+  }
+
+  return plugins;
+}
+
+/**
+ * Returns the Rollup config array for the given Elena config. Useful for advanced
+ * users who want to call `rollup -c` with a thin wrapper config file.
+ *
+ * @param {import("./utils/load-config.js").ElenaConfig} [options]
+ * @returns {import("rollup").RollupOptions[]}
+ */
+export function createRollupConfig(options = {}) {
+  const src = options.input ?? "src";
+  const outdir = options.output?.dir ?? "dist";
+  const format = options.output?.format ?? "esm";
+  const sourcemap = options.output?.sourcemap ?? true;
+  const bundle = options.bundle !== undefined ? options.bundle : "src/index.js";
+  const extraPlugins = options.plugins ?? [];
+
+  const entries = readdirSync(src, { recursive: true })
+    .filter(f => f.endsWith(".js"))
+    .map(f => `${src}/${f}`);
+
+  const configs = [
+    {
+      input: entries,
+      plugins: buildPlugins({
+        src,
+        outdir,
+        hasSummary: false,
+        includeCssBundle: true,
+        extraPlugins,
+      }),
+      output: { format, sourcemap, dir: outdir },
+      preserveEntrySignatures: "strict",
+      treeshake: TREESHAKE,
+      onwarn,
+    },
+  ];
+
+  if (bundle) {
+    configs.push({
+      input: bundle,
+      plugins: buildPlugins({
+        src,
+        outdir,
+        hasSummary: true,
+        includeCssBundle: false,
+        extraPlugins,
+      }),
+      output: { format, sourcemap, file: `${outdir}/bundle.js` },
+      preserveEntrySignatures: "strict",
+      treeshake: TREESHAKE,
+      onwarn,
+    });
+  }
+
+  return configs;
+}
+
+/**
+ * Runs both Rollup build targets programmatically using the Rollup Node.js API.
+ *
+ * Note: the `output` key inside `RollupOptions` is ignored by the `rollup()` API —
+ * output options must be passed separately to `build.write()`.
+ *
+ * @param {import("./utils/load-config.js").ElenaConfig} config
+ * @returns {Promise<void>}
+ */
+export async function runRollupBuild(config) {
+  const src = config.input ?? "src";
+  const outdir = config.output?.dir ?? "dist";
+  const format = config.output?.format ?? "esm";
+  const sourcemap = config.output?.sourcemap ?? true;
+  const bundle = config.bundle !== undefined ? config.bundle : "src/index.js";
+  const extraPlugins = config.plugins ?? [];
+
+  const entries = readdirSync(src, { recursive: true })
+    .filter(f => f.endsWith(".js"))
+    .map(f => `${src}/${f}`);
+
+  // Build 1: individual modules + CSS bundle
+  console.log(color(`░█ [ELENA]: Building Progressive Web Components...`));
+  console.log(` `);
+  for (const entry of entries) {
+    console.log(color(`░█ [ELENA]: Generating and minifying ${entry}...`));
+  }
+
+  const build1 = await rollup({
+    input: entries,
+    plugins: buildPlugins({ src, outdir, hasSummary: false, includeCssBundle: true, extraPlugins }),
+    preserveEntrySignatures: "strict",
+    treeshake: TREESHAKE,
+    onwarn,
+  });
+  await build1.write({ format, sourcemap, dir: outdir });
+  await build1.close();
+
+  // Build 2: single-file JS bundle (optional)
+  if (bundle) {
+    console.log(color(`░█ [ELENA]: Generating and minifying JS bundle...`));
+    console.log(` `);
+
+    const build2 = await rollup({
+      input: bundle,
+      plugins: buildPlugins({
+        src,
+        outdir,
+        hasSummary: true,
+        includeCssBundle: false,
+        extraPlugins,
+      }),
+      preserveEntrySignatures: "strict",
+      treeshake: TREESHAKE,
+      onwarn,
+    });
+    await build2.write({ format, sourcemap, file: `${outdir}/bundle.js` });
+    await build2.close();
+  }
+}

package/src/utils/color.js

@@ -0,0 +1,2 @@
+/** Applies the Elena brand color (#f19c77) to a string using ANSI true color escape codes. */
+export const color = str => `\x1b[38;2;241;156;119m${str}\x1b[0m`;

package/src/utils/load-config.js

@@ -0,0 +1,57 @@
+import { pathToFileURL } from "url";
+import { resolve } from "path";
+import { existsSync } from "fs";
+
+/**
+ * @typedef {object} ElenaOutputConfig
+ * @property {string} [dir]        Output directory for individual modules, CSS, and CEM artifacts.
+ * @property {string} [format]     Rollup output format (default: `"esm"`).
+ * @property {boolean} [sourcemap] Whether to emit sourcemaps (default: `true`).
+ */
+
+/**
+ * @typedef {object} ElenaAnalyzeConfig
+ * @property {import("@custom-elements-manifest/analyzer").Plugin[]} [plugins]
+ *   Additional CEM analyzer plugins appended after Elena's built-in set.
+ */
+
+/**
+ * @typedef {object} ElenaConfig
+ * @property {string}             [input]   Source directory scanned for .js and .css files.
+ * @property {ElenaOutputConfig}  [output]  Rollup output options.
+ * @property {string|false}       [bundle]  Entry for the single-file bundle; `false` to disable.
+ * @property {import("rollup").Plugin[]} [plugins] Additional Rollup plugins appended after built-ins.
+ * @property {ElenaAnalyzeConfig} [analyze] CEM analysis options.
+ */
+
+/** @type {Required<ElenaConfig>} */
+const DEFAULTS = {
+  input: "src",
+  output: { dir: "dist", format: "esm", sourcemap: true },
+  bundle: "src/index.js",
+  plugins: [],
+  analyze: { plugins: [] },
+};
+
+/**
+ * Loads the Elena config from `elena.config.mjs` or `elena.config.js` in `cwd`,
+ * falling back to defaults if no config file is found.
+ *
+ * @param {string} [cwd]
+ * @returns {Promise<Required<ElenaConfig>>}
+ */
+export async function loadConfig(cwd = process.cwd()) {
+  for (const name of ["elena.config.mjs", "elena.config.js"]) {
+    const configPath = resolve(cwd, name);
+    if (!existsSync(configPath)) continue;
+    const mod = await import(pathToFileURL(configPath).href);
+    const user = mod.default ?? {};
+    return {
+      ...DEFAULTS,
+      ...user,
+      output: { ...DEFAULTS.output, ...user.output },
+      analyze: { ...DEFAULTS.analyze, ...user.analyze },
+    };
+  }
+  return { ...DEFAULTS };
+}