feat: build through cli

ROADMAP.md

···
     - Web
     - Tauri
     - Wails
+
+## Docs
+
+- [ ] Document `charge()` bootstrap flow and declarative state/computed attributes (`data-volt-state`, `data-volt-computed:*`).
+- [ ] Add async effect guide covering abort signals, debounce/throttle, retries, and `onError` handling.
+- [ ] Write lifecycle instrumentation docs for `registerGlobalHook`, `registerElementHook`, `getElementBindings`, and plugin `context.lifecycle` callbacks.
+- [ ] Explain `data-volt-bind:*` semantics, especially boolean attribute handling and dependency subscription behavior.
+- [ ] Refresh README and overview content to use `data-volt-*` naming and reflect the current module layout.

cli/eslint.config.js

···
                 tsconfigRootDir: import.meta.dirname,
             },
         },
-        ignores: ["eslint.config.js"],
+        ignores: ["eslint.config.js", "tsdown.config.ts"],
         rules: {
             "no-undef": "off",
             "@typescript-eslint/no-unused-vars": [

cli/src/commands/build.ts

···
+import { echo } from "$console/echo.js";
+import { buildLibrary, copyBuildArtifacts, findBuildArtifacts } from "$utils/build.js";
+import path from "node:path";
+
+export type BuildCommandOptions = { minify?: boolean; css?: boolean };
+
+/**
+ * Build command implementation.
+ *
+ * Builds the Volt.js library and copies the build artifacts to the specified
+ * output directory. Supports optional minification and CSS inclusion.
+ */
+export async function buildCommand(outDir: string = ".", options: BuildCommandOptions = {}): Promise<void> {
+  const minify = options.minify !== false;
+  const includeCss = options.css !== false;
+
+  const resolvedOutDir = path.resolve(process.cwd(), outDir);
+
+  echo.title("\nBuilding Volt.js library...\n");
+  echo.info("Building library...");
+  await buildLibrary();
+
+  echo.info("Finding build artifacts...");
+  const artifacts = await findBuildArtifacts();
+
+  echo.info(`Copying to ${resolvedOutDir}...`);
+  await copyBuildArtifacts(artifacts, { outDir: resolvedOutDir, minify, includeCss });
+
+  echo.success("\nBuild completed successfully!\n");
+
+  if (minify) {
+    echo.info(`Output: ${outDir}${outDir.endsWith("/") ? "" : "/"}volt.min.js`);
+    if (includeCss) {
+      echo.info(`        ${outDir}${outDir.endsWith("/") ? "" : "/"}volt.min.css\n`);
+    }
+  } else {
+    echo.info(`Output: ${outDir}${outDir.endsWith("/") ? "" : "/"}volt.js`);
+    if (includeCss) {
+      echo.info(`        ${outDir}${outDir.endsWith("/") ? "" : "/"}volt.css\n`);
+    }
+  }
+}

cli/src/commands/css-docs.ts

···
+import { echo } from "$console/echo.js";
+import { getDocsPath, getLibSrcPath } from "$utils/paths.js";
+import { trackVersion } from "$versioning/tracker.js";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { echo } from "../console/echo.js";
-import { trackVersion } from "../versioning/tracker.js";
-import { getLibSrcPath, getDocsPath } from "../utils/paths.js";
 
 type CSSComment = { selector: string; comment: string };
 
···
       continue;
     }
 
-    lines.push(`### \`${comment.selector}\``, "");
-    lines.push(comment.comment, "");
+    lines.push(`### \`${comment.selector}\``, "", comment.comment, "");
   }
 
   return lines.join("\n");

cli/src/commands/docs.ts

···
+import { echo } from "$console/echo.js";
+import { getDocsPath, getLibSrcPath } from "$utils/paths.js";
+import { trackVersion } from "$versioning/tracker.js";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import ts from "typescript";
-import { echo } from "../console/echo.js";
-import { trackVersion } from "../versioning/tracker.js";
-import { getLibSrcPath, getDocsPath } from "../utils/paths.js";
 
 type Member = { name: string; type: string; docs?: string };
 
···
     return { description: "", examples: [] };
   }
 
-  const comments = ranges.map((range) => fullText.substring(range.pos, range.end));
+  const comments = ranges.map((range) => fullText.slice(range.pos, range.end));
   const jsdocComments = comments.filter((c) => c.trim().startsWith("/**"));
 
   if (jsdocComments.length === 0) {
···
 function extractFnSig(node: ts.FunctionDeclaration, sourceFile: ts.SourceFile): string {
   const start = node.getStart(sourceFile);
   const end = node.body ? node.body.getStart(sourceFile) : node.getEnd();
-  return sourceFile.text.substring(start, end).trim().replaceAll(/\s+/g, " ");
+  return sourceFile.text.slice(start, end).trim().replaceAll(/\s+/g, " ");
 }
 
 /**

cli/src/commands/example.ts

···
-import { existsSync } from "node:fs";
+import { echo } from "$console/echo.js";
+import { type BuildArtifacts, buildLibrary, copyBuildArtifacts, findBuildArtifacts } from "$utils/build.js";
+import { getExamplesPath } from "$utils/paths.js";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { minify as terserMinify } from "terser";
-import { echo } from "../console/echo.js";
-import { findMonorepoRoot, getLibPath, getExamplesPath } from "../utils/paths.js";
 
-type BuildArtifacts = { jsPath: string; cssPath: string };
-
-/**
- * Build the library using pnpm workspace commands
- */
-async function buildLibrary(): Promise<void> {
-  const { execSync } = await import("node:child_process");
-  const monorepoRoot = await findMonorepoRoot();
-
-  try {
-    execSync("pnpm --filter volt build:lib", { cwd: monorepoRoot, stdio: "inherit" });
-  } catch {
-    throw new Error("Library build failed. Make sure Vite is configured correctly.");
-  }
-}
-
-/**
- * Find the library build artifacts in dist/
- */
-async function findBuildArtifacts(): Promise<BuildArtifacts> {
-  const libPath = await getLibPath();
-  const distDir = path.join(libPath, "dist");
-  const jsPath = path.join(distDir, "volt.js");
-  const cssPath = path.join(libPath, "src", "styles", "base.css");
-
-  if (!existsSync(jsPath)) {
-    throw new Error(`Library JS not found at ${jsPath}. Build may have failed.`);
-  }
-
-  if (!existsSync(cssPath)) {
-    throw new Error(`Base CSS not found at ${cssPath}.`);
-  }
-
-  return { jsPath, cssPath };
-}
-
-async function minifyJS(code: string): Promise<string> {
-  const result = await terserMinify(code, {
-    compress: {
-      dead_code: true,
-      drop_debugger: true,
-      conditionals: true,
-      evaluate: true,
-      booleans: true,
-      loops: true,
-      unused: true,
-      hoist_funs: true,
-      keep_fargs: false,
-      hoist_vars: false,
-      if_return: true,
-      join_vars: true,
-      side_effects: true,
-    },
-    mangle: { toplevel: true },
-    format: { comments: false },
-  });
-
-  if (!result.code) {
-    throw new Error("Minification failed - no output generated");
-  }
-
-  return result.code;
-}
-
-// TODO: use terser
-function minifyCSS(code: string): string {
-  return code.replaceAll(/\/\*[\s\S]*?\*\//g, "").replaceAll(/\s+/g, " ").replaceAll(/\s*([{}:;,])\s*/g, "$1").trim();
-}
+export type BuildMode = "markup" | "programmatic";
 
 /**
  * Create minified build artifacts in examples/dist/
  */
 async function createMinifiedArtifacts(artifacts: BuildArtifacts, examplesDir: string): Promise<void> {
   const examplesDistDir = path.join(examplesDir, "dist");
-  await mkdir(examplesDistDir, { recursive: true });
-
-  const jsContent = await readFile(artifacts.jsPath, "utf8");
-  const cssContent = await readFile(artifacts.cssPath, "utf8");
-
-  echo.info("  Minifying JavaScript...");
-  const minifiedJS = await minifyJS(jsContent);
-
-  echo.info("  Minifying CSS...");
-  const minifiedCSS = minifyCSS(cssContent);
-
-  const voltJSPath = path.join(examplesDistDir, "volt.min.js");
-  const voltCSSPath = path.join(examplesDistDir, "volt.min.css");
-
-  await writeFile(voltJSPath, minifiedJS, "utf8");
-  await writeFile(voltCSSPath, minifiedCSS, "utf8");
-
-  echo.ok(`  Created: examples/dist/volt.min.js (${Math.round(minifiedJS.length / 1024)} KB)`);
-  echo.ok(`  Created: examples/dist/volt.min.css (${Math.round(minifiedCSS.length / 1024)} KB)`);
+  await copyBuildArtifacts(artifacts, { outDir: examplesDistDir, minify: true, includeCss: true });
 }
 
-function generateHTML(name: string, mode: "markup" | "programmatic", standalone: boolean): string {
+function generateHTML(name: string, mode: BuildMode, standalone: boolean): string {
   const cssPath = standalone ? "volt.min.css" : "../dist/volt.min.css";
   const jsPath = standalone ? "volt.min.js" : "../dist/volt.min.js";
 
···
 `;
 }
 
-/**
- * Generate app.js template
- */
 function generateAppJS(): string {
   return `// Import volt.js functions if needed
 // import { mount, signal, computed, effect } from '../dist/volt.min.js';
···
 async function createExampleFiles(
   exampleDir: string,
   name: string,
-  mode: "markup" | "programmatic",
+  mode: BuildMode,
   standalone: boolean,
 ): Promise<void> {
   await mkdir(exampleDir, { recursive: true });
···
  */
 export async function exampleCommand(
   name: string,
-  options: { mode?: "markup" | "programmatic"; standalone?: boolean } = {},
+  options: { mode?: BuildMode; standalone?: boolean } = {},
 ): Promise<void> {
   const mode = options.mode || "programmatic";
   const standalone = options.standalone || false;

cli/src/commands/stats.ts

···
+import { echo } from "$console/echo.js";
+import { findMonorepoRoot, getLibSrcPath, getLibTestPath } from "$utils/paths.js";
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { echo } from "../console/echo.js";
-import { getLibSrcPath, getLibTestPath, findMonorepoRoot } from "../utils/paths.js";
 
 type FileStats = { path: string; lines: number; totalLines: number };
 type DirectoryStats = { totalLines: number; codeLines: number; files: FileStats[] };
···
 export async function statsCommand(includeFull: boolean): Promise<void> {
   const monorepoRoot = await findMonorepoRoot();
   const srcDir = await getLibSrcPath();
+  const srcStats = await collectStats(srcDir, monorepoRoot);
 
   echo.title("\nVolt.js Code Statistics\n");
-
-  const srcStats = await collectStats(srcDir, monorepoRoot);
 
   echo.label("Source Code (src/):");
   echo.text(`  Files: ${srcStats.files.length}`);

cli/src/index.ts

···
 /* eslint-disable unicorn/no-process-exit */
+import { buildCommand } from "$commands/build.js";
+import { cssDocsCommand } from "$commands/css-docs.js";
+import { docsCommand } from "$commands/docs.js";
+import { type BuildMode, exampleCommand } from "$commands/example.js";
+import { statsCommand } from "$commands/stats.js";
+import { echo } from "$console/echo.js";
 import { Command } from "commander";
-import { cssDocsCommand } from "./commands/css-docs.js";
-import { docsCommand } from "./commands/docs.js";
-import { exampleCommand } from "./commands/example.js";
-import { statsCommand } from "./commands/stats.js";
-import { echo } from "./console/echo.js";
 
 const program = new Command();
 
···
   }
 });
 
+program.command("build [outDir]").description("Build the library and output to a directory").option(
+  "--no-minify",
+  "Skip minification (outputs volt.js instead of volt.min.js)",
+).option("--no-css", "Skip CSS output").action(
+  async (outDir: string | undefined, options: { minify: boolean; css: boolean }) => {
+    try {
+      await buildCommand(outDir, options);
+    } catch (error) {
+      echo.err("Error building library:", error);
+      process.exit(1);
+    }
+  },
+);
+
 program.command("css-docs").description("Generate CSS documentation from base.css comments and variables").action(
   async () => {
     try {
···
   "Example mode: markup (declarative) or programmatic (imperative)",
   "programmatic",
 ).option("--standalone", "Create standalone example with local copies of volt.min.js and volt.min.css", false).action(
-  async (name: string, options: { mode: "markup" | "programmatic"; standalone: boolean }) => {
+  async (name: string, options: { mode: BuildMode; standalone: boolean }) => {
     try {
       await exampleCommand(name, options);
     } catch (error) {

cli/src/utils/build.ts

···
+import { echo } from "$console/echo.js";
+import { findMonorepoRoot, getLibPath } from "$utils/paths.js";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { minify as terserMinify } from "terser";
+
+export type BuildArtifacts = { jsPath: string; cssPath: string };
+
+export type BuildOptions = { outDir: string; minify?: boolean; includeCss?: boolean };
+
+/**
+ * Build the library using pnpm workspace commands.
+ *
+ * Runs `pnpm --filter volt build:lib` in the monorepo root to compile the Volt.js library into lib/dist/.
+ */
+export async function buildLibrary(): Promise<void> {
+  const { execSync } = await import("node:child_process");
+  const monorepoRoot = await findMonorepoRoot();
+
+  try {
+    execSync("pnpm --filter volt build:lib", { cwd: monorepoRoot, stdio: "inherit" });
+  } catch {
+    throw new Error("Library build failed. Make sure Vite is configured correctly.");
+  }
+}
+
+/**
+ * Find the library build artifacts in lib/dist/.
+ *
+ * Locates the compiled JavaScript and base CSS files after a successful build.
+ */
+export async function findBuildArtifacts(): Promise<BuildArtifacts> {
+  const libPath = await getLibPath();
+  const distDir = path.join(libPath, "dist");
+  const jsPath = path.join(distDir, "volt.js");
+  const cssPath = path.join(libPath, "src", "styles", "base.css");
+
+  if (!existsSync(jsPath)) {
+    throw new Error(`Library JS not found at ${jsPath}. Build may have failed.`);
+  }
+
+  if (!existsSync(cssPath)) {
+    throw new Error(`Base CSS not found at ${cssPath}.`);
+  }
+
+  return { jsPath, cssPath };
+}
+
+/**
+ * Minify JavaScript code using Terser.
+ *
+ * Applies aggressive compression and mangling to reduce bundle size.
+ */
+export async function minifyJS(code: string): Promise<string> {
+  const result = await terserMinify(code, {
+    compress: {
+      dead_code: true,
+      drop_debugger: true,
+      conditionals: true,
+      evaluate: true,
+      booleans: true,
+      loops: true,
+      unused: true,
+      hoist_funs: true,
+      keep_fargs: false,
+      hoist_vars: false,
+      if_return: true,
+      join_vars: true,
+      side_effects: true,
+    },
+    mangle: { toplevel: true },
+    format: { comments: false },
+  });
+
+  if (!result.code) {
+    throw new Error("Minification failed - no output generated");
+  }
+
+  return result.code;
+}
+
+/**
+ * Minify CSS code using regex-based compression.
+ *
+ * Removes comments, normalizes whitespace, and strips spacing around CSS syntax characters.
+ */
+export function minifyCSS(code: string): string {
+  return code.replaceAll(/\/\*[\s\S]*?\*\//g, "").replaceAll(/\s+/g, " ").replaceAll(/\s*([{}:;,])\s*/g, "$1").trim();
+}
+
+/**
+ * Copy build artifacts to the specified output directory.
+ *
+ * Reads the built JavaScript and CSS files, optionally minifies them, and writes them to the target directory.
+ * Creates the directory if needed.
+ * The output file naming depends on whether minification is enabled.
+ */
+export async function copyBuildArtifacts(artifacts: BuildArtifacts, options: BuildOptions): Promise<void> {
+  const { outDir, minify = true, includeCss = true } = options;
+
+  await mkdir(outDir, { recursive: true });
+
+  const jsContent = await readFile(artifacts.jsPath, "utf8");
+  const jsFilename = minify ? "volt.min.js" : "volt.js";
+  let outputJS = jsContent;
+
+  if (minify) {
+    echo.info("  Minifying JavaScript...");
+    outputJS = await minifyJS(jsContent);
+  }
+
+  const jsOutputPath = path.join(outDir, jsFilename);
+  await writeFile(jsOutputPath, outputJS, "utf8");
+  const jsSize = Math.round(outputJS.length / 1024);
+  echo.ok(`  Created: ${jsFilename} (${jsSize} KB)`);
+
+  if (includeCss) {
+    const cssContent = await readFile(artifacts.cssPath, "utf8");
+    const cssFilename = minify ? "volt.min.css" : "volt.css";
+    let outputCSS = cssContent;
+
+    if (minify) {
+      echo.info("  Minifying CSS...");
+      outputCSS = minifyCSS(cssContent);
+    }
+
+    const cssOutputPath = path.join(outDir, cssFilename);
+    await writeFile(cssOutputPath, outputCSS, "utf8");
+    const cssSize = Math.round(outputCSS.length / 1024);
+    echo.ok(`  Created: ${cssFilename} (${cssSize} KB)`);
+  }
+}

cli/tsconfig.json

···
     "esModuleInterop": true,
     "isolatedModules": true,
     "verbatimModuleSyntax": true,
-    "skipLibCheck": true
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "paths": {
+      "$commands/*": ["./src/commands/*"],
+      "$utils/*": ["./src/utils/*"],
+      "$versioning/*": ["./src/versioning/*"],
+      "$console/*": ["./src/console/*"]
+    }
   },
   "include": ["src"]
 }

cli/tsdown.config.ts

···
   clean: true,
   shims: true,
   banner: { js: "#!/usr/bin/env node" },
+  alias: {
+    $commands: "./src/commands",
+    $utils: "./src/utils",
+    $versioning: "./src/versioning",
+    $console: "./src/console",
+  },
 });

dprint.json

···
 {
   "typescript": { "preferSingleLine": true, "jsx.bracketPosition": "sameLine" },
   "json": { "preferSingleLine": true, "lineWidth": 121, "indentWidth": 2 },
-  "markup": { "preferAttrsSingleLine": true, "printWidth": 121, "styleIndent": true, "scriptIndent": true },
+  "markup": {
+    "preferAttrsSingleLine": true,
+    "printWidth": 121,
+    "styleIndent": true,
+    "scriptIndent": true,
+    "closingBracketSameLine": true
+  },
   "excludes": ["**/node_modules"],
   "plugins": [
     "https://plugins.dprint.dev/typescript-0.95.8.wasm",