@vojtaholik/static-kit-cli 2.0.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@vojtaholik/static-kit-cli",
+  "version": "2.0.0",
+  "type": "module",
+  "bin": {
+    "static-kit": "./src/cli.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vojtaholik/module-kit",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@vojtaholik/static-kit-core": "^2.0.0",
+    "lightningcss": "^1.28.2",
+    "browserslist": "^4.24.4"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env bun
+/**
+ * Static Block Kit CLI
+ *
+ * Commands:
+ *   dev    - Start development server
+ *   build  - Build static site for production
+ *   gen    - Compile block templates
+ *   sprite - Compile SVGs into spritesheet
+ */
+
+const command = process.argv[2];
+
+switch (command) {
+  case "dev":
+    await import("./commands/dev.ts");
+    break;
+  case "build":
+    await import("./commands/build.ts");
+    break;
+  case "gen":
+    await import("./commands/gen.ts");
+    break;
+  case "sprite":
+    await import("./commands/sprite.ts");
+    break;
+  case "--help":
+  case "-h":
+  case undefined:
+    console.log(`
+Static Block Kit CLI
+
+Usage:
+  static-block-kit <command>
+
+Commands:
+  dev     Start development server with hot reload
+  build   Build static site for production
+  gen     Compile block templates to render functions
+  sprite  Compile SVGs from svg/ into spritesheet
+
+Options:
+  --help, -h  Show this help message
+`);
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    console.error("Run 'static-block-kit --help' for available commands");
+    process.exit(1);
+}

package/src/commands/build.ts

@@ -0,0 +1,144 @@
+#!/usr/bin/env bun
+/**
+ * Static Kit - Build Pipeline
+ *
+ * 1. Run template compiler (gen-blocks)
+ * 2. Load and validate all page configs
+ * 3. Render each page to HTML (no dev overlay)
+ * 4. Copy publicDir to dist/{publicPath}/ (1:1 structure)
+ * 5. Write HTML files to dist/ (flat structure)
+ */
+
+import { mkdir, rm, cp } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { Glob } from "bun";
+import {
+  renderPage,
+  compileBlockTemplates,
+  type PageConfig,
+} from "@vojtaholik/static-kit-core";
+import { loadConfig, resolvePath } from "../config-loader.ts";
+import { processCSS } from "../css-processor.ts";
+import { compileSpritesheet } from "../sprite-compiler.ts";
+
+const cwd = process.cwd();
+const config = await loadConfig(cwd);
+
+const blocksDir = resolvePath(config, "blocksDir", cwd);
+const pagesDir = resolvePath(config, "pagesDir", cwd);
+const publicDir = resolvePath(config, "publicDir", cwd);
+const outDir = resolvePath(config, "outDir", cwd);
+
+// Strip leading slash from publicPath for filesystem operations
+const publicPathDir = config.publicPath.replace(/^\//, "");
+
+async function build() {
+  console.log("🔨 Building static site...\n");
+
+  // Clean dist directory
+  console.log("Cleaning output directory...");
+  await rm(outDir, { recursive: true, force: true });
+  await mkdir(outDir, { recursive: true });
+
+  // Step 1: Compile templates
+  console.log("\n📝 Compiling block templates...");
+  await compileBlockTemplates({
+    blocksDir,
+    genDir: join(blocksDir, "gen"),
+  });
+
+  // Step 1.5: Compile SVG spritesheet
+  console.log("\n🎨 Compiling SVG spritesheet...");
+  try {
+    const { count } = await compileSpritesheet({ publicDir });
+    console.log(`  ✓ ${count} SVGs compiled`);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw err;
+    }
+    console.log("  ℹ No svg/ directory found, skipping");
+  }
+
+  // Step 2: Import fresh modules (after template compilation)
+  const blocksModule = await import(join(blocksDir, "index.ts"));
+  const pagesModule = await import(join(pagesDir, "index.ts"));
+
+  // Register blocks
+  if (typeof blocksModule.registerAllBlocks === "function") {
+    blocksModule.registerAllBlocks();
+  }
+
+  const pages: PageConfig[] = pagesModule.pages;
+
+  // Step 3: Render all pages (flat structure in dist/)
+  console.log("\n📄 Rendering pages...");
+  for (const page of pages) {
+    const html = await renderPage(page, {
+      templateDir: pagesDir,
+      isDev: false,
+      assetBase: "/",
+    });
+
+    // Flat output: /about -> dist/about.html, / -> dist/index.html
+    const fileName =
+      page.path === "/" ? "index.html" : `${page.path.replace(/^\//, "")}.html`;
+    const outPath = join(outDir, fileName);
+
+    // Write HTML
+    await Bun.write(outPath, html);
+    console.log(`  ✓ ${page.path} → ${outPath}`);
+  }
+
+  // Step 4: Copy publicDir to dist/public/ (1:1 mirrored structure)
+  console.log("\n📦 Copying public assets...");
+  const outPublicDir = join(outDir, publicPathDir);
+
+  const publicGlob = new Glob("**/*");
+  for await (const file of publicGlob.scan(publicDir)) {
+    const srcFile = join(publicDir, file);
+    const destFile = join(outPublicDir, file);
+
+    const bunFile = Bun.file(srcFile);
+    if (await bunFile.exists()) {
+      await mkdir(dirname(destFile), { recursive: true });
+
+      // Process CSS files through lightningcss
+      if (file.endsWith(".css")) {
+        const cssBytes = new Uint8Array(await bunFile.arrayBuffer());
+        const result = processCSS({
+          filename: srcFile,
+          code: cssBytes,
+          minify: true,
+        });
+        await Bun.write(destFile, result.code);
+        console.log(`  ✓ ${config.publicPath}/${file} (minified)`);
+      } else {
+        await Bun.write(destFile, await bunFile.arrayBuffer());
+        console.log(`  ✓ ${config.publicPath}/${file}`);
+      }
+    }
+  }
+
+  // Done
+  console.log("\n✅ Build complete!");
+  console.log(`   Output: ${outDir}/`);
+
+  // List output files
+  console.log("\n   Files:");
+  const glob = new Glob("**/*");
+  for await (const file of glob.scan(outDir)) {
+    const stat = await Bun.file(join(outDir, file)).size;
+    console.log(`   - ${file} (${formatBytes(stat)})`);
+  }
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+build().catch((err) => {
+  console.error("Build failed:", err);
+  process.exit(1);
+});

package/src/commands/dev.ts

@@ -0,0 +1,401 @@
+#!/usr/bin/env bun
+/**
+ * Static Kit - Development Server
+ *
+ * Bun.serve() based dev server with:
+ * - Page routes (rendered HTML with dev overlay)
+ * - Static asset serving
+ * - Dev API endpoints
+ * - Hot reload via SSE
+ */
+
+import { watch } from "node:fs";
+import { join } from "node:path";
+import {
+  decodeSchemaAddress,
+  blockRegistry,
+  renderPage,
+  compileBlockTemplates,
+  type PageConfig,
+} from "@vojtaholik/static-kit-core";
+import { loadConfig, resolvePath } from "../config-loader.ts";
+import { processCSS } from "../css-processor.ts";
+import { compileSpritesheet } from "../sprite-compiler.ts";
+
+const cwd = process.cwd();
+const config = await loadConfig(cwd);
+
+const blocksDir = resolvePath(config, "blocksDir", cwd);
+const pagesDir = resolvePath(config, "pagesDir", cwd);
+const publicDir = resolvePath(config, "publicDir", cwd);
+const svgDir = join(publicDir, "svg");
+
+// Compile block templates before importing blocks (gen/ may not exist yet)
+console.log("🔨 Compiling block templates...");
+await compileBlockTemplates({
+  blocksDir,
+  genDir: join(blocksDir, "gen"),
+});
+
+// Compile SVG spritesheet if svg/ directory exists
+try {
+  console.log("🎨 Compiling SVG spritesheet...");
+  const { count } = await compileSpritesheet({ publicDir });
+  if (count === 0) {
+    console.log("   (no SVGs found in svg/)");
+  }
+} catch (err) {
+  if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+    console.warn("   ⚠ Sprite compilation failed:", err);
+  }
+  // svg/ directory doesn't exist, skip silently
+}
+
+// Dynamically import site's blocks and pages
+const blocksModule = await import(join(blocksDir, "index.ts"));
+const pagesModule = await import(join(pagesDir, "index.ts"));
+
+// Register all blocks at startup
+if (typeof blocksModule.registerAllBlocks === "function") {
+  blocksModule.registerAllBlocks();
+}
+
+const pages: PageConfig[] = pagesModule.pages;
+const getPageByPath = pagesModule.getPageByPath as (
+  path: string
+) => PageConfig | undefined;
+
+// Try to load cms-blocks if it exists
+let cmsBlocks: Record<string, unknown> = {};
+try {
+  const cmsPath = config.cmsBlocksFile
+    ? join(cwd, config.cmsBlocksFile)
+    : join(cwd, "cms-blocks.ts");
+  const cmsBlocksModule = await import(`file://${cmsPath}`);
+  cmsBlocks = cmsBlocksModule.cmsBlocks ?? cmsBlocksModule.default ?? {};
+} catch {
+  // No cms-blocks file, that's fine
+}
+
+const PORT = config.devPort;
+const publicPath = config.publicPath; // e.g. "/public"
+
+// Server start time for HMR restart detection
+const SERVER_START_TIME = Date.now();
+
+// SSE clients for hot reload
+const sseClients = new Set<ReadableStreamDefaultController<Uint8Array>>();
+const sseHeartbeats = new Map<
+  ReadableStreamDefaultController<Uint8Array>,
+  ReturnType<typeof setInterval>
+>();
+
+// Debounce file change notifications
+let reloadTimeout: ReturnType<typeof setTimeout> | null = null;
+let lastChangeType: "full" | "css" = "full";
+
+function broadcastReload(type: "full" | "css" = "full") {
+  // Debounce rapid changes
+  if (reloadTimeout) {
+    clearTimeout(reloadTimeout);
+    // Escalate to full reload if mixed changes
+    if (type === "full") lastChangeType = "full";
+  } else {
+    lastChangeType = type;
+  }
+
+  reloadTimeout = setTimeout(() => {
+    reloadTimeout = null;
+    const message = `data: ${JSON.stringify({
+      type: lastChangeType,
+      time: Date.now(),
+    })}\n\n`;
+    const encoder = new TextEncoder();
+    const data = encoder.encode(message);
+
+    for (const controller of sseClients) {
+      try {
+        controller.enqueue(data);
+      } catch {
+        // Clean up both client and heartbeat when controller fails
+        const heartbeat = sseHeartbeats.get(controller);
+        if (heartbeat) {
+          clearInterval(heartbeat);
+          sseHeartbeats.delete(controller);
+        }
+        sseClients.delete(controller);
+      }
+    }
+    console.log(
+      `🔄 ${lastChangeType === "css" ? "CSS" : "Full"} reload triggered`
+    );
+  }, 50);
+}
+
+// Watch for file changes
+const watchDirs = [blocksDir, pagesDir, publicDir, svgDir];
+
+async function handleFileChange(filename: string, dir: string) {
+  // Ignore generated files
+  if (filename.includes("/gen/") || filename.endsWith(".render.ts")) return;
+
+  // SVG in svg/ directory changed - recompile spritesheet
+  if (filename.endsWith(".svg") && dir === svgDir) {
+    console.log(`🎨 SVG changed: ${filename}`);
+    try {
+      await compileSpritesheet({ publicDir });
+      broadcastReload("css"); // No full reload needed for SVG sprites
+    } catch (err) {
+      console.warn("   ⚠ Sprite compilation failed:", err);
+    }
+    return;
+  }
+
+  if (filename.endsWith(".css")) {
+    broadcastReload("css");
+    return;
+  }
+
+  // HTML template changed - recompile templates before reload
+  if (filename.endsWith(".block.html")) {
+    console.log(`📝 Template changed: ${filename}`);
+    await compileBlockTemplates({
+      blocksDir,
+      genDir: join(blocksDir, "gen"),
+    });
+    // bun --watch will restart the server after recompile
+    // which triggers browser reload via SSE reconnect
+    return;
+  }
+
+  // For other source files, just broadcast (bun --watch handles the restart)
+  if (filename.endsWith(".ts") || filename.endsWith(".js")) {
+    broadcastReload("full");
+  }
+}
+
+for (const dir of watchDirs) {
+  try {
+    watch(dir, { recursive: true }, (event, filename) => {
+      if (!filename) return;
+      handleFileChange(filename, dir);
+    });
+  } catch {
+    // Directory might not exist yet
+  }
+}
+
+console.log(`🚀 Starting dev server on http://localhost:${PORT}`);
+console.log(`👀 Watching for changes...`);
+
+Bun.serve({
+  port: PORT,
+  idleTimeout: 120, // Don't kill SSE connections every 10s
+  async fetch(req) {
+    const url = new URL(req.url);
+    const path = url.pathname;
+
+    try {
+      // Dev overlay (special internal asset)
+      if (path === "/__dev-overlay.js") {
+        const js = await Bun.file(join(publicDir, "js/dev-overlay.js")).text();
+        return new Response(js, {
+          headers: { "Content-Type": "application/javascript" },
+        });
+      }
+
+      // Hot reload SSE endpoint
+      if (path === "/__hmr") {
+        const stream = new ReadableStream<Uint8Array>({
+          start(controller) {
+            sseClients.add(controller);
+            const encoder = new TextEncoder();
+            // Send initial connected message with server start time
+            controller.enqueue(
+              encoder.encode(
+                `data: ${JSON.stringify({
+                  type: "connected",
+                  time: SERVER_START_TIME,
+                })}\n\n`
+              )
+            );
+            // Heartbeat every 30s to keep connection alive
+            const heartbeat = setInterval(() => {
+              try {
+                controller.enqueue(encoder.encode(": heartbeat\n\n"));
+              } catch {
+                clearInterval(heartbeat);
+                sseHeartbeats.delete(controller);
+              }
+            }, 30000);
+            sseHeartbeats.set(controller, heartbeat);
+          },
+          cancel(controller) {
+            const heartbeat = sseHeartbeats.get(controller);
+            if (heartbeat) {
+              clearInterval(heartbeat);
+              sseHeartbeats.delete(controller);
+            }
+            sseClients.delete(controller);
+          },
+        });
+
+        return new Response(stream, {
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+          },
+        });
+      }
+
+      // Dev API endpoints
+      if (path === "/__pages") {
+        return Response.json(
+          pages.map((p) => ({
+            id: p.id,
+            path: p.path,
+            title: p.title,
+          }))
+        );
+      }
+
+      if (path === "/__site") {
+        return Response.json({
+          pages: pages.map((p) => ({
+            id: p.id,
+            path: p.path,
+            title: p.title,
+          })),
+          blocks: blockRegistry.types(),
+          schemas: cmsBlocks,
+        });
+      }
+
+      if (path === "/__inspect") {
+        const address = url.searchParams.get("address");
+        if (!address) {
+          return Response.json(
+            { error: "Missing address parameter" },
+            { status: 400 }
+          );
+        }
+
+        try {
+          const decoded = decodeSchemaAddress(address);
+          const page = pages.find((p) => p.id === decoded.pageId);
+          const region = page?.regions[decoded.region];
+          const block = region?.blocks.find((b) => b.id === decoded.blockId);
+          const blockDef = block ? blockRegistry.get(block.type) : null;
+
+          // Convert file:// URL to absolute path if needed
+          const sourceFile = blockDef?.sourceFile?.startsWith("file://")
+            ? blockDef.sourceFile.replace("file://", "")
+            : blockDef?.sourceFile;
+
+          return Response.json({
+            address: decoded,
+            page: page
+              ? {
+                  id: page.id,
+                  path: page.path,
+                  title: page.title,
+                  sourceFile: `${pagesDir}/${decoded.pageId}.page.ts`,
+                }
+              : null,
+            block: block
+              ? {
+                  id: block.id,
+                  type: block.type,
+                  props: block.props,
+                  sourceFile,
+                  templateFile: `${blocksDir}/${block.type}.block.html`,
+                }
+              : null,
+            schema: block ? cmsBlocks[block.type] : null,
+          });
+        } catch (err) {
+          return Response.json(
+            { error: "Invalid address", details: String(err) },
+            { status: 400 }
+          );
+        }
+      }
+
+      // Public static files - serve publicDir at publicPath (1:1 mapping)
+      if (path.startsWith(`${publicPath}/`)) {
+        const relativePath = path.slice(publicPath.length + 1);
+        const filePath = join(publicDir, relativePath);
+        const file = Bun.file(filePath);
+        if (await file.exists()) {
+          // Process CSS through lightningcss (no minification in dev)
+          if (filePath.endsWith(".css")) {
+            const cssBytes = new Uint8Array(await file.arrayBuffer());
+            const result = processCSS({
+              filename: filePath,
+              code: cssBytes,
+              minify: false,
+            });
+            return new Response(new TextDecoder().decode(result.code), {
+              headers: {
+                "Content-Type": "text/css",
+                "Cache-Control": "no-cache, no-store, must-revalidate",
+              },
+            });
+          }
+          return new Response(file, {
+            headers: { "Cache-Control": "no-cache, no-store, must-revalidate" },
+          });
+        }
+      }
+
+      // Page routes
+      const pagePath = path === "/" ? "/" : path.replace(/\/$/, "");
+      const page = getPageByPath(pagePath);
+
+      if (page) {
+        const html = await renderPage(page, {
+          templateDir: pagesDir,
+          isDev: true,
+          assetBase: "/",
+        });
+
+        return new Response(html, {
+          headers: { "Content-Type": "text/html" },
+        });
+      }
+
+      // 404
+      return new Response("Not Found", { status: 404 });
+    } catch (err) {
+      console.error("Error handling request:", err);
+      return new Response(
+        `<html>
+          <head><title>Error</title></head>
+          <body style="font-family: system-ui; padding: 2rem;">
+            <h1>Server Error</h1>
+            <pre style="background: #f5f5f5; padding: 1rem; overflow: auto;">${String(
+              err
+            )}</pre>
+          </body>
+        </html>`,
+        {
+          status: 500,
+          headers: { "Content-Type": "text/html" },
+        }
+      );
+    }
+  },
+});
+
+console.log(`
+  Dev server running at http://localhost:${PORT}
+
+  Pages: ${pagesDir}
+  Public: ${publicDir} → ${publicPath}/
+
+  Dev API:
+    /__pages    → List all pages
+    /__site     → Site config (pages, blocks, schemas)
+    /__inspect  → Decode schema address
+`);

package/src/commands/gen.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env bun
+/**
+ * Generate block render functions from templates
+ */
+
+import { join } from "node:path";
+import { compileBlockTemplates } from "@vojtaholik/static-kit-core";
+import { loadConfig } from "../config-loader.ts";
+
+const cwd = process.cwd();
+const config = await loadConfig(cwd);
+
+console.log("🔨 Compiling block templates...");
+
+await compileBlockTemplates({
+  blocksDir: join(cwd, config.blocksDir),
+  genDir: join(cwd, config.blocksDir, "gen"),
+});
+
+console.log("✅ Done!");

package/src/commands/sprite.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env bun
+/**
+ * Static Kit - SVG Sprite CLI Command
+ *
+ * Compiles individual SVG files from publicDir/svg/ into a single spritesheet.
+ *
+ * Usage in HTML:
+ *   <svg><use href="/public/sprite.svg#icon-name"/></svg>
+ */
+
+import { loadConfig, resolvePath } from "../config-loader.ts";
+import { compileSpritesheet } from "../sprite-compiler.ts";
+
+const cwd = process.cwd();
+const config = await loadConfig(cwd);
+const publicDir = resolvePath(config, "publicDir", cwd);
+
+console.log("🎨 Compiling SVG spritesheet...\n");
+
+try {
+  const { count, outputPath } = await compileSpritesheet({ publicDir });
+  console.log(`  ✓ Compiled ${count} SVGs → ${outputPath}`);
+  console.log("\n✅ Sprite compilation complete!");
+} catch (err) {
+  if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+    console.log("  ℹ No svg/ directory found, skipping sprite compilation");
+  } else {
+    console.error("Sprite compilation failed:", err);
+    process.exit(1);
+  }
+}

package/src/config-loader.ts

@@ -0,0 +1,43 @@
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { configSchema, type StaticKitConfig } from "@vojtaholik/static-kit-core";
+
+/**
+ * Load static-kit.config.ts from the current working directory
+ */
+export async function loadConfig(
+  cwd = process.cwd()
+): Promise<StaticKitConfig> {
+  const configPath = join(cwd, "static-kit.config.ts");
+
+  // Check if file exists first
+  if (!existsSync(configPath)) {
+    console.log("No static-kit.config.ts found, using defaults");
+    return configSchema.parse({});
+  }
+
+  try {
+    // Use file:// URL for dynamic imports
+    const configModule = await import(`file://${configPath}`);
+    const rawConfig = configModule.default ?? configModule;
+    return configSchema.parse(rawConfig);
+  } catch (err) {
+    console.error("Error loading config:", err);
+    throw err;
+  }
+}
+
+/**
+ * Resolve a path relative to the project root
+ */
+export function resolvePath(
+  config: StaticKitConfig,
+  key: keyof StaticKitConfig,
+  cwd = process.cwd()
+): string {
+  const value = config[key];
+  if (typeof value !== "string") {
+    throw new Error(`Config key ${key} is not a string`);
+  }
+  return join(cwd, value);
+}

package/src/css-processor.ts

@@ -0,0 +1,81 @@
+/**
+ * CSS Processing with lightningcss
+ *
+ * Handles:
+ * - CSS nesting (native)
+ * - Custom media queries
+ * - Vendor prefixes (autoprefixer)
+ * - Minification (build only)
+ */
+
+import { transform, browserslistToTargets } from "lightningcss";
+import browserslist from "browserslist";
+
+// Cache the targets since browserslist resolution is expensive
+let cachedTargets: ReturnType<typeof browserslistToTargets> | null = null;
+
+function getTargets() {
+  if (!cachedTargets) {
+    cachedTargets = browserslistToTargets(browserslist("> 0.5%, not dead"));
+  }
+  return cachedTargets;
+}
+
+export interface CSSProcessOptions {
+  /** Enable minification (typically false for dev, true for build) */
+  minify?: boolean;
+  /** Filename for error reporting and source maps */
+  filename: string;
+  /** Raw CSS content as Uint8Array */
+  code: Uint8Array;
+}
+
+export interface CSSProcessResult {
+  code: Uint8Array;
+  map: Uint8Array | undefined;
+}
+
+/**
+ * Process CSS through lightningcss
+ *
+ * Features enabled:
+ * - CSS nesting (lowered for browser compat)
+ * - Custom media queries draft spec
+ * - Vendor prefixes based on browserslist targets
+ */
+export function processCSS(options: CSSProcessOptions): CSSProcessResult {
+  const result = transform({
+    filename: options.filename,
+    code: options.code,
+    minify: options.minify ?? false,
+    targets: getTargets(),
+    drafts: {
+      customMedia: true,
+    },
+    // Error on unknown at-rules instead of passing through
+    errorRecovery: false,
+  });
+
+  return {
+    code: result.code,
+    map: result.map ?? undefined,
+  };
+}
+
+/**
+ * Process CSS from a string (convenience wrapper)
+ */
+export function processCSSString(
+  css: string,
+  options: Omit<CSSProcessOptions, "code">
+): string {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+
+  const result = processCSS({
+    ...options,
+    code: encoder.encode(css),
+  });
+
+  return decoder.decode(result.code);
+}

package/src/sprite-compiler.ts

@@ -0,0 +1,75 @@
+/**
+ * SVG Sprite Compiler
+ *
+ * Compiles individual SVG files into a single spritesheet.
+ * Each SVG becomes a <symbol> element with id matching the filename.
+ */
+
+import { join, basename } from "node:path";
+import { Glob } from "bun";
+
+export interface SpriteCompileOptions {
+  publicDir: string;
+  /** Relative path within publicDir for source SVGs */
+  svgDir?: string;
+  /** Output filename within publicDir */
+  outputFile?: string;
+}
+
+/**
+ * Parse an SVG string and extract viewBox + inner content
+ */
+function parseSvg(content: string): { viewBox: string; inner: string } | null {
+  // Extract viewBox attribute
+  const viewBoxMatch = content.match(/viewBox=["']([^"']+)["']/);
+  const viewBox = viewBoxMatch?.[1] ?? "0 0 24 24";
+
+  // Extract content between <svg> tags
+  const svgMatch = content.match(/<svg[^>]*>([\s\S]*)<\/svg>/i);
+  if (!svgMatch) return null;
+
+  const inner = svgMatch[1]?.trim() ?? "";
+  return { viewBox, inner };
+}
+
+/**
+ * Compile SVGs from a directory into a spritesheet
+ */
+export async function compileSpritesheet(
+  options: SpriteCompileOptions
+): Promise<{ count: number; outputPath: string }> {
+  const { publicDir, svgDir = "svg", outputFile = "sprite.svg" } = options;
+
+  const inputDir = join(publicDir, svgDir);
+  const outputPath = join(publicDir, outputFile);
+
+  const symbols: string[] = [];
+  const glob = new Glob("*.svg");
+
+  for await (const file of glob.scan(inputDir)) {
+    const filePath = join(inputDir, file);
+    const content = await Bun.file(filePath).text();
+
+    const parsed = parseSvg(content);
+    if (!parsed) {
+      console.warn(`  ⚠ Skipping ${file}: could not parse SVG`);
+      continue;
+    }
+
+    // Use filename without extension as symbol id
+    const id = basename(file, ".svg");
+    symbols.push(
+      `  <symbol id="${id}" viewBox="${parsed.viewBox}">\n    ${parsed.inner}\n  </symbol>`
+    );
+  }
+
+  // Generate spritesheet
+  const spritesheet = `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="display:none;">
+${symbols.join("\n")}
+</svg>
+`;
+
+  await Bun.write(outputPath, spritesheet);
+
+  return { count: symbols.length, outputPath };
+}