tkeron 4.1.0 → 4.3.0

package/README.md

@@ -19,6 +19,7 @@ bun install -g tkeron
 - TypeScript → vanilla JavaScript
 - HTML components (`.com.html`) - inline at build time
 - TypeScript components (`.com.ts`) - dynamic generation
+- Markdown components (`.com.md`) - write content in Markdown, rendered to HTML at build time
 - Pre-rendering (`.pre.ts`) - DOM manipulation at build time
 - Dev server with hot reload
 - Zero config
@@ -72,6 +73,7 @@ document.getElementById("quote").textContent = data.content;
 - **[Getting Started](./docs/getting-started.md)** - Installation and first steps
 - **[HTML Components](./docs/components-html.md)** - Reusable markup with `.com.html`
 - **[TypeScript Components](./docs/components-typescript.md)** - Dynamic components with `.com.ts`
+- **[Markdown Components](./docs/components-markdown.md)** - Content in Markdown with `.com.md`
 - **[Pre-rendering](./docs/pre-rendering.md)** - Build-time HTML transformation
 - **[CLI Reference](./docs/cli-reference.md)** - All commands and options
 - **[Best Practices](./docs/best-practices.md)** - Patterns, limits, and anti-patterns

package/bun.lock

@@ -30,11 +30,11 @@
 
     "@types/bun": ["@types/bun@1.3.9", "", { "dependencies": { "bun-types": "1.3.9" } }, "sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw=="],
 
-    "@types/node": ["@types/node@25.1.0", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-t7frlewr6+cbx+9Ohpl0NOTKXZNV9xHRmNOvql47BFJKcEG1CxtxlPEEe+gR9uhVWM4DwhnvTF110mIL4yP9RA=="],
+    "@types/node": ["@types/node@25.3.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-4K3bqJpXpqfg2XKGK9bpDTc6xO/xoUP/RBWS7AtRMug6zZFaRekiLzjVtAoZMquxoAbzBvy5nxQ7veS5eYzf8A=="],
 
     "accepts": ["accepts@2.0.0", "", { "dependencies": { "mime-types": "^3.0.0", "negotiator": "^1.0.0" } }, "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng=="],
 
-    "ajv": ["ajv@8.17.1", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g=="],
+    "ajv": ["ajv@8.18.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
 
     "ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="],
 
@@ -110,7 +110,7 @@
 
     "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
 
-    "hono": ["hono@4.11.7", "", {}, "sha512-l7qMiNee7t82bH3SeyUCt9UF15EVmaBvsppY2zQtrbIhl/yzBTny+YUxsVjSjQ6gaqaeVtZmGocom8TzBlA4Yw=="],
+    "hono": ["hono@4.12.1", "", {}, "sha512-hi9afu8g0lfJVLolxElAZGANCTTl6bewIdsRNhaywfP9K8BPf++F2z6OLrYGIinUwpRKzbZHMhPwvc0ZEpAwGw=="],
 
     "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
 
@@ -166,7 +166,7 @@
 
     "proxy-addr": ["proxy-addr@2.0.7", "", { "dependencies": { "forwarded": "0.2.0", "ipaddr.js": "1.9.1" } }, "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg=="],
 
-    "qs": ["qs@6.14.1", "", { "dependencies": { "side-channel": "^1.1.0" } }, "sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ=="],
+    "qs": ["qs@6.15.0", "", { "dependencies": { "side-channel": "^1.1.0" } }, "sha512-mAZTtNCeetKMH+pSjrb76NAM8V9a05I9aBZOHztWy/UqcJdQYNsf59vrRKWnojAT9Y+GbIvoTBC++CPHqpDBhQ=="],
 
     "range-parser": ["range-parser@1.2.1", "", {}, "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg=="],
 
@@ -204,7 +204,7 @@
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
-    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
 
     "unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
 

package/changelog.md

@@ -1,3 +1,62 @@
+# v4.3.0
+
+## Markdown Components
+
+### New Features
+
+- **Added**: `.com.md` component type — write components in Markdown, rendered to HTML at build time using Bun's native `Bun.markdown.html()` API with full GFM support (headings, bold, italic, strikethrough, lists, tables, blockquotes, links, images, code)
+- **Added**: `src/processComMd.ts` — new processor following the same pattern as `processCom` and `processComTs`
+  - Circular dependency detection
+  - Max nesting depth (50 levels)
+  - Component resolution: local directory first, then root
+  - Returns `true` when changes were made (drives the build loop)
+
+### Breaking Changes (Build Behavior)
+
+- **Changed**: Component resolution priority is now enforced: `.com.ts` > `.com.html` > `.com.md`
+  - Previously the loop ran `processCom` (HTML) before `processComTs` (TS), giving `.com.html` effective priority over `.com.ts` when both existed for the same tag
+  - Now `.com.ts` is resolved first as intended
+  - **Impact**: If you had both a `.com.ts` and `.com.html` for the same component name and were relying on the `.com.html` being used, the `.com.ts` will now win
+
+### Documentation
+
+- **Added**: `docs/components-markdown.md` — full documentation for `.com.md` components including GFM features, naming rules, priority rules, and examples
+- **Updated**: `README.md` — `.com.md` added to features list and documentation links
+- **Updated**: `mcp-server.ts` — `tkeron://components-markdown` resource registered
+
+### Tests
+
+- **Added**: `tests/processComMd.test.ts` — 23 tests covering all behaviors
+- **Updated**: `tests/examples.test.ts` — updated `with_com_mixed_priority` tests to reflect correct `.com.ts` > `.com.html` priority
+
+---
+
+# v4.2.0
+
+## Developer Experience
+
+### New Features
+
+- **Added**: TypeScript configuration to `init_sample` example
+  - `tsconfig.json` - Minimal TypeScript configuration for IDE support
+  - `tkeron.d.ts` - Type definitions for `.com.ts` and `.pre.ts` files
+  - Enables IntelliSense for `com` variable in `.com.ts` files
+  - Enables IntelliSense for `document` variable in `.pre.ts` files
+  - Improves developer experience in VS Code and other IDEs
+
+### Bug Fixes
+
+- **Fixed**: Variable naming conflict in `init_sample/websrc/index.ts`
+  - Renamed `count` to `clickCount` to avoid TypeScript scope collision
+- **Fixed**: TypeScript type error in `init_sample/websrc/user-badge.com.ts`
+  - Added explicit `parseInt` radix parameter for type safety
+
+### Tests
+
+- **Updated**: Test expectations to match renamed variables in `init_sample`
+
+---
+
 # v4.1.0
 
 ## Documentation & Developer Experience

package/docs/components-markdown.md

@@ -0,0 +1,322 @@
+# Markdown Components
+
+Markdown components (`.com.md` files) let you write reusable content in Markdown that gets converted to HTML and inlined at build time. Powered by Bun's built-in Markdown parser with full GitHub Flavored Markdown (GFM) support.
+
+## Quick Start
+
+Create a file named with `.com.md` extension:
+
+```markdown
+<!-- hero-text.com.md -->
+
+# Welcome to My Site
+
+This is a **great** place to start.
+
+- Fast
+- Simple
+- Powerful
+```
+
+Use it with a matching custom element:
+
+```html
+<!-- index.html -->
+<hero-text></hero-text>
+```
+
+Build, and the custom element is replaced with the rendered HTML.
+
+## How They Work
+
+### 1. Component Naming
+
+Component filenames must:
+
+- End with `.com.md`
+- Match the custom element name (without `.com.md`)
+- Use lowercase with hyphens
+
+**Examples:**
+
+| Filename            | Custom Element | Valid?            |
+| ------------------- | -------------- | ----------------- |
+| `hero-text.com.md`  | `<hero-text>`  | ✅ Yes            |
+| `about-info.com.md` | `<about-info>` | ✅ Yes            |
+| `intro.com.md`      | `<intro>`      | ❌ No (no hyphen) |
+
+### 2. Component Resolution
+
+Tkeron looks for components in this order:
+
+1. **Same directory** as the file using it
+2. **Root directory** (`websrc/`)
+
+**Example structure:**
+
+```
+websrc/
+├── index.html
+├── site-intro.com.md         # Available to all files
+├── blog/
+│   ├── post.html
+│   └── post-footer.com.md    # Available only to blog/post.html
+```
+
+In `blog/post.html`:
+
+- `<post-footer>` → Finds `blog/post-footer.com.md` first
+- `<site-intro>` → Falls back to `websrc/site-intro.com.md`
+
+### 3. Component Priority
+
+When multiple component types exist for the same name, Tkeron uses this priority:
+
+1. **`.com.ts`** (TypeScript components — highest priority)
+2. **`.com.html`** (HTML components)
+3. **`.com.md`** (Markdown components — lowest priority)
+
+If both `hero-text.com.html` and `hero-text.com.md` exist, the `.com.html` version is used and `.com.md` is ignored.
+
+### 4. Build Process
+
+```
+Before Build (websrc/index.html):
+<hero-text></hero-text>
+
+After Build (web/index.html):
+<h1>Welcome</h1>
+<p>Some <strong>bold</strong> text</p>
+```
+
+The `.com.md` file is NOT copied to output — only its rendered HTML is inlined.
+
+## GFM Features
+
+Markdown components support all GitHub Flavored Markdown extensions out of the box:
+
+### Headings
+
+```markdown
+# Heading 1
+
+## Heading 2
+
+### Heading 3
+```
+
+### Bold, Italic, Strikethrough
+
+```markdown
+**bold text**
+_italic text_
+~~strikethrough~~
+```
+
+### Lists
+
+```markdown
+- Unordered item 1
+- Unordered item 2
+
+1. Ordered item 1
+2. Ordered item 2
+```
+
+### Links and Images
+
+```markdown
+[Link text](https://example.com)
+![Alt text](image.jpg)
+```
+
+### Tables
+
+```markdown
+| Feature  | Status |
+| -------- | ------ |
+| Tables   | ✅     |
+| Lists    | ✅     |
+| Headings | ✅     |
+```
+
+### Blockquotes
+
+```markdown
+> This is a blockquote
+> with multiple lines
+```
+
+### Code
+
+````markdown
+Inline `code` and fenced blocks:
+
+```js
+console.log("hello");
+```
+````
+
+## Basic Examples
+
+### About Section
+
+```markdown
+<!-- about-section.com.md -->
+
+## About Us
+
+We are a **small team** building great tools.
+
+- Open source
+- Community driven
+- Built with love
+```
+
+**Usage:**
+
+```html
+<about-section></about-section>
+```
+
+### Feature List
+
+```markdown
+<!-- feature-list.com.md -->
+
+## Features
+
+| Feature     | Description               |
+| ----------- | ------------------------- |
+| Fast builds | Sub-second build times    |
+| Zero config | Works out of the box      |
+| Components  | Reusable HTML, TS, and MD |
+```
+
+### FAQ Section
+
+```markdown
+<!-- faq-section.com.md -->
+
+## Frequently Asked Questions
+
+### How do I install?
+
+Run `bun add -g tkeron` to install globally.
+
+### How do I build?
+
+Run `tk build` in your project directory.
+
+### Where is the output?
+
+Built files go to the `web/` directory.
+```
+
+## Nested Components
+
+Markdown components can include other components using HTML custom elements inside the Markdown:
+
+```markdown
+<!-- page-content.com.md -->
+
+# Main Content
+
+Here is some introductory text.
+
+<feature-list></feature-list>
+
+And here is the conclusion.
+```
+
+The nested `<feature-list>` will be resolved — whether it's a `.com.ts`, `.com.html`, or `.com.md` component.
+
+## When to Use Markdown Components
+
+### ✅ Perfect For
+
+- **Content-heavy sections**: About pages, documentation, FAQs
+- **Blog content**: Static blog posts or content blocks
+- **Feature descriptions**: Lists of features with formatting
+- **Text-heavy UI**: Any section where the content is primarily text
+
+### ❌ Not Ideal For
+
+- **Dynamic content**: Use [TypeScript Components](./components-typescript.md) instead
+- **Complex layouts**: Use [HTML Components](./components-html.md) for precise HTML structure
+- **Interactive elements**: Markdown produces static HTML only
+
+## Limitations
+
+### ❌ No Dynamic Content
+
+Markdown components are **static**. They can't read attributes or use logic. For dynamic content, use [TypeScript Components](./components-typescript.md).
+
+### ❌ No Circular Dependencies
+
+Components can't include themselves directly or indirectly. Build will fail with a clear error message.
+
+### Maximum Nesting Depth
+
+Components can be nested up to **50 levels** deep.
+
+## Best Practices
+
+### ✅ Use for Content Sections
+
+```markdown
+<!-- team-info.com.md -->
+
+## Our Team
+
+We have **10+ engineers** working on this project.
+
+- Backend: 5 engineers
+- Frontend: 3 engineers
+- DevOps: 2 engineers
+```
+
+### ✅ Name Descriptively
+
+```
+Good:
+- about-section.com.md
+- faq-content.com.md
+- feature-overview.com.md
+
+Bad:
+- text1.com.md
+- stuff.com.md
+```
+
+### ✅ Combine with Other Component Types
+
+Use Markdown for content, HTML for layout, and TypeScript for dynamic parts:
+
+```
+websrc/
+├── page-layout.com.html      # Layout structure
+├── hero-content.com.md        # Content in Markdown
+├── user-greeting.com.ts       # Dynamic greeting
+├── index.html
+```
+
+```html
+<!-- index.html -->
+<page-layout></page-layout>
+```
+
+```html
+<!-- page-layout.com.html -->
+<div class="page">
+  <user-greeting></user-greeting>
+  <hero-content></hero-content>
+</div>
+```
+
+## Next Steps
+
+- For precise HTML structure, see [**HTML Components**](./components-html.md)
+- For dynamic components with logic, see [**TypeScript Components**](./components-typescript.md)
+- For build-time transformations, see [**Pre-rendering**](./pre-rendering.md)
+- For patterns and tips, see [**Best Practices**](./best-practices.md)

package/docs/components-typescript.md

@@ -86,6 +86,46 @@ Same as HTML components:
 1. **Same directory** as the file using it
 2. **Root directory** (`websrc/`)
 
+### IDE Support & IntelliSense
+
+For the best development experience, Tkeron projects include TypeScript configuration files:
+
+**`tkeron.d.ts`** - Provides type definitions:
+
+```typescript
+declare module "*.com.ts" {
+  global {
+    const com: HTMLElement;
+  }
+}
+```
+
+This tells your IDE that `com` is an `HTMLElement`, enabling:
+
+- **IntelliSense** for `com.getAttribute()`, `com.innerHTML`, etc.
+- **Type checking** for your component code
+- **Auto-completion** for DOM methods and properties
+
+**`tsconfig.json`** - TypeScript configuration:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "lib": ["ESNext", "DOM"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["websrc/**/*", "tkeron.d.ts"]
+}
+```
+
+Both files are automatically created when you run `tk init`. If you created your project manually, you can copy them from the [init_sample example](https://github.com/pablotk/tkeron/tree/master/examples/init_sample).
+
+**Note:** These files are only for IDE support and don't affect the build process. Tkeron uses Bun's built-in TypeScript support for compilation.
+
 ## Basic Examples
 
 ### Attribute-Based Content

package/docs/getting-started.md

@@ -38,7 +38,8 @@ my-website/
 │   ├── index.ts         # TypeScript for index
 │   ├── index.pre.ts     # Pre-rendering script
 │   └── *.com.html       # Sample components
-└── tkeron.d.ts          # TypeScript definitions
+├── tkeron.d.ts          # TypeScript definitions
+└── tsconfig.json        # TypeScript configuration
 ```
 
 ### Initialize in Current Directory

package/docs/pre-rendering.md

@@ -97,6 +97,26 @@ If the `.html` file doesn't exist, Tkeron creates a default one:
 
 Then your `.pre.ts` file runs on this template.
 
+### IDE Support & IntelliSense
+
+The `tkeron.d.ts` file in your project provides type definitions for the `document` variable:
+
+```typescript
+declare module "*.pre.ts" {
+  global {
+    const document: Document;
+  }
+}
+```
+
+This enables:
+
+- **IntelliSense** for `document.querySelector()`, `document.getElementById()`, etc.
+- **Type checking** for DOM manipulation
+- **Auto-completion** for all Document methods and properties
+
+The `tsconfig.json` ensures your IDE recognizes these types. Both files are automatically created by `tk init`.
+
 ## Basic Examples
 
 ### Set Page Title

package/examples/init_sample/tkeron.d.ts

@@ -0,0 +1,13 @@
+// Augment global scope for .pre.ts files
+declare module "*.pre.ts" {
+  global {
+    const document: Document;
+  }
+}
+
+// Augment global scope for .com.ts files
+declare module "*.com.ts" {
+  global {
+    const com: HTMLElement;
+  }
+}

package/examples/init_sample/websrc/index.ts

@@ -1,10 +1,10 @@
 // Client-side TypeScript - runs in the browser
-let count = 0;
+let clickCount = 0;
 
-const button = document.getElementById('increment') as HTMLButtonElement;
-const countDisplay = document.getElementById('count') as HTMLSpanElement;
+const button = document.getElementById("increment") as HTMLButtonElement;
+const countDisplay = document.getElementById("count") as HTMLSpanElement;
 
-button.addEventListener('click', () => {
-  count++;
-  countDisplay.textContent = count.toString();
+button.addEventListener("click", () => {
+  clickCount++;
+  countDisplay.textContent = clickCount.toString();
 });

package/examples/init_sample/websrc/user-badge.com.ts

@@ -1,16 +1,17 @@
 // TypeScript component - runs at build time with logic
-const count = com.getAttribute('count') || '3';
+const count = com.getAttribute("count") || "3";
+const numCount = parseInt(count, 10);
 
 // Generate list dynamically
 const items = [];
-for (let i = 1; i <= parseInt(count); i++) {
+for (let i = 1; i <= numCount; i++) {
   items.push(`<li>✓ Item ${i}</li>`);
 }
 
 com.innerHTML = `
   <div style="background: #f0fdf4; border-left: 3px solid #22c55e; padding: 0.75rem; border-radius: 4px;">
     <ul style="list-style: none; padding: 0; margin: 0; font-size: 0.9rem; color: #166534;">
-      ${items.join('')}
+      ${items.join("")}
     </ul>
   </div>
 `;

package/mcp-server.ts

@@ -53,6 +53,12 @@ const DOCS = [
     description: "Build dynamic components with .com.ts files",
     file: "components-typescript.md",
   },
+  {
+    uri: "tkeron://components-markdown",
+    name: "Markdown Components",
+    description: "Create components with Markdown using .com.md files",
+    file: "components-markdown.md",
+  },
   {
     uri: "tkeron://pre-rendering",
     name: "Pre-rendering",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tkeron",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "CLI tool for backend-driven frontend development with TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/build.ts

@@ -3,6 +3,7 @@ import { buildDir } from "./buildDir";
 import { processPre } from "./processPre";
 import { processCom } from "./processCom";
 import { processComTs } from "./processComTs";
+import { processComMd } from "./processComMd";
 import { rm, exists, mkdir, cp } from "fs/promises";
 import type { Logger } from "@tkeron/tools";
 import { silentLogger } from "@tkeron/tools";
@@ -46,10 +47,11 @@ export const build = async (options: BuildOptions) => {
 
     const MAX_ITERATIONS = 10;
     for (let i = 0; i < MAX_ITERATIONS; i++) {
-      const htmlChanged = await processCom(tempDir, { logger: log });
       const tsChanged = await processComTs(tempDir, { logger: log });
+      const htmlChanged = await processCom(tempDir, { logger: log });
+      const mdChanged = await processComMd(tempDir, { logger: log });
 
-      if (!htmlChanged && !tsChanged) {
+      if (!tsChanged && !htmlChanged && !mdChanged) {
         break;
       }
     }

package/src/processComMd.ts

@@ -0,0 +1,197 @@
+import { parseHTML } from "@tkeron/html-parser";
+import { getFilePaths } from "@tkeron/tools";
+import { join, dirname } from "path";
+import type { Logger } from "@tkeron/tools";
+import { silentLogger } from "@tkeron/tools";
+
+const DOCTYPE = "<!doctype html>\n";
+
+const ensureHtmlDocument = (html: string): string => {
+  const hasHtmlTag = /<\s*html[\s>]/i.test(html);
+  if (hasHtmlTag) return html;
+  return `${DOCTYPE}<html><head></head><body>${html}</body></html>`;
+};
+
+export interface ProcessComMdOptions {
+  logger?: Logger;
+}
+
+export const processComMd = async (
+  tempDir: string,
+  options: ProcessComMdOptions = {},
+): Promise<boolean> => {
+  const log = options.logger || silentLogger;
+
+  if (!tempDir || typeof tempDir !== "string") {
+    log.error(`\n❌ Error: Invalid tempDir provided for processComMd.`);
+    return false;
+  }
+
+  const htmlFiles = getFilePaths(tempDir, "**/*.html", true).filter(
+    (p) => !p.endsWith(".com.html"),
+  );
+
+  let hasChanges = false;
+
+  for (const htmlFile of htmlFiles) {
+    const htmlContent = await Bun.file(htmlFile).text();
+    const document = parseHTML(ensureHtmlDocument(htmlContent));
+
+    const htmlElement =
+      document.querySelector("html") || document.documentElement;
+    if (htmlElement) {
+      const changed = await processComponents(
+        htmlElement,
+        dirname(htmlFile),
+        tempDir,
+        [],
+        0,
+        log,
+      );
+      hasChanges = hasChanges || changed;
+    }
+
+    const output =
+      DOCTYPE +
+      (htmlElement?.outerHTML || document.documentElement?.outerHTML || "");
+    await Bun.write(htmlFile, output);
+  }
+
+  return hasChanges;
+};
+
+const processComponents = async (
+  element: any,
+  currentDir: string,
+  rootDir: string,
+  componentStack: string[],
+  depth: number = 0,
+  log: Logger = silentLogger,
+): Promise<boolean> => {
+  let hasChanges = false;
+  const MAX_DEPTH = 50;
+  if (depth > MAX_DEPTH) {
+    log.warn(`Maximum component nesting depth (${MAX_DEPTH}) reached`);
+    return hasChanges;
+  }
+
+  const children = Array.from(element.children || []);
+
+  for (const child of children) {
+    const tagName = (child as any).tagName?.toLowerCase();
+
+    if (tagName) {
+      if (!tagName.includes("-")) {
+        const localPath = join(currentDir, `${tagName}.com.md`);
+        const rootPath = join(rootDir, `${tagName}.com.md`);
+        if (
+          (await Bun.file(localPath).exists()) ||
+          (await Bun.file(rootPath).exists())
+        ) {
+          log.error(
+            `\n❌ Error: Component name '${tagName}' must contain at least one hyphen.`,
+          );
+          log.error(`\n💡 Custom elements require hyphens to be valid HTML.`);
+          log.error(
+            `   Rename '${tagName}.com.md' to 'tk-${tagName}.com.md' or similar.`,
+          );
+          log.error(
+            `   File: ${(await Bun.file(localPath).exists()) ? localPath : rootPath}\n`,
+          );
+          throw new Error(
+            `Component name '${tagName}' must contain at least one hyphen`,
+          );
+        }
+      } else {
+        const localPath = join(currentDir, `${tagName}.com.md`);
+        const rootPath = join(rootDir, `${tagName}.com.md`);
+
+        let componentPath: string | null = null;
+
+        if (await Bun.file(localPath).exists()) {
+          componentPath = localPath;
+        } else if (await Bun.file(rootPath).exists()) {
+          componentPath = rootPath;
+        }
+
+        if (componentPath) {
+          hasChanges = true;
+
+          if (componentStack.includes(tagName)) {
+            const chain = [...componentStack, tagName].join(" -> ");
+            log.error(`\n❌ Error: Circular component dependency detected.`);
+            log.error(`\n💡 Component chain: ${chain}`);
+            log.error(
+              `\n   Components cannot include themselves directly or indirectly.`,
+            );
+            log.error(`   Check your .com.md files for circular references.\n`);
+            throw new Error(`Circular dependency: ${chain}`);
+          }
+
+          const mdContent = await Bun.file(componentPath).text();
+          const componentHtml = Bun.markdown.html(mdContent);
+
+          const tempDoc = parseHTML(
+            `<html><body><div id="__tkeron_component_root__">${componentHtml}</div></body></html>`,
+          );
+          const body = tempDoc.querySelector("body");
+          const tempContainer =
+            body?.querySelector("#__tkeron_component_root__") ||
+            body?.firstElementChild;
+
+          if (!tempContainer) continue;
+
+          const nodesToInsert = Array.from(
+            (tempContainer as any).childNodes || [],
+          ).map((node: any) => (node?.cloneNode ? node.cloneNode(true) : node));
+
+          const parent = (child as any).parentNode;
+
+          if (parent) {
+            if (nodesToInsert.length === 0) {
+              parent.removeChild(child);
+            } else if (nodesToInsert.length === 1) {
+              parent.replaceChild(nodesToInsert[0], child);
+            } else {
+              parent.replaceChild(nodesToInsert[0], child);
+              let refNode = nodesToInsert[0];
+              for (let i = 1; i < nodesToInsert.length; i++) {
+                parent.insertBefore(nodesToInsert[i], refNode.nextSibling);
+                refNode = nodesToInsert[i];
+              }
+            }
+          }
+
+          const nextCurrentDir = dirname(componentPath);
+          const nextStack = [...componentStack, tagName];
+
+          for (const node of nodesToInsert) {
+            if ((node as any).nodeType === 1) {
+              const nestedChanged = await processComponents(
+                node,
+                nextCurrentDir,
+                rootDir,
+                nextStack,
+                depth + 1,
+                log,
+              );
+              hasChanges = hasChanges || nestedChanged;
+            }
+          }
+        }
+      }
+    }
+
+    const childChanged = await processComponents(
+      child,
+      currentDir,
+      rootDir,
+      componentStack,
+      depth,
+      log,
+    );
+    hasChanges = hasChanges || childChanged;
+  }
+
+  return hasChanges;
+};