@ncukondo/slide-generation 0.7.0 → 0.8.1

package/dist/cli/index.js

@@ -338,6 +338,13 @@ ${slidesContent}`;
             lines.push(`${key}: ${this.formatFrontMatterValue(value)}`);
           }
         }
+        if (options?.templateCss && options.templateCss.trim()) {
+          lines.push("style: |");
+          const cssLines = options.templateCss.split("\n");
+          for (const line of cssLines) {
+            lines.push(`  ${line}`);
+          }
+        }
         lines.push("---");
         return lines.join("\n");
       }
@@ -374,7 +381,7 @@ ${this.renderSpeakerNotes(note)}`;
           }
           parts.push(slideContent);
         }
-        return parts.map((slide) => `---
+        return parts.map((slide, index) => index === 0 ? slide : `---
 
 ${slide}`).join("\n\n");
       }
@@ -615,6 +622,46 @@ var init_loader = __esm({
   }
 });
 
+// src/templates/css-collector.ts
+var CSSCollector;
+var init_css_collector = __esm({
+  "src/templates/css-collector.ts"() {
+    "use strict";
+    CSSCollector = class {
+      constructor(templateLoader) {
+        this.templateLoader = templateLoader;
+      }
+      /**
+       * Collect CSS from the specified templates
+       * @param templateNames - Names of templates to collect CSS from
+       * @returns Combined CSS string from all templates
+       */
+      collect(templateNames) {
+        const uniqueNames = [...new Set(templateNames)];
+        const cssBlocks = [];
+        for (const name of uniqueNames) {
+          const template = this.templateLoader.get(name);
+          if (template?.css) {
+            cssBlocks.push(template.css);
+          }
+        }
+        return cssBlocks.join("\n\n");
+      }
+    };
+  }
+});
+
+// src/templates/index.ts
+var init_templates = __esm({
+  "src/templates/index.ts"() {
+    "use strict";
+    init_engine();
+    init_loader();
+    init_validators();
+    init_css_collector();
+  }
+});
+
 // src/icons/schema.ts
 import { z as z4 } from "zod";
 var iconSourceTypeSchema, iconSourceSchema, iconDefaultsSchema, iconRegistrySchema;
@@ -757,24 +804,217 @@ var init_registry = __esm({
   }
 });
 
-// src/icons/resolver.ts
+// src/icons/fetcher.ts
 import * as fs3 from "fs/promises";
 import * as path2 from "path";
+import { stringify as stringifyYaml, parse as parseYaml3 } from "yaml";
+function isExternalSource(prefix) {
+  return ICON_SOURCES[prefix]?.external ?? false;
+}
+function isValidIconName(name, allowPath = false) {
+  if (!name || name.length > 100) {
+    return false;
+  }
+  if (name.includes("..") || name.startsWith("/") || name.endsWith("/")) {
+    return false;
+  }
+  const pattern = allowPath ? VALID_ICON_NAME_WITH_PATH : VALID_ICON_NAME;
+  return pattern.test(name);
+}
+var ICON_SOURCES, VALID_ICON_NAME, VALID_ICON_NAME_WITH_PATH, IconFetcher;
+var init_fetcher = __esm({
+  "src/icons/fetcher.ts"() {
+    "use strict";
+    ICON_SOURCES = {
+      health: { set: "healthicons", license: "MIT", external: true },
+      ms: { set: "material-symbols", license: "Apache-2.0", external: true },
+      hero: { set: "heroicons", license: "MIT", external: true },
+      mi: { set: "material-icons", license: "Apache-2.0", external: false },
+      mdi: { set: "mdi", license: "Apache-2.0", external: true },
+      iconify: { set: "iconify", license: "Various", external: true }
+    };
+    VALID_ICON_NAME = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/i;
+    VALID_ICON_NAME_WITH_PATH = /^[a-z0-9][a-z0-9-/]*[a-z0-9]$|^[a-z0-9]$/i;
+    IconFetcher = class {
+      fetchedDir;
+      saveLocally;
+      timeoutMs;
+      constructor(options = {}) {
+        this.fetchedDir = options.fetchedDir ?? "icons/fetched";
+        this.saveLocally = options.saveLocally ?? true;
+        this.timeoutMs = options.timeoutMs ?? 1e4;
+      }
+      /**
+       * Parse an icon reference string (e.g., "health:stethoscope")
+       * Returns null if the format is invalid or contains unsafe characters
+       */
+      parseReference(iconRef) {
+        const colonIndex = iconRef.indexOf(":");
+        if (colonIndex === -1) {
+          return null;
+        }
+        const prefix = iconRef.substring(0, colonIndex);
+        const name = iconRef.substring(colonIndex + 1);
+        if (!/^[a-z0-9]+$/i.test(prefix)) {
+          return null;
+        }
+        if (!isValidIconName(name)) {
+          return null;
+        }
+        return { prefix, name };
+      }
+      /**
+       * Get the Iconify set name for a prefix
+       */
+      getIconifySet(prefix) {
+        return ICON_SOURCES[prefix]?.set ?? prefix;
+      }
+      /**
+       * Get the local file path for an icon reference
+       */
+      getLocalPath(iconRef) {
+        const parsed = this.parseReference(iconRef);
+        if (!parsed) {
+          throw new Error(`Invalid icon reference: ${iconRef}`);
+        }
+        const setDir = this.getIconifySet(parsed.prefix);
+        return path2.join(this.fetchedDir, setDir, `${parsed.name}.svg`);
+      }
+      /**
+       * Check if an icon exists locally
+       */
+      async existsLocally(iconRef) {
+        const localPath = this.getLocalPath(iconRef);
+        try {
+          await fs3.access(localPath);
+          return true;
+        } catch {
+          return false;
+        }
+      }
+      /**
+       * Build the Iconify API URL for an icon
+       */
+      buildUrl(prefix, name) {
+        const set = this.getIconifySet(prefix);
+        return `https://api.iconify.design/${set}/${name}.svg`;
+      }
+      /**
+       * Resolve an icon reference (local first, then fetch)
+       */
+      async resolve(iconRef) {
+        if (await this.existsLocally(iconRef)) {
+          const localPath = this.getLocalPath(iconRef);
+          return await fs3.readFile(localPath, "utf-8");
+        }
+        return await this.fetchAndSave(iconRef);
+      }
+      /**
+       * Fetch an icon from external source and save locally
+       */
+      async fetchAndSave(iconRef) {
+        const parsed = this.parseReference(iconRef);
+        if (!parsed) {
+          throw new Error(`Invalid icon reference: ${iconRef}`);
+        }
+        const url = this.buildUrl(parsed.prefix, parsed.name);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+          response = await fetch(url, { signal: controller.signal });
+        } catch (error) {
+          if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(`Fetch timeout: ${iconRef} (exceeded ${this.timeoutMs}ms)`);
+          }
+          throw error;
+        } finally {
+          clearTimeout(timeoutId);
+        }
+        if (!response.ok) {
+          throw new Error(`Icon not found: ${iconRef} (HTTP ${response.status})`);
+        }
+        const svg = await response.text();
+        if (this.saveLocally) {
+          await this.saveLocallyInternal(parsed.prefix, parsed.name, svg, url);
+        }
+        return svg;
+      }
+      /**
+       * Save icon to local filesystem
+       */
+      async saveLocallyInternal(prefix, name, svg, sourceUrl) {
+        const setDir = this.getIconifySet(prefix);
+        const dirPath = path2.join(this.fetchedDir, setDir);
+        const filePath = path2.join(dirPath, `${name}.svg`);
+        await fs3.mkdir(dirPath, { recursive: true });
+        await fs3.writeFile(filePath, svg, "utf-8");
+        await this.updateSourcesYaml(setDir, name, sourceUrl);
+      }
+      /**
+       * Update _sources.yaml with source information
+       */
+      async updateSourcesYaml(setDir, name, sourceUrl) {
+        const sourcesPath = path2.join(this.fetchedDir, "_sources.yaml");
+        let sources = {};
+        try {
+          const content = await fs3.readFile(sourcesPath, "utf-8");
+          sources = parseYaml3(content) ?? {};
+        } catch {
+        }
+        const key = `${setDir}/${name}.svg`;
+        sources[key] = {
+          source: sourceUrl,
+          fetched_at: (/* @__PURE__ */ new Date()).toISOString(),
+          license: this.getLicense(setDir)
+        };
+        const header = `# Fetched icon sources
+# This file tracks where icons were fetched from for traceability
+
+`;
+        await fs3.writeFile(sourcesPath, header + stringifyYaml(sources), "utf-8");
+      }
+      /**
+       * Get the license for an icon set
+       */
+      getLicense(setDir) {
+        for (const config of Object.values(ICON_SOURCES)) {
+          if (config.set === setDir) {
+            return config.license;
+          }
+        }
+        return "Unknown";
+      }
+    };
+  }
+});
+
+// src/icons/resolver.ts
+import * as fs4 from "fs/promises";
+import * as path3 from "path";
 import nunjucks2 from "nunjucks";
 var IconResolver;
 var init_resolver = __esm({
   "src/icons/resolver.ts"() {
     "use strict";
+    init_fetcher();
     IconResolver = class {
       constructor(registry, options = {}) {
         this.registry = registry;
         this.nunjucksEnv = new nunjucks2.Environment(null, {
           autoescape: false
         });
-        this.options = options;
+        this.options = {
+          autoFetch: true,
+          ...options
+        };
+        this.fetcher = new IconFetcher({
+          fetchedDir: options.fetchedDir ?? "icons/fetched"
+        });
       }
       nunjucksEnv;
       options;
+      fetcher;
       /**
        * Render an icon by name or alias
        */
@@ -796,6 +1036,17 @@ var init_resolver = __esm({
           color: this.resolveColor(options?.color) ?? defaults.color,
           ...options?.class !== void 0 ? { class: options.class } : {}
         };
+        const cachedSvg = await this.tryGetCachedSvg(parsed.prefix, parsed.name);
+        if (cachedSvg) {
+          return this.processSvg(cachedSvg, parsed.name, mergedOptions);
+        }
+        if (this.options.autoFetch && this.isFetchableSource(parsed.prefix)) {
+          try {
+            const fetchedSvg = await this.fetcher.fetchAndSave(`${parsed.prefix}:${parsed.name}`);
+            return this.processSvg(fetchedSvg, parsed.name, mergedOptions);
+          } catch {
+          }
+        }
         switch (source.type) {
           case "web-font":
             return this.renderWebFont(source, parsed.name, mergedOptions);
@@ -809,6 +1060,29 @@ var init_resolver = __esm({
             throw new Error(`Unsupported icon source type: "${source.type}"`);
         }
       }
+      /**
+       * Try to get a cached SVG from the fetched directory
+       */
+      async tryGetCachedSvg(prefix, name) {
+        const iconSourceConfig = ICON_SOURCES[prefix];
+        if (!iconSourceConfig) {
+          return null;
+        }
+        const setDir = iconSourceConfig.set;
+        const fetchedDir = this.options.fetchedDir ?? "icons/fetched";
+        const svgPath = path3.join(fetchedDir, setDir, `${name}.svg`);
+        try {
+          return await fs4.readFile(svgPath, "utf-8");
+        } catch {
+          return null;
+        }
+      }
+      /**
+       * Check if a source prefix is fetchable from external API
+       */
+      isFetchableSource(prefix) {
+        return prefix in ICON_SOURCES;
+      }
       /**
        * Render a web-font icon
        */
@@ -833,9 +1107,9 @@ var init_resolver = __esm({
         if (!source.path) {
           throw new Error(`Local SVG source "${source.name}" has no path defined`);
         }
-        const svgPath = path2.join(source.path, `${name}.svg`);
+        const svgPath = path3.join(source.path, `${name}.svg`);
         try {
-          const svgContent = await fs3.readFile(svgPath, "utf-8");
+          const svgContent = await fs4.readFile(svgPath, "utf-8");
           return this.processSvg(svgContent, name, options);
         } catch (error) {
           if (error.code === "ENOENT") {
@@ -982,6 +1256,8 @@ var init_manager = __esm({
       }
       /**
        * Get multiple references by IDs using ref export for better performance
+       * Note: ref export returns exit code 1 when references are not found,
+       * but still outputs valid JSON (empty array or partial results) to stdout
        */
       async getByIds(ids) {
         if (ids.length === 0) {
@@ -989,7 +1265,8 @@ var init_manager = __esm({
         }
         const idsArg = ids.map((id) => `"${id}"`).join(" ");
         const result = await this.execCommand(
-          `${this.command} export ${idsArg}`
+          `${this.command} export ${idsArg}`,
+          true
         );
         const items = this.parseJSON(result);
         const map = /* @__PURE__ */ new Map();
@@ -998,16 +1275,16 @@ var init_manager = __esm({
         }
         return map;
       }
-      execCommand(cmd) {
-        return new Promise((resolve8, reject) => {
+      execCommand(cmd, ignoreExitCode = false) {
+        return new Promise((resolve9, reject) => {
           exec(cmd, (error, stdout) => {
-            if (error) {
+            if (error && !ignoreExitCode) {
               reject(
                 new ReferenceManagerError(`Failed to execute: ${cmd}`, error)
               );
               return;
             }
-            resolve8(stdout.toString());
+            resolve9(stdout.toString());
           });
         });
       }
@@ -1462,7 +1739,7 @@ var init_bibliography = __esm({
 });
 
 // src/core/pipeline.ts
-import { writeFile } from "fs/promises";
+import { writeFile as writeFile2 } from "fs/promises";
 var PipelineError, Pipeline;
 var init_pipeline = __esm({
   "src/core/pipeline.ts"() {
@@ -1471,7 +1748,7 @@ var init_pipeline = __esm({
     init_transformer();
     init_renderer();
     init_engine();
-    init_loader();
+    init_templates();
     init_registry();
     init_resolver();
     init_manager();
@@ -1493,7 +1770,9 @@ var init_pipeline = __esm({
         this.templateEngine = new TemplateEngine();
         this.templateLoader = new TemplateLoader();
         this.iconRegistry = new IconRegistryLoader();
-        this.iconResolver = new IconResolver(this.iconRegistry);
+        this.iconResolver = new IconResolver(this.iconRegistry, {
+          fetchedDir: config.icons.fetched
+        });
         this.referenceManager = new ReferenceManager(
           config.references.connection.command
         );
@@ -1520,6 +1799,7 @@ var init_pipeline = __esm({
           this.citationFormatter
         );
         this.renderer = new Renderer();
+        this.cssCollector = new CSSCollector(this.templateLoader);
       }
       parser;
       templateEngine;
@@ -1532,6 +1812,7 @@ var init_pipeline = __esm({
       bibliographyGenerator;
       transformer;
       renderer;
+      cssCollector;
       warnings = [];
       /**
        * Run the full conversion pipeline
@@ -1546,7 +1827,7 @@ var init_pipeline = __esm({
           const transformedSlides = await this.transformSlides(presentation);
           const output = this.render(transformedSlides, presentation);
           if (options?.outputPath) {
-            await writeFile(options.outputPath, output, "utf-8");
+            await writeFile2(options.outputPath, output, "utf-8");
           }
           return output;
         } catch (error) {
@@ -1573,7 +1854,7 @@ var init_pipeline = __esm({
           const transformedSlides = await this.transformSlides(presentation);
           const output = this.render(transformedSlides, presentation);
           if (options?.outputPath) {
-            await writeFile(options.outputPath, output, "utf-8");
+            await writeFile2(options.outputPath, output, "utf-8");
           }
           return {
             output,
@@ -1687,9 +1968,12 @@ var init_pipeline = __esm({
       render(slides, presentation) {
         try {
           const notes = presentation.slides.map((slide) => slide.notes);
+          const templateNames = presentation.slides.map((slide) => slide.template);
+          const templateCss = this.cssCollector.collect(templateNames);
           const renderOptions = {
             includeTheme: true,
-            notes
+            notes,
+            ...templateCss ? { templateCss } : {}
           };
           return this.renderer.render(slides, presentation.meta, renderOptions);
         } catch (error) {
@@ -1804,11 +2088,7 @@ var init_schema2 = __esm({
       }).default({}),
       icons: z5.object({
         registry: z5.string().default("./icons/registry.yaml"),
-        cache: z5.object({
-          enabled: z5.boolean().default(true),
-          directory: z5.string().default(".cache/icons"),
-          ttl: z5.number().default(86400)
-        }).default({})
+        fetched: z5.string().default("./icons/fetched")
       }).default({}),
       references: z5.object({
         enabled: z5.boolean().default(true),
@@ -1834,9 +2114,9 @@ var init_schema2 = __esm({
 });
 
 // src/config/loader.ts
-import { access, readFile as readFile5 } from "fs/promises";
-import { join as join3 } from "path";
-import { parse as parseYaml3 } from "yaml";
+import { access as access2, readFile as readFile6 } from "fs/promises";
+import { join as join4 } from "path";
+import { parse as parseYaml4 } from "yaml";
 var CONFIG_NAMES, ConfigLoader;
 var init_loader2 = __esm({
   "src/config/loader.ts"() {
@@ -1850,9 +2130,9 @@ var init_loader2 = __esm({
       }
       async findConfig(directory) {
         for (const name of CONFIG_NAMES) {
-          const path12 = join3(directory, name);
+          const path12 = join4(directory, name);
           try {
-            await access(path12);
+            await access2(path12);
             return path12;
           } catch {
           }
@@ -1862,8 +2142,8 @@ var init_loader2 = __esm({
       async loadFile(configPath) {
         if (!configPath) return {};
         try {
-          const content = await readFile5(configPath, "utf-8");
-          return parseYaml3(content) ?? {};
+          const content = await readFile6(configPath, "utf-8");
+          return parseYaml4(content) ?? {};
         } catch (error) {
           if (error.code === "ENOENT") {
             return {};
@@ -1995,9 +2275,9 @@ var init_schema3 = __esm({
 });
 
 // src/images/metadata-loader.ts
-import * as fs4 from "fs/promises";
-import * as path3 from "path";
-import { parse as parseYaml4 } from "yaml";
+import * as fs5 from "fs/promises";
+import * as path4 from "path";
+import { parse as parseYaml5 } from "yaml";
 var metadataWarnings, ImageMetadataLoader;
 var init_metadata_loader = __esm({
   "src/images/metadata-loader.ts"() {
@@ -2026,16 +2306,16 @@ var init_metadata_loader = __esm({
        */
       async loadDirectory(dirPath) {
         const result = /* @__PURE__ */ new Map();
-        const fullDirPath = path3.join(this.baseDir, dirPath);
+        const fullDirPath = path4.join(this.baseDir, dirPath);
         try {
-          await fs4.access(fullDirPath);
+          await fs5.access(fullDirPath);
         } catch {
           return result;
         }
-        const files = await fs4.readdir(fullDirPath);
+        const files = await fs5.readdir(fullDirPath);
         const imageFiles = files.filter((f) => isImageFile(f));
         for (const file of imageFiles) {
-          const imagePath = path3.join(dirPath, file);
+          const imagePath = path4.join(dirPath, file);
           const metadata = await this.load(imagePath);
           result.set(file, metadata);
         }
@@ -2047,7 +2327,7 @@ var init_metadata_loader = __esm({
       async hasMetadata(imagePath) {
         const individualPath = this.getIndividualMetadataPath(imagePath);
         try {
-          await fs4.access(individualPath);
+          await fs5.access(individualPath);
           return true;
         } catch {
         }
@@ -2055,7 +2335,7 @@ var init_metadata_loader = __esm({
         if (dirMetadata === null) {
           return false;
         }
-        const filename = path3.basename(imagePath);
+        const filename = path4.basename(imagePath);
         return filename in dirMetadata && filename !== "_defaults";
       }
       /**
@@ -2069,14 +2349,14 @@ var init_metadata_loader = __esm({
        * Get the path to individual metadata file
        */
       getIndividualMetadataPath(imagePath) {
-        return path3.join(this.baseDir, `${imagePath}.meta.yaml`);
+        return path4.join(this.baseDir, `${imagePath}.meta.yaml`);
       }
       /**
        * Get the path to directory metadata file
        */
       getDirectoryMetadataPath(imagePath) {
-        const dir = path3.dirname(imagePath);
-        return path3.join(this.baseDir, dir, "images.yaml");
+        const dir = path4.dirname(imagePath);
+        return path4.join(this.baseDir, dir, "images.yaml");
       }
       /**
        * Load individual metadata file (.meta.yaml)
@@ -2084,13 +2364,13 @@ var init_metadata_loader = __esm({
       async loadIndividualMetadata(imagePath) {
         const metadataPath = this.getIndividualMetadataPath(imagePath);
         try {
-          await fs4.access(metadataPath);
+          await fs5.access(metadataPath);
         } catch {
           return null;
         }
         try {
-          const content = await fs4.readFile(metadataPath, "utf-8");
-          const parsed = parseYaml4(content);
+          const content = await fs5.readFile(metadataPath, "utf-8");
+          const parsed = parseYaml5(content);
           const validated = individualMetadataSchema.safeParse(parsed);
           if (validated.success) {
             return validated.data;
@@ -2115,13 +2395,13 @@ var init_metadata_loader = __esm({
       async loadDirectoryMetadataFile(imagePath) {
         const metadataPath = this.getDirectoryMetadataPath(imagePath);
         try {
-          await fs4.access(metadataPath);
+          await fs5.access(metadataPath);
         } catch {
           return null;
         }
         try {
-          const content = await fs4.readFile(metadataPath, "utf-8");
-          const parsed = parseYaml4(content);
+          const content = await fs5.readFile(metadataPath, "utf-8");
+          const parsed = parseYaml5(content);
           const validated = directoryMetadataSchema.safeParse(parsed);
           if (validated.success) {
             return validated.data;
@@ -2148,7 +2428,7 @@ var init_metadata_loader = __esm({
         if (dirMetadata === null) {
           return {};
         }
-        const filename = path3.basename(imagePath);
+        const filename = path4.basename(imagePath);
         const defaults = dirMetadata["_defaults"] ?? {};
         const fileMetadata = dirMetadata[filename] ?? {};
         return this.mergeMetadata(defaults, fileMetadata);
@@ -2183,8 +2463,8 @@ var init_metadata_loader = __esm({
 });
 
 // src/images/validator.ts
-import * as fs5 from "fs/promises";
-import * as path4 from "path";
+import * as fs6 from "fs/promises";
+import * as path5 from "path";
 import imageSize from "image-size";
 var ImageValidator;
 var init_validator = __esm({
@@ -2204,14 +2484,14 @@ var init_validator = __esm({
       async validateImageExists(imagePath) {
         const errors = [];
         const warnings = [];
-        const fullPath = path4.join(this.baseDir, imagePath);
-        const ext = path4.extname(imagePath).toLowerCase();
+        const fullPath = path5.join(this.baseDir, imagePath);
+        const ext = path5.extname(imagePath).toLowerCase();
         if (!IMAGE_EXTENSIONS.has(ext)) {
           errors.push(`Unsupported image format: ${imagePath}`);
           return { valid: false, errors, warnings };
         }
         try {
-          await fs5.access(fullPath);
+          await fs6.access(fullPath);
         } catch {
           errors.push(`Image not found: ${imagePath}`);
           return { valid: false, errors, warnings };
@@ -2222,9 +2502,9 @@ var init_validator = __esm({
        * Get image dimensions
        */
       async getImageDimensions(imagePath) {
-        const fullPath = path4.join(this.baseDir, imagePath);
+        const fullPath = path5.join(this.baseDir, imagePath);
         try {
-          const buffer = await fs5.readFile(fullPath);
+          const buffer = await fs6.readFile(fullPath);
           const dimensions = imageSize(buffer);
           if (dimensions.width && dimensions.height) {
             return {
@@ -2559,8 +2839,8 @@ var init_processor = __esm({
 });
 
 // src/images/processing-pipeline.ts
-import * as fs6 from "fs/promises";
-import * as path5 from "path";
+import * as fs7 from "fs/promises";
+import * as path6 from "path";
 var ImageProcessingPipeline;
 var init_processing_pipeline = __esm({
   "src/images/processing-pipeline.ts"() {
@@ -2573,7 +2853,7 @@ var init_processing_pipeline = __esm({
         this.baseDir = baseDir;
         this.metadataLoader = new ImageMetadataLoader(baseDir);
         this.processor = new ImageProcessor();
-        this.outputDir = options?.outputDir ?? path5.join(baseDir, ".processed");
+        this.outputDir = options?.outputDir ?? path6.join(baseDir, ".processed");
       }
       metadataLoader;
       processor;
@@ -2582,7 +2862,7 @@ var init_processing_pipeline = __esm({
        * Process a single image based on its metadata instructions
        */
       async processImage(imagePath) {
-        const fullPath = path5.join(this.baseDir, imagePath);
+        const fullPath = path6.join(this.baseDir, imagePath);
         const result = {
           success: true,
           originalPath: fullPath
@@ -2593,7 +2873,7 @@ var init_processing_pipeline = __esm({
             result.skipped = true;
             return result;
           }
-          await fs6.mkdir(this.outputDir, { recursive: true });
+          await fs7.mkdir(this.outputDir, { recursive: true });
           const processedPath = await this.applyInstructions(
             fullPath,
             imagePath,
@@ -2622,7 +2902,7 @@ var init_processing_pipeline = __esm({
           imageMap: /* @__PURE__ */ new Map()
         };
         try {
-          const files = await fs6.readdir(this.baseDir);
+          const files = await fs7.readdir(this.baseDir);
           const imageFiles = files.filter((f) => isImageFile(f));
           result.totalImages = imageFiles.length;
           for (const imageFile of imageFiles) {
@@ -2646,11 +2926,11 @@ var init_processing_pipeline = __esm({
        * Apply processing instructions to an image
        */
       async applyInstructions(inputPath, relativePath, instructions) {
-        const outputFilename = path5.basename(relativePath);
-        const finalOutputPath = path5.join(this.outputDir, outputFilename);
+        const outputFilename = path6.basename(relativePath);
+        const finalOutputPath = path6.join(this.outputDir, outputFilename);
         const tempPaths = [
-          path5.join(this.outputDir, `temp_${outputFilename}`),
-          path5.join(this.outputDir, `temp2_${outputFilename}`)
+          path6.join(this.outputDir, `temp_${outputFilename}`),
+          path6.join(this.outputDir, `temp2_${outputFilename}`)
         ];
         let currentInputPath = inputPath;
         for (let i = 0; i < instructions.length; i++) {
@@ -2663,11 +2943,11 @@ var init_processing_pipeline = __esm({
           }
         }
         try {
-          await fs6.unlink(path5.join(this.outputDir, `temp_${outputFilename}`));
+          await fs7.unlink(path6.join(this.outputDir, `temp_${outputFilename}`));
         } catch {
         }
         try {
-          await fs6.unlink(path5.join(this.outputDir, `temp2_${outputFilename}`));
+          await fs7.unlink(path6.join(this.outputDir, `temp2_${outputFilename}`));
         } catch {
         }
         return finalOutputPath;
@@ -2753,19 +3033,19 @@ var init_images = __esm({
 
 // src/cli/commands/convert.ts
 import { Command } from "commander";
-import { access as access4, readFile as readFile8 } from "fs/promises";
-import { basename as basename3, dirname as dirname2, join as join7 } from "path";
+import { access as access5, readFile as readFile9 } from "fs/promises";
+import { basename as basename3, dirname as dirname2, join as join8, resolve, isAbsolute } from "path";
 import chalk from "chalk";
 import ora from "ora";
-import { parse as parseYaml5 } from "yaml";
+import { parse as parseYaml6 } from "yaml";
 function getDefaultOutputPath(inputPath) {
   const dir = dirname2(inputPath);
   const base = basename3(inputPath, ".yaml");
-  return join7(dir, `${base}.md`);
+  return join8(dir, `${base}.md`);
 }
 async function extractImageDirectories(inputPath, baseDir) {
-  const content = await readFile8(inputPath, "utf-8");
-  const parsed = parseYaml5(content);
+  const content = await readFile9(inputPath, "utf-8");
+  const parsed = parseYaml6(content);
   const imageDirs = /* @__PURE__ */ new Set();
   if (!parsed.slides) return [];
   for (const slide of parsed.slides) {
@@ -2788,7 +3068,7 @@ async function extractImageDirectories(inputPath, baseDir) {
     for (const imagePath of imagePaths) {
       const dir = dirname2(imagePath);
       if (dir && dir !== ".") {
-        imageDirs.add(join7(baseDir, dir));
+        imageDirs.add(join8(baseDir, dir));
       }
     }
   }
@@ -2799,7 +3079,7 @@ async function processImages(inputPath, baseDir) {
   let totalProcessed = 0;
   for (const imageDir of imageDirs) {
     try {
-      await access4(imageDir);
+      await access5(imageDir);
       const pipeline = new ImageProcessingPipeline(imageDir);
       const result = await pipeline.processDirectory();
       totalProcessed += result.processedImages;
@@ -2824,7 +3104,7 @@ async function executeConvert(inputPath, options) {
   try {
     spinner?.start(`Reading ${inputPath}...`);
     try {
-      await access4(inputPath);
+      await access5(inputPath);
     } catch {
       spinner?.fail(`File not found: ${inputPath}`);
       console.error(chalk.red(`Error: Input file not found: ${inputPath}`));
@@ -2839,6 +3119,19 @@ async function executeConvert(inputPath, options) {
       configPath = await configLoader.findConfig(dirname2(inputPath));
     }
     const config = await configLoader.load(configPath);
+    const configDir = configPath ? dirname2(configPath) : dirname2(inputPath);
+    if (!isAbsolute(config.icons.fetched)) {
+      config.icons.fetched = resolve(configDir, config.icons.fetched);
+    }
+    if (!isAbsolute(config.icons.registry)) {
+      config.icons.registry = resolve(configDir, config.icons.registry);
+    }
+    if (!isAbsolute(config.templates.builtin)) {
+      config.templates.builtin = resolve(configDir, config.templates.builtin);
+    }
+    if (config.templates.custom && !isAbsolute(config.templates.custom)) {
+      config.templates.custom = resolve(configDir, config.templates.custom);
+    }
     if (options.references === false) {
       config.references.enabled = false;
     }
@@ -2942,16 +3235,16 @@ var init_convert = __esm({
 
 // src/cli/utils/marp-runner.ts
 import { existsSync } from "fs";
-import { join as join8, resolve, dirname as dirname4 } from "path";
+import { join as join9, resolve as resolve2, dirname as dirname4 } from "path";
 import {
   execFileSync,
   spawn
 } from "child_process";
 function getMarpCommand(projectDir) {
-  const startDir = resolve(projectDir ?? process.cwd());
+  const startDir = resolve2(projectDir ?? process.cwd());
   let currentDir = startDir;
   while (true) {
-    const localMarp = join8(currentDir, "node_modules", ".bin", "marp");
+    const localMarp = join9(currentDir, "node_modules", ".bin", "marp");
     if (existsSync(localMarp)) {
       return localMarp;
     }
@@ -3013,13 +3306,20 @@ function parseMarpBrowserError(errorOutput) {
   }
   return null;
 }
+function addHtmlOption(args) {
+  if (args.includes("--html") || args.includes("--no-html")) {
+    return args;
+  }
+  return ["--html", ...args];
+}
 function runMarp(args, options = {}) {
   const { projectDir, ...execOptions } = options;
   const marpCmd = getMarpCommand(projectDir);
   if (!marpCmd) {
     throw new Error("Marp CLI not found. Install it with: npm install -D @marp-team/marp-cli");
   }
-  execFileSync(marpCmd, args, execOptions);
+  const finalArgs = addHtmlOption(args);
+  execFileSync(marpCmd, finalArgs, execOptions);
 }
 function spawnMarp(args, options = {}) {
   const { projectDir, ...spawnOptions } = options;
@@ -3027,7 +3327,8 @@ function spawnMarp(args, options = {}) {
   if (!marpCmd) {
     throw new Error("Marp CLI not found. Install it with: npm install -D @marp-team/marp-cli");
   }
-  return spawn(marpCmd, args, spawnOptions);
+  const finalArgs = addHtmlOption(args);
+  return spawn(marpCmd, finalArgs, spawnOptions);
 }
 var init_marp_runner = __esm({
   "src/cli/utils/marp-runner.ts"() {
@@ -3051,17 +3352,17 @@ __export(screenshot_exports, {
   generateContactSheet: () => generateContactSheet
 });
 import { Command as Command4 } from "commander";
-import { access as access7, mkdir as mkdir3, readdir as readdir5, rename, unlink as unlink2 } from "fs/promises";
-import { basename as basename5, dirname as dirname6, extname as extname3, join as join10 } from "path";
+import { access as access8, mkdir as mkdir4, readdir as readdir5, rename, unlink as unlink2 } from "fs/promises";
+import { basename as basename5, dirname as dirname6, extname as extname3, join as join11 } from "path";
 import chalk4 from "chalk";
 import ora3 from "ora";
 import sharp2 from "sharp";
 async function filterToSpecificSlide(outputDir, baseName, slideNumber, format) {
   const slideStr = slideNumber.toString().padStart(3, "0");
   const targetFileName = `${baseName}.${slideStr}.${format}`;
-  const targetPath = join10(outputDir, targetFileName);
+  const targetPath = join11(outputDir, targetFileName);
   try {
-    await access7(targetPath);
+    await access8(targetPath);
   } catch {
     return {
       success: false,
@@ -3074,7 +3375,7 @@ async function filterToSpecificSlide(outputDir, baseName, slideNumber, format) {
   );
   for (const file of slideFiles) {
     if (file !== targetFileName) {
-      await unlink2(join10(outputDir, file));
+      await unlink2(join11(outputDir, file));
     }
   }
   return {
@@ -3091,8 +3392,8 @@ async function ensureFileExtensions(outputDir, baseName, format) {
   const renamedFiles = [];
   for (const file of files) {
     if (file.startsWith(baseName) && slidePattern.test(file)) {
-      const oldPath = join10(outputDir, file);
-      const newPath = join10(outputDir, `${file}.${format}`);
+      const oldPath = join11(outputDir, file);
+      const newPath = join11(outputDir, `${file}.${format}`);
       await rename(oldPath, newPath);
       renamedFiles.push(`${file}.${format}`);
     }
@@ -3186,14 +3487,14 @@ function formatAiOutput(options) {
     ""
   ];
   for (const file of files) {
-    lines.push(`  ${join10(outputDir, file)}`);
+    lines.push(`  ${join11(outputDir, file)}`);
   }
   lines.push("");
   lines.push(`Estimated tokens: ~${totalTokens} (${files.length} ${imageLabel})`);
   if (files.length > 0) {
     lines.push("");
     lines.push("To review in Claude Code:");
-    lines.push(`  Read ${join10(outputDir, files[0])}`);
+    lines.push(`  Read ${join11(outputDir, files[0])}`);
   }
   return lines.join("\n");
 }
@@ -3211,7 +3512,7 @@ function buildMarpCommandArgs(markdownPath, outputDir, options) {
     args.push("--jpeg-quality", String(quality));
   }
   const mdBaseName = basename5(markdownPath, extname3(markdownPath));
-  const outputPath = join10(outputDir, mdBaseName);
+  const outputPath = join11(outputDir, mdBaseName);
   args.push("-o", outputPath);
   args.push(markdownPath);
   return args;
@@ -3226,7 +3527,7 @@ async function executeScreenshot(inputPath, options) {
   const spinner = options.verbose ? null : ora3();
   const outputDir = options.output || "./screenshots";
   try {
-    await access7(inputPath);
+    await access8(inputPath);
   } catch {
     const message = `File not found: ${inputPath}`;
     console.error(chalk4.red(`Error: ${message}`));
@@ -3252,7 +3553,7 @@ async function executeScreenshot(inputPath, options) {
   }
   spinner?.succeed("Marp CLI found");
   try {
-    await mkdir3(outputDir, { recursive: true });
+    await mkdir4(outputDir, { recursive: true });
   } catch {
     const message = `Failed to create output directory: ${outputDir}`;
     console.error(chalk4.red(`Error: ${message}`));
@@ -3359,7 +3660,7 @@ Error: ${browserError.message}
   const generatedFiles = allFiles.filter((f) => f.startsWith(mdBaseName) && f.endsWith(`.${actualFormat}`)).sort();
   if (generatedFiles.length > 0) {
     try {
-      const metadata = await sharp2(join10(outputDir, generatedFiles[0])).metadata();
+      const metadata = await sharp2(join11(outputDir, generatedFiles[0])).metadata();
       if (metadata.width && metadata.height) {
         actualWidth = metadata.width;
         actualHeight = metadata.height;
@@ -3370,10 +3671,10 @@ Error: ${browserError.message}
   if (options.contactSheet && generatedFiles.length > 0) {
     spinner?.start("Generating contact sheet...");
     const slides = generatedFiles.map((file, index) => ({
-      path: join10(outputDir, file),
+      path: join11(outputDir, file),
       index: index + 1
     }));
-    const contactSheetPath = join10(outputDir, `${mdBaseName}-contact.png`);
+    const contactSheetPath = join11(outputDir, `${mdBaseName}-contact.png`);
     const contactResult = await generateContactSheet(slides, {
       outputPath: contactSheetPath,
       columns: options.columns || 2,
@@ -3433,13 +3734,9 @@ init_transformer();
 init_renderer();
 init_pipeline();
 
-// src/templates/index.ts
-init_engine();
-init_loader();
-init_validators();
-
 // src/index.ts
-var VERSION = "0.7.0";
+init_templates();
+var VERSION = "0.8.1";
 
 // src/cli/index.ts
 init_convert();
@@ -3451,11 +3748,11 @@ init_registry();
 init_loader2();
 init_convert();
 import { Command as Command2 } from "commander";
-import { access as access5, readFile as readFile9 } from "fs/promises";
+import { access as access6, readFile as readFile10 } from "fs/promises";
 import { dirname as dirname3 } from "path";
 import chalk2 from "chalk";
 import ora2 from "ora";
-import { parse as parseYaml6, stringify as yamlStringify } from "yaml";
+import { parse as parseYaml7, stringify as yamlStringify } from "yaml";
 
 // src/references/index.ts
 init_extractor();
@@ -3696,7 +3993,7 @@ async function executeValidate(inputPath, options) {
   try {
     spinner?.start(`Validating ${inputPath}...`);
     try {
-      await access5(inputPath);
+      await access6(inputPath);
     } catch {
       spinner?.fail(`File not found: ${inputPath}`);
       result.errors.push(`File not found: ${inputPath}`);
@@ -3705,9 +4002,9 @@ async function executeValidate(inputPath, options) {
       process.exitCode = ExitCode.FileReadError;
       return;
     }
-    const content = await readFile9(inputPath, "utf-8");
+    const content = await readFile10(inputPath, "utf-8");
     try {
-      parseYaml6(content);
+      parseYaml7(content);
       result.stats.yamlSyntax = true;
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
@@ -4028,15 +4325,16 @@ function outputResult(result, options) {
 }
 
 // src/cli/commands/templates.ts
+init_templates();
+init_loader2();
+init_pipeline();
+init_convert();
 import { Command as Command5 } from "commander";
 import chalk5 from "chalk";
 import * as yaml2 from "yaml";
-import { mkdir as mkdir4, writeFile as writeFile3, rm as rm2, readdir as readdir6 } from "fs/promises";
-import { join as join11, basename as basename6 } from "path";
+import { mkdir as mkdir5, writeFile as writeFile4, rm as rm2, readdir as readdir6 } from "fs/promises";
+import { join as join12, basename as basename6 } from "path";
 import { tmpdir as tmpdir2 } from "os";
-init_loader2();
-init_pipeline();
-init_convert();
 
 // src/cli/commands/preview.ts
 init_pipeline();
@@ -4044,9 +4342,9 @@ init_loader2();
 init_convert();
 init_marp_runner();
 import { Command as Command3 } from "commander";
-import { access as access6, readdir as readdir4, mkdir as mkdir2, writeFile as writeFile2, readFile as readFile10, rm } from "fs/promises";
-import { basename as basename4, dirname as dirname5, join as join9, extname as extname2 } from "path";
-import * as path6 from "path";
+import { access as access7, readdir as readdir4, mkdir as mkdir3, writeFile as writeFile3, readFile as readFile11, rm } from "fs/promises";
+import { basename as basename4, dirname as dirname5, join as join10, extname as extname2 } from "path";
+import * as path7 from "path";
 import { tmpdir } from "os";
 import { createServer } from "http";
 import chalk3 from "chalk";
@@ -4164,7 +4462,7 @@ async function collectSlideInfo(dir, baseName, format) {
       if (match) {
         const index = parseInt(match[1], 10);
         slides.push({
-          path: join9(dir, file),
+          path: join10(dir, file),
           title: `Slide ${index}`,
           index
         });
@@ -4180,7 +4478,7 @@ async function checkMarpCliAvailable(projectDir) {
 }
 function getTempPreviewDir(inputPath) {
   const base = basename4(inputPath, ".yaml");
-  return join9(tmpdir(), `slide-gen-preview-${base}-${Date.now()}`);
+  return join10(tmpdir(), `slide-gen-preview-${base}-${Date.now()}`);
 }
 function buildMarpCommand(markdownDir, options) {
   const parts = ["marp", "--server", "-I", markdownDir];
@@ -4190,7 +4488,7 @@ function buildMarpCommand(markdownDir, options) {
   return parts.join(" ");
 }
 function startStaticServer(baseDir, port, options = {}) {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     const mimeTypes = {
       ".html": "text/html",
       ".png": "image/png",
@@ -4203,8 +4501,8 @@ function startStaticServer(baseDir, port, options = {}) {
       try {
         const urlPath = new URL(req.url || "/", `http://localhost`).pathname;
         const requestedPath = urlPath === "/" ? "/index.html" : urlPath;
-        const resolvedBaseDir = path6.resolve(baseDir);
-        const filePath = path6.resolve(baseDir, "." + requestedPath);
+        const resolvedBaseDir = path7.resolve(baseDir);
+        const filePath = path7.resolve(baseDir, "." + requestedPath);
         if (!filePath.startsWith(resolvedBaseDir + "/") && filePath !== resolvedBaseDir) {
           res.writeHead(403);
           res.end("Forbidden");
@@ -4212,7 +4510,7 @@ function startStaticServer(baseDir, port, options = {}) {
         }
         const ext = extname2(filePath);
         const contentType = mimeTypes[ext] || "application/octet-stream";
-        const data = await readFile10(filePath);
+        const data = await readFile11(filePath);
         res.writeHead(200, { "Content-Type": contentType });
         res.end(data);
       } catch {
@@ -4227,16 +4525,16 @@ function startStaticServer(baseDir, port, options = {}) {
         const prefix = options.messagePrefix ?? "Server";
         console.log(`${prefix} running at ${chalk3.cyan(url)}`);
       }
-      resolve8(server);
+      resolve9(server);
     });
   });
 }
 async function executeGalleryPreview(inputPath, options) {
   const errors = [];
   const port = Number(options.port) || 8080;
-  const galleryDir = join9(tmpdir(), `slide-gen-gallery-${Date.now()}`);
+  const galleryDir = join10(tmpdir(), `slide-gen-gallery-${Date.now()}`);
   try {
-    await access6(inputPath);
+    await access7(inputPath);
   } catch {
     console.error(chalk3.red(`Error: File not found: ${inputPath}`));
     errors.push(`File not found: ${inputPath}`);
@@ -4257,7 +4555,7 @@ async function executeGalleryPreview(inputPath, options) {
     return { success: false, errors };
   }
   console.log(chalk3.green("\u2713") + " Marp CLI found");
-  await mkdir2(galleryDir, { recursive: true });
+  await mkdir3(galleryDir, { recursive: true });
   const configLoader = new ConfigLoader();
   let configPath = options.config;
   if (!configPath) {
@@ -4276,7 +4574,7 @@ async function executeGalleryPreview(inputPath, options) {
     await rm(galleryDir, { recursive: true, force: true });
     return { success: false, errors };
   }
-  const tempMdPath = join9(galleryDir, "slides.md");
+  const tempMdPath = join10(galleryDir, "slides.md");
   console.log(`Converting ${chalk3.cyan(inputPath)}...`);
   try {
     await pipeline.runWithResult(inputPath, { outputPath: tempMdPath });
@@ -4317,7 +4615,7 @@ async function executeGalleryPreview(inputPath, options) {
     path: basename4(s.path)
   }));
   const galleryHtml = generateGalleryHtml(relativeSlides);
-  await writeFile2(join9(galleryDir, "index.html"), galleryHtml);
+  await writeFile3(join10(galleryDir, "index.html"), galleryHtml);
   console.log(`
 Starting gallery server on port ${chalk3.cyan(port)}...`);
   let server;
@@ -4359,11 +4657,11 @@ Showing ${slides.length} slides in gallery mode`);
   };
   process.on("SIGINT", signalHandler);
   process.on("SIGTERM", signalHandler);
-  await new Promise((resolve8) => {
+  await new Promise((resolve9) => {
     if (options.signal) {
-      options.signal.addEventListener("abort", () => resolve8());
+      options.signal.addEventListener("abort", () => resolve9());
     }
-    server.on("close", () => resolve8());
+    server.on("close", () => resolve9());
   });
   return { success: true, errors };
 }
@@ -4381,7 +4679,7 @@ async function executePreview(inputPath, options) {
   const port = Number(options.port) || 8080;
   if (options.signal?.aborted) {
     try {
-      await access6(inputPath);
+      await access7(inputPath);
     } catch {
       errors.push(`File not found: ${inputPath}`);
       return { success: false, errors };
@@ -4389,7 +4687,7 @@ async function executePreview(inputPath, options) {
     return { success: true, errors };
   }
   try {
-    await access6(inputPath);
+    await access7(inputPath);
   } catch {
     console.error(chalk3.red(`Error: File not found: ${inputPath}`));
     errors.push(`File not found: ${inputPath}`);
@@ -4427,8 +4725,8 @@ async function executePreview(inputPath, options) {
     return { success: false, errors };
   }
   const tempDir = getTempPreviewDir(inputPath);
-  await mkdir2(tempDir, { recursive: true });
-  const tempMarkdownPath = join9(tempDir, "slides.md");
+  await mkdir3(tempDir, { recursive: true });
+  const tempMarkdownPath = join10(tempDir, "slides.md");
   console.log(`Converting ${chalk3.cyan(inputPath)}...`);
   try {
     await pipeline.runWithResult(inputPath, { outputPath: tempMarkdownPath });
@@ -4514,13 +4812,13 @@ Watching ${chalk3.cyan(inputPath)} for changes...`);
   };
   process.on("SIGINT", signalHandler);
   process.on("SIGTERM", signalHandler);
-  await new Promise((resolve8) => {
+  await new Promise((resolve9) => {
     marpProcess.on("exit", () => {
       cleanup();
-      resolve8();
+      resolve9();
     });
     if (options.signal) {
-      options.signal.addEventListener("abort", () => resolve8());
+      options.signal.addEventListener("abort", () => resolve9());
     }
   });
   return {
@@ -4944,7 +5242,7 @@ async function executeTemplatePreview(name, options) {
     return;
   }
   const port = Number(options.port) || 8080;
-  const previewDir = join11(tmpdir2(), `slide-gen-template-preview-${Date.now()}`);
+  const previewDir = join12(tmpdir2(), `slide-gen-template-preview-${Date.now()}`);
   console.log("Checking for Marp CLI...");
   const marpAvailable = await checkMarpCliAvailable();
   if (!marpAvailable) {
@@ -4981,7 +5279,7 @@ async function executeTemplatePreview(name, options) {
     return;
   }
   console.log(`Found ${templates.length} template(s) to preview`);
-  await mkdir4(previewDir, { recursive: true });
+  await mkdir5(previewDir, { recursive: true });
   console.log("Initializing pipeline...");
   const pipeline = new Pipeline(config);
   try {
@@ -4997,9 +5295,9 @@ async function executeTemplatePreview(name, options) {
   for (const template of templates) {
     console.log(`Processing template: ${chalk5.cyan(template.name)}...`);
     const sampleYaml = generateSampleYaml(template);
-    const yamlPath = join11(previewDir, `${template.name}.yaml`);
-    await writeFile3(yamlPath, sampleYaml);
-    const mdPath = join11(previewDir, `${template.name}.md`);
+    const yamlPath = join12(previewDir, `${template.name}.yaml`);
+    await writeFile4(yamlPath, sampleYaml);
+    const mdPath = join12(previewDir, `${template.name}.md`);
     try {
       await pipeline.runWithResult(yamlPath, { outputPath: mdPath });
     } catch (error) {
@@ -5032,7 +5330,7 @@ async function executeTemplatePreview(name, options) {
     return;
   }
   const previewHtml = generateTemplatePreviewHtml(templatePreviews);
-  await writeFile3(join11(previewDir, "index.html"), previewHtml);
+  await writeFile4(join12(previewDir, "index.html"), previewHtml);
   console.log(`
 Starting preview server on port ${chalk5.cyan(port)}...`);
   let server;
@@ -5069,8 +5367,8 @@ Showing ${templatePreviews.length} template preview(s)`);
   };
   process.on("SIGINT", signalHandler);
   process.on("SIGTERM", signalHandler);
-  await new Promise((resolve8) => {
-    server.on("close", () => resolve8());
+  await new Promise((resolve9) => {
+    server.on("close", () => resolve9());
   });
 }
 function createScreenshotSubcommand() {
@@ -5114,7 +5412,7 @@ async function executeTemplateScreenshot(name, options) {
     return { success: true, errors: [], files: [] };
   }
   const outputDir = options.output || "./template-screenshots";
-  await mkdir4(outputDir, { recursive: true });
+  await mkdir5(outputDir, { recursive: true });
   const configLoader = new ConfigLoader();
   const configPath = options.config || await configLoader.findConfig(process.cwd());
   const config = await configLoader.load(configPath);
@@ -5127,8 +5425,8 @@ async function executeTemplateScreenshot(name, options) {
     process.exitCode = ExitCode.GeneralError;
     return { success: false, errors: [message] };
   }
-  const tempDir = join11(tmpdir2(), `slide-gen-template-screenshot-${Date.now()}`);
-  await mkdir4(tempDir, { recursive: true });
+  const tempDir = join12(tmpdir2(), `slide-gen-template-screenshot-${Date.now()}`);
+  await mkdir5(tempDir, { recursive: true });
   const isAiFormat = options.format === "ai";
   const imageFormat = isAiFormat ? "jpeg" : options.format || "png";
   const imageWidth = isAiFormat ? 640 : options.width || 1280;
@@ -5139,9 +5437,9 @@ async function executeTemplateScreenshot(name, options) {
       console.log(`Processing: ${template.name}`);
     }
     const sampleYaml = generateSampleYaml(template);
-    const yamlPath = join11(tempDir, `${template.name}.yaml`);
-    await writeFile3(yamlPath, sampleYaml);
-    const mdPath = join11(tempDir, `${template.name}.md`);
+    const yamlPath = join12(tempDir, `${template.name}.yaml`);
+    await writeFile4(yamlPath, sampleYaml);
+    const mdPath = join12(tempDir, `${template.name}.md`);
     try {
       await pipeline.runWithResult(yamlPath, { outputPath: mdPath });
     } catch (error) {
@@ -5158,7 +5456,7 @@ async function executeTemplateScreenshot(name, options) {
     if (imageFormat === "jpeg") {
       marpArgs.push("--jpeg-quality", String(options.quality || 80));
     }
-    const outputBasePath = join11(tempDir, template.name);
+    const outputBasePath = join12(tempDir, template.name);
     marpArgs.push("-o", outputBasePath);
     marpArgs.push(mdPath);
     try {
@@ -5178,7 +5476,7 @@ async function executeTemplateScreenshot(name, options) {
       (f) => f.startsWith(template.name) && f.endsWith(`.${imageFormat}`)
     );
     for (const slideFile of slideFiles) {
-      const sourceFile = join11(tempDir, slideFile);
+      const sourceFile = join12(tempDir, slideFile);
       const match = slideFile.match(/\.(\d{3})\.\w+$/);
       let targetName;
       if (slideFiles.length === 1 || !match) {
@@ -5186,7 +5484,7 @@ async function executeTemplateScreenshot(name, options) {
       } else {
         targetName = slideFile;
       }
-      const targetFile = join11(outputDir, targetName);
+      const targetFile = join12(outputDir, targetName);
       const { copyFile: fsCopyFile } = await import("fs/promises");
       await fsCopyFile(sourceFile, targetFile);
       generatedFiles.push(targetName);
@@ -5198,10 +5496,10 @@ async function executeTemplateScreenshot(name, options) {
     console.log("Generating contact sheet...");
     const { generateContactSheet: genContactSheet } = await Promise.resolve().then(() => (init_screenshot(), screenshot_exports));
     const slides = generatedFiles.map((file, index) => ({
-      path: join11(outputDir, file),
+      path: join12(outputDir, file),
       index: index + 1
     }));
-    const contactSheetPath = join11(outputDir, `templates-contact.${imageFormat === "jpeg" ? "jpeg" : "png"}`);
+    const contactSheetPath = join12(outputDir, `templates-contact.${imageFormat === "jpeg" ? "jpeg" : "png"}`);
     const contactResult = await genContactSheet(slides, {
       outputPath: contactSheetPath,
       columns: options.columns || 3,
@@ -5224,7 +5522,7 @@ async function executeTemplateScreenshot(name, options) {
     console.log("Screenshots saved (AI-optimized):");
     console.log("");
     for (const file of generatedFiles) {
-      console.log(`  ${join11(outputDir, file)}`);
+      console.log(`  ${join12(outputDir, file)}`);
     }
     console.log("");
     console.log(`Estimated tokens: ~${totalTokens} (${generatedFiles.length} images)`);
@@ -5252,194 +5550,14 @@ function createTemplatesCommand() {
 // src/cli/commands/icons.ts
 init_registry();
 init_resolver();
+init_fetcher();
+init_loader2();
+init_convert();
 import { Command as Command6 } from "commander";
 import chalk6 from "chalk";
 import * as fs8 from "fs/promises";
 import * as path8 from "path";
 import { parse as parseYaml8, stringify as stringifyYaml2 } from "yaml";
-
-// src/icons/fetcher.ts
-import * as fs7 from "fs/promises";
-import * as path7 from "path";
-import { stringify as stringifyYaml, parse as parseYaml7 } from "yaml";
-var ICON_SOURCES = {
-  health: { set: "healthicons", license: "MIT", external: true },
-  ms: { set: "material-symbols", license: "Apache-2.0", external: true },
-  hero: { set: "heroicons", license: "MIT", external: true },
-  mi: { set: "material-icons", license: "Apache-2.0", external: false },
-  mdi: { set: "mdi", license: "Apache-2.0", external: true },
-  iconify: { set: "iconify", license: "Various", external: true }
-};
-function isExternalSource(prefix) {
-  return ICON_SOURCES[prefix]?.external ?? false;
-}
-var VALID_ICON_NAME = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/i;
-var VALID_ICON_NAME_WITH_PATH = /^[a-z0-9][a-z0-9-/]*[a-z0-9]$|^[a-z0-9]$/i;
-function isValidIconName(name, allowPath = false) {
-  if (!name || name.length > 100) {
-    return false;
-  }
-  if (name.includes("..") || name.startsWith("/") || name.endsWith("/")) {
-    return false;
-  }
-  const pattern = allowPath ? VALID_ICON_NAME_WITH_PATH : VALID_ICON_NAME;
-  return pattern.test(name);
-}
-var IconFetcher = class {
-  fetchedDir;
-  saveLocally;
-  timeoutMs;
-  constructor(options = {}) {
-    this.fetchedDir = options.fetchedDir ?? "icons/fetched";
-    this.saveLocally = options.saveLocally ?? true;
-    this.timeoutMs = options.timeoutMs ?? 1e4;
-  }
-  /**
-   * Parse an icon reference string (e.g., "health:stethoscope")
-   * Returns null if the format is invalid or contains unsafe characters
-   */
-  parseReference(iconRef) {
-    const colonIndex = iconRef.indexOf(":");
-    if (colonIndex === -1) {
-      return null;
-    }
-    const prefix = iconRef.substring(0, colonIndex);
-    const name = iconRef.substring(colonIndex + 1);
-    if (!/^[a-z0-9]+$/i.test(prefix)) {
-      return null;
-    }
-    if (!isValidIconName(name)) {
-      return null;
-    }
-    return { prefix, name };
-  }
-  /**
-   * Get the Iconify set name for a prefix
-   */
-  getIconifySet(prefix) {
-    return ICON_SOURCES[prefix]?.set ?? prefix;
-  }
-  /**
-   * Get the local file path for an icon reference
-   */
-  getLocalPath(iconRef) {
-    const parsed = this.parseReference(iconRef);
-    if (!parsed) {
-      throw new Error(`Invalid icon reference: ${iconRef}`);
-    }
-    const setDir = this.getIconifySet(parsed.prefix);
-    return path7.join(this.fetchedDir, setDir, `${parsed.name}.svg`);
-  }
-  /**
-   * Check if an icon exists locally
-   */
-  async existsLocally(iconRef) {
-    const localPath = this.getLocalPath(iconRef);
-    try {
-      await fs7.access(localPath);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  /**
-   * Build the Iconify API URL for an icon
-   */
-  buildUrl(prefix, name) {
-    const set = this.getIconifySet(prefix);
-    return `https://api.iconify.design/${set}/${name}.svg`;
-  }
-  /**
-   * Resolve an icon reference (local first, then fetch)
-   */
-  async resolve(iconRef) {
-    if (await this.existsLocally(iconRef)) {
-      const localPath = this.getLocalPath(iconRef);
-      return await fs7.readFile(localPath, "utf-8");
-    }
-    return await this.fetchAndSave(iconRef);
-  }
-  /**
-   * Fetch an icon from external source and save locally
-   */
-  async fetchAndSave(iconRef) {
-    const parsed = this.parseReference(iconRef);
-    if (!parsed) {
-      throw new Error(`Invalid icon reference: ${iconRef}`);
-    }
-    const url = this.buildUrl(parsed.prefix, parsed.name);
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
-    let response;
-    try {
-      response = await fetch(url, { signal: controller.signal });
-    } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") {
-        throw new Error(`Fetch timeout: ${iconRef} (exceeded ${this.timeoutMs}ms)`);
-      }
-      throw error;
-    } finally {
-      clearTimeout(timeoutId);
-    }
-    if (!response.ok) {
-      throw new Error(`Icon not found: ${iconRef} (HTTP ${response.status})`);
-    }
-    const svg = await response.text();
-    if (this.saveLocally) {
-      await this.saveLocallyInternal(parsed.prefix, parsed.name, svg, url);
-    }
-    return svg;
-  }
-  /**
-   * Save icon to local filesystem
-   */
-  async saveLocallyInternal(prefix, name, svg, sourceUrl) {
-    const setDir = this.getIconifySet(prefix);
-    const dirPath = path7.join(this.fetchedDir, setDir);
-    const filePath = path7.join(dirPath, `${name}.svg`);
-    await fs7.mkdir(dirPath, { recursive: true });
-    await fs7.writeFile(filePath, svg, "utf-8");
-    await this.updateSourcesYaml(setDir, name, sourceUrl);
-  }
-  /**
-   * Update _sources.yaml with source information
-   */
-  async updateSourcesYaml(setDir, name, sourceUrl) {
-    const sourcesPath = path7.join(this.fetchedDir, "_sources.yaml");
-    let sources = {};
-    try {
-      const content = await fs7.readFile(sourcesPath, "utf-8");
-      sources = parseYaml7(content) ?? {};
-    } catch {
-    }
-    const key = `${setDir}/${name}.svg`;
-    sources[key] = {
-      source: sourceUrl,
-      fetched_at: (/* @__PURE__ */ new Date()).toISOString(),
-      license: this.getLicense(setDir)
-    };
-    const header = `# Fetched icon sources
-# This file tracks where icons were fetched from for traceability
-
-`;
-    await fs7.writeFile(sourcesPath, header + stringifyYaml(sources), "utf-8");
-  }
-  /**
-   * Get the license for an icon set
-   */
-  getLicense(setDir) {
-    for (const config of Object.values(ICON_SOURCES)) {
-      if (config.set === setDir) {
-        return config.license;
-      }
-    }
-    return "Unknown";
-  }
-};
-
-// src/cli/commands/icons.ts
-init_loader2();
-init_convert();
 function extractIconReferences(presentation) {
   const icons = /* @__PURE__ */ new Set();
   function extractFromValue(value) {
@@ -6040,7 +6158,7 @@ import { mkdir as mkdir8, writeFile as writeFile7, access as access11, readdir a
 import { existsSync as existsSync2 } from "fs";
 import { execSync, spawnSync } from "child_process";
 import { createInterface } from "readline";
-import { basename as basename8, dirname as dirname8, join as join17, resolve as resolve6, sep } from "path";
+import { basename as basename8, dirname as dirname8, join as join17, resolve as resolve7, sep } from "path";
 import { fileURLToPath } from "url";
 import chalk7 from "chalk";
 import ora4 from "ora";
@@ -7014,6 +7132,73 @@ Take new screenshots and verify improvements.
 7. \`Read ./screenshots/presentation.003.jpeg\`
 8. Verify fix, move to next slide
 
+## Custom Template Creation
+
+When creating or modifying templates, follow these critical rules.
+
+### Critical Rules
+
+#### 1. CSS Selectors (Marp Scoping)
+
+When using \`<!-- _class: foo -->\`:
+- The class is added to \`<section>\` element itself
+- Use \`section.foo\` when targeting the \`<section>\` element itself
+
+\`\`\`yaml
+# Correct
+output: |
+  <!-- _class: my-slide -->
+  <div class="container">...</div>
+
+css: |
+  section.my-slide .container { display: flex; }
+\`\`\`
+
+\`\`\`yaml
+# WRONG - This does not target the section element itself
+css: |
+  .my-slide .container { display: flex; }
+\`\`\`
+
+Note: \`.my-slide .container\` is valid for descendants inside the section, but it does not target the \`<section>\` element itself.
+
+#### 2. HTML + Markdown (CommonMark)
+
+Markdown inside HTML is only parsed with blank lines:
+
+\`\`\`yaml
+# Correct - blank line after <div>
+output: |
+  <div class="container">
+
+  ## Heading works
+  - List works
+
+  </div>
+\`\`\`
+
+\`\`\`yaml
+# WRONG - no blank line, Markdown won't parse
+output: |
+  <div class="container">
+  ## This is plain text
+  - Not a list
+  </div>
+\`\`\`
+
+### Visual Regression Test (Required)
+
+After creating/modifying templates, ALWAYS verify with screenshots:
+
+\`\`\`bash
+slide-gen templates screenshot <template-name> --format png -o /tmp/test
+\`\`\`
+
+**Check that:**
+- Layout is correct (columns, grids, flexbox)
+- Markdown is parsed (headings, lists rendered properly)
+- CSS is not silently failing
+
 ## Reference Management
 
 For academic presentations, manage citations and references:
@@ -7312,6 +7497,92 @@ Image with text side by side.
 - \`items\` or \`text\`: Content (required)
 
 ## Run \`slide-gen templates list --format llm\` for full list.
+
+---
+
+## Creating Custom Templates
+
+### Template File Structure
+
+\`\`\`yaml
+name: my-template
+description: "Description for LLM"
+category: custom
+
+schema:
+  type: object
+  required: [title]
+  properties:
+    title: { type: string }
+    content: { type: string }
+
+example:
+  title: "Sample"
+  content: "Sample content"
+
+output: |
+  ---
+  <!-- _class: my-template -->
+
+  # {{ title }}
+
+  <div class="content">
+
+  {{ content }}
+
+  </div>
+
+css: |
+  section.my-template .content {
+    padding: 1em;
+  }
+\`\`\`
+
+### Critical CSS Rule: Marp Scoping
+
+When using \`<!-- _class: foo -->\`, Marp adds class to the \`<section>\` element.
+
+**Correct (targeting the section element):**
+\`\`\`css
+section.foo .child { ... }
+\`\`\`
+
+**Wrong (for targeting the section element):**
+\`\`\`css
+.foo .child { ... }
+\`\`\`
+
+Note: \`.foo .child\` is valid for descendants inside the section, but it does not target the \`<section>\` element itself.
+
+### Critical HTML Rule: CommonMark
+
+Markdown inside HTML only parses with blank lines after tags:
+
+**Correct:**
+\`\`\`html
+<div>
+
+## Heading works
+
+</div>
+\`\`\`
+
+**Wrong:**
+\`\`\`html
+<div>
+## Plain text, not heading
+</div>
+\`\`\`
+
+### Visual Verification
+
+Always test templates with screenshots:
+
+\`\`\`bash
+slide-gen templates screenshot <template-name> --format png -o /tmp/test
+\`\`\`
+
+Check: Layout, Markdown parsing, CSS application.
 `;
 }
 
@@ -7989,7 +8260,8 @@ slide-gen validate presentation.yaml
 // src/cli/commands/init.ts
 function getPackageRoot() {
   const __dirname = dirname8(fileURLToPath(import.meta.url));
-  if (__dirname.includes(`${sep}src${sep}`) || __dirname.includes("/src/")) {
+  const isInSourceDir = __dirname.endsWith(`${sep}src${sep}cli${sep}commands`) || __dirname.endsWith("/src/cli/commands");
+  if (isInSourceDir) {
     return join17(__dirname, "..", "..", "..");
   }
   return join17(__dirname, "..", "..");
@@ -8001,7 +8273,7 @@ function createInitCommand() {
 }
 async function executeInit(directory, options) {
   const spinner = ora4();
-  const targetDir = resolve6(directory);
+  const targetDir = resolve7(directory);
   const includeExamples = options.examples !== false;
   const includeAiConfig = options.aiConfig !== false;
   const includeSources = options.sources !== false;
@@ -8029,6 +8301,13 @@ async function executeInit(directory, options) {
     const sourceIconsRegistry = join17(packageRoot, "icons", "registry.yaml");
     const targetIconsRegistry = join17(targetDir, "icons", "registry.yaml");
     await copyFileIfNotExists(sourceIconsRegistry, targetIconsRegistry);
+    const sourceIconsFetched = join17(packageRoot, "icons", "fetched");
+    const targetIconsFetched = join17(targetDir, "icons", "fetched");
+    try {
+      await access11(targetIconsFetched);
+    } catch {
+      await cp(sourceIconsFetched, targetIconsFetched, { recursive: true });
+    }
     const sourceDefaultTheme = join17(packageRoot, "themes", "default.css");
     const targetDefaultTheme = join17(targetDir, "themes", "default.css");
     await copyFileIfNotExists(sourceDefaultTheme, targetDefaultTheme);
@@ -8050,11 +8329,11 @@ async function executeInit(directory, options) {
         await sourcesManager.init({
           name: "Untitled Project",
           setup_pattern: options.fromDirectory ? "A" : void 0,
-          original_source: options.fromDirectory ? resolve6(options.fromDirectory) : void 0
+          original_source: options.fromDirectory ? resolve7(options.fromDirectory) : void 0
         });
         if (options.fromDirectory) {
           const importer = new SourceImporter(targetDir, sourcesManager);
-          const result = await importer.importDirectory(resolve6(options.fromDirectory), {
+          const result = await importer.importDirectory(resolve7(options.fromDirectory), {
             recursive: true
           });
           sourcesImported = result.imported;
@@ -8160,16 +8439,16 @@ async function promptMarpInstallChoice() {
   console.log(`  ${chalk7.cyan("2)")} Local install ${chalk7.dim("(creates package.json)")}`);
   console.log(`  ${chalk7.cyan("3)")} Skip ${chalk7.dim("(I'll install it later)")}`);
   console.log("");
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     rl.question("Choice [1]: ", (answer) => {
       rl.close();
       const normalized = answer.trim();
       if (normalized === "" || normalized === "1") {
-        resolve8("global");
+        resolve9("global");
       } else if (normalized === "2") {
-        resolve8("local");
+        resolve9("local");
       } else {
-        resolve8("skip");
+        resolve9("skip");
       }
     });
   });
@@ -8341,10 +8620,8 @@ templates:
 icons:
   # Path to icon registry file
   registry: ./icons/registry.yaml
-  cache:
-    enabled: true
-    directory: .cache/icons
-    ttl: 86400
+  # Path to fetched/pre-bundled icon SVGs
+  fetched: ./icons/fetched
 
 references:
   enabled: true
@@ -8565,14 +8842,20 @@ async function executeWatch(inputPath, options) {
     }, debounceMs);
   };
   state.start();
+  const isWSL = !!process.env["WSL_DISTRO_NAME"];
   watcher = chokidarWatch2(inputPath, {
     persistent: true,
     ignoreInitial: true,
+    usePolling: isWSL,
+    ...isWSL && { interval: 100 },
     awaitWriteFinish: {
       stabilityThreshold: 100,
       pollInterval: 50
     }
   });
+  await new Promise((resolve9) => {
+    watcher.on("ready", resolve9);
+  });
   watcher.on("change", handleChange);
   const cleanup = () => {
     state.stop();
@@ -8591,9 +8874,9 @@ async function executeWatch(inputPath, options) {
   };
   process.on("SIGINT", signalHandler);
   process.on("SIGTERM", signalHandler);
-  await new Promise((resolve8) => {
+  await new Promise((resolve9) => {
     if (options.signal) {
-      options.signal.addEventListener("abort", () => resolve8());
+      options.signal.addEventListener("abort", () => resolve9());
     }
   });
   return {
@@ -9035,7 +9318,7 @@ init_screenshot();
 init_convert();
 import { Command as Command10 } from "commander";
 import { access as access13, stat as stat3 } from "fs/promises";
-import { resolve as resolve7 } from "path";
+import { resolve as resolve8 } from "path";
 import chalk10 from "chalk";
 import ora5 from "ora";
 function createSourcesCommand() {
@@ -9084,7 +9367,7 @@ function createSourcesSyncCommand() {
   });
 }
 async function executeSourcesInit(projectDir, options) {
-  const resolvedDir = resolve7(projectDir);
+  const resolvedDir = resolve8(projectDir);
   const spinner = ora5("Initializing sources...").start();
   try {
     const manager = new SourcesManager(resolvedDir);
@@ -9100,10 +9383,10 @@ async function executeSourcesInit(projectDir, options) {
     let originalSource;
     if (options.fromDirectory) {
       setupPattern = "A";
-      originalSource = resolve7(options.fromDirectory);
+      originalSource = resolve8(options.fromDirectory);
     } else if (options.fromFile) {
       setupPattern = "B";
-      originalSource = resolve7(options.fromFile);
+      originalSource = resolve8(options.fromFile);
     }
     await manager.init({
       name: projectName,
@@ -9114,14 +9397,14 @@ async function executeSourcesInit(projectDir, options) {
     if (options.fromDirectory) {
       const importer = new SourceImporter(resolvedDir, manager);
       const result = await importer.importDirectory(
-        resolve7(options.fromDirectory),
+        resolve8(options.fromDirectory),
         { recursive: true }
       );
       filesImported = result.imported;
     }
     if (options.fromFile) {
       const importer = new SourceImporter(resolvedDir, manager);
-      await importer.importFile(resolve7(options.fromFile), {
+      await importer.importFile(resolve8(options.fromFile), {
         type: "scenario"
       });
       filesImported = 1;
@@ -9146,8 +9429,8 @@ async function executeSourcesInit(projectDir, options) {
   }
 }
 async function executeSourcesImport(projectDir, sourcePath, options) {
-  const resolvedDir = resolve7(projectDir);
-  const resolvedSource = resolve7(sourcePath);
+  const resolvedDir = resolve8(projectDir);
+  const resolvedSource = resolve8(sourcePath);
   const spinner = ora5("Importing files...").start();
   try {
     const manager = new SourcesManager(resolvedDir);
@@ -9206,7 +9489,7 @@ async function executeSourcesImport(projectDir, sourcePath, options) {
   }
 }
 async function executeSourcesStatus(projectDir, _options) {
-  const resolvedDir = resolve7(projectDir);
+  const resolvedDir = resolve8(projectDir);
   try {
     const manager = new SourcesManager(resolvedDir);
     if (!await manager.exists()) {
@@ -9293,7 +9576,7 @@ async function executeSourcesStatus(projectDir, _options) {
   }
 }
 async function executeSourcesSync(projectDir, options) {
-  const resolvedDir = resolve7(projectDir);
+  const resolvedDir = resolve8(projectDir);
   try {
     const manager = new SourcesManager(resolvedDir);
     if (!await manager.exists()) {