tkeron 4.0.0-beta.8 → 4.0.0

package/docs/components-typescript.md

@@ -7,17 +7,17 @@ TypeScript components (`.com.ts` files) let you create dynamic, logic-driven com
 Create a `.com.ts` file:
 
 ```typescript
-// greeting.com.ts
-const name = com.getAttribute('name') || 'World';
+// user-greeting.com.ts
+const name = com.getAttribute("name") || "World";
 com.innerHTML = `<h1>Hello, ${name}!</h1>`;
 ```
 
 Use it with attributes:
 
 ```html
-<greeting name="Alice"></greeting>
-<greeting name="Bob"></greeting>
-<greeting></greeting>
+<user-greeting name="Alice"></user-greeting>
+<user-greeting name="Bob"></user-greeting>
+<user-greeting></user-greeting>
 ```
 
 Build output:
@@ -36,9 +36,9 @@ Every `.com.ts` file has access to a special `com` variable:
 
 ```typescript
 // The 'com' variable is the DOM element itself
-com.getAttribute('attr-name')  // Read attributes
-com.innerHTML = '...'           // Set content (this is what's kept)
-com.tagName                     // Get element name
+com.getAttribute("attr-name"); // Read attributes
+com.innerHTML = "..."; // Set content (this is what's kept)
+com.tagName; // Get element name
 ```
 
 **Important:** Only the `innerHTML` you set is included in the final output. Everything else is discarded.
@@ -58,6 +58,27 @@ Browser sees only:
 <div class="card">John</div>
 ```
 
+### Component Naming
+
+Component filenames must:
+
+- End with `.com.ts`
+- Match the custom element name (without `.com.ts`)
+- **Use lowercase with hyphens** (custom element requirement)
+
+**Examples:**
+
+| Filename              | Custom Element  | Valid?                    |
+| --------------------- | --------------- | ------------------------- |
+| `user-card.com.ts`    | `<user-card>`   | ✅ Yes                    |
+| `nav-menu.com.ts`     | `<nav-menu>`    | ✅ Yes                    |
+| `greeting.com.ts`     | `<greeting>`    | ❌ No (no hyphen)         |
+| `UserCard.com.ts`     | `<user-card>`   | ✅ Yes (case-insensitive) |
+
+**Why hyphens are required:**
+
+Custom elements in HTML must contain at least one hyphen to distinguish them from standard HTML elements. This is a web standard requirement. Tkeron validates this at build time and shows a clear error message if a component name doesn't follow this rule.
+
 ### Component Resolution
 
 Same as HTML components:
@@ -71,8 +92,8 @@ Same as HTML components:
 
 ```typescript
 // user-badge.com.ts
-const name = com.getAttribute('name') || 'Guest';
-const role = com.getAttribute('role') || 'User';
+const name = com.getAttribute("name") || "Guest";
+const role = com.getAttribute("role") || "User";
 
 com.innerHTML = `
   <div class="badge">
@@ -111,7 +132,7 @@ com.innerHTML = `
 
 ```typescript
 // item-list.com.ts
-const count = parseInt(com.getAttribute('count') || '3');
+const count = parseInt(com.getAttribute("count") || "3");
 const items = [];
 
 for (let i = 1; i <= count; i++) {
@@ -120,7 +141,7 @@ for (let i = 1; i <= count; i++) {
 
 com.innerHTML = `
   <ul class="item-list">
-    ${items.join('')}
+    ${items.join("")}
   </ul>
 `;
 ```
@@ -147,14 +168,14 @@ com.innerHTML = `
 
 ```typescript
 // alert-box.com.ts
-const type = com.getAttribute('type') || 'info';
-const message = com.getAttribute('message') || 'No message provided';
+const type = com.getAttribute("type") || "info";
+const message = com.getAttribute("message") || "No message provided";
 
 const colors = {
-  info: '#3b82f6',
-  success: '#22c55e',
-  warning: '#f59e0b',
-  error: '#ef4444',
+  info: "#3b82f6",
+  success: "#22c55e",
+  warning: "#f59e0b",
+  error: "#ef4444",
 };
 
 const color = colors[type as keyof typeof colors] || colors.info;
@@ -185,23 +206,23 @@ You can use all TypeScript features:
 interface Stats {
   label: string;
   value: number;
-  trend: 'up' | 'down' | 'neutral';
+  trend: "up" | "down" | "neutral";
 }
 
-const label = com.getAttribute('label') || 'Stat';
-const value = parseInt(com.getAttribute('value') || '0');
-const trend = com.getAttribute('trend') as Stats['trend'] || 'neutral';
+const label = com.getAttribute("label") || "Stat";
+const value = parseInt(com.getAttribute("value") || "0");
+const trend = (com.getAttribute("trend") as Stats["trend"]) || "neutral";
 
 const trendIcon = {
-  up: '↑',
-  down: '↓',
-  neutral: '→',
+  up: "↑",
+  down: "↓",
+  neutral: "→",
 };
 
 const trendColor = {
-  up: '#22c55e',
-  down: '#ef4444',
-  neutral: '#6b7280',
+  up: "#22c55e",
+  down: "#ef4444",
+  neutral: "#6b7280",
 };
 
 com.innerHTML = `
@@ -221,10 +242,10 @@ You can import any TypeScript module or npm package:
 
 ```typescript
 // product-card.com.ts
-import { formatPrice } from './utils';
+import { formatPrice } from "./utils";
 
-const name = com.getAttribute('name') || 'Product';
-const price = parseFloat(com.getAttribute('price') || '0');
+const name = com.getAttribute("name") || "Product";
+const price = parseFloat(com.getAttribute("price") || "0");
 
 com.innerHTML = `
   <div class="product-card">
@@ -237,9 +258,9 @@ com.innerHTML = `
 ```typescript
 // utils.ts
 export function formatPrice(price: number): string {
-  return new Intl.NumberFormat('en-US', {
-    style: 'currency',
-    currency: 'USD',
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
   }).format(price);
 }
 ```
@@ -250,7 +271,7 @@ Fetch data at build time:
 
 ```typescript
 // weather-widget.com.ts
-const city = com.getAttribute('city') || 'London';
+const city = com.getAttribute("city") || "London";
 
 interface WeatherData {
   temperature: number;
@@ -279,9 +300,9 @@ com.innerHTML = `
 
 ```typescript
 // markdown-content.com.ts
-import { marked } from 'marked';
+import { marked } from "marked";
 
-const content = com.getAttribute('content') || '# Hello';
+const content = com.getAttribute("content") || "# Hello";
 const html = marked(content);
 
 com.innerHTML = `
@@ -303,8 +324,8 @@ TypeScript components can use other components:
 
 ```typescript
 // user-profile.com.ts
-const username = com.getAttribute('username') || 'anonymous';
-const bio = com.getAttribute('bio') || 'No bio provided';
+const username = com.getAttribute("username") || "anonymous";
+const bio = com.getAttribute("bio") || "No bio provided";
 
 com.innerHTML = `
   <div class="user-profile">
@@ -327,8 +348,8 @@ Event listeners are lost in the static output:
 
 ```typescript
 // ❌ This won't work
-com.addEventListener('click', () => {
-  console.log('clicked');
+com.addEventListener("click", () => {
+  console.log("clicked");
 });
 ```
 
@@ -336,9 +357,9 @@ com.addEventListener('click', () => {
 
 ```typescript
 // index.ts (runs in browser)
-document.querySelectorAll('.my-button').forEach(button => {
-  button.addEventListener('click', () => {
-    console.log('clicked');
+document.querySelectorAll(".my-button").forEach((button) => {
+  button.addEventListener("click", () => {
+    console.log("clicked");
   });
 });
 ```
@@ -349,8 +370,8 @@ You can't access other parts of the document:
 
 ```typescript
 // ❌ This won't work
-const header = document.querySelector('header');
-com.innerHTML = header?.textContent || '';
+const header = document.querySelector("header");
+com.innerHTML = header?.textContent || "";
 ```
 
 **Solution:** Use [pre-rendering](./pre-rendering.md) for document-wide transformations.
@@ -375,7 +396,7 @@ Build-time components can't access runtime data:
 
 ```typescript
 // ❌ This won't work - no access to current user
-const currentUser = localStorage.getItem('user');
+const currentUser = localStorage.getItem("user");
 com.innerHTML = `<p>Hello, ${currentUser}</p>`;
 ```
 
@@ -386,6 +407,7 @@ com.innerHTML = `<p>Hello, ${currentUser}</p>`;
 ### ✅ Use for Attribute-Driven Components
 
 Perfect for:
+
 - Components that vary based on attributes
 - Generating repetitive HTML
 - Build-time data transformation
@@ -395,11 +417,13 @@ Perfect for:
 
 ```typescript
 // color-badge.com.ts
-const validColors = ['red', 'blue', 'green', 'yellow'];
-const color = com.getAttribute('color') || 'blue';
+const validColors = ["red", "blue", "green", "yellow"];
+const color = com.getAttribute("color") || "blue";
 
 if (!validColors.includes(color)) {
-  throw new Error(`Invalid color: ${color}. Use one of: ${validColors.join(', ')}`);
+  throw new Error(
+    `Invalid color: ${color}. Use one of: ${validColors.join(", ")}`,
+  );
 }
 
 com.innerHTML = `<span class="badge badge-${color}">Badge</span>`;
@@ -415,14 +439,14 @@ Prevent XSS by escaping user-provided content:
 // user-comment.com.ts
 function escapeHtml(text: string): string {
   return text
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#039;');
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
 }
 
-const comment = com.getAttribute('comment') || '';
+const comment = com.getAttribute("comment") || "";
 com.innerHTML = `<p>${escapeHtml(comment)}</p>`;
 ```
 
@@ -430,15 +454,15 @@ com.innerHTML = `<p>${escapeHtml(comment)}</p>`;
 
 ```typescript
 // card.com.ts
-type CardVariant = 'default' | 'outlined' | 'elevated';
+type CardVariant = "default" | "outlined" | "elevated";
 
-const variant = com.getAttribute('variant') as CardVariant || 'default';
-const title = com.getAttribute('title') || 'Card';
+const variant = (com.getAttribute("variant") as CardVariant) || "default";
+const title = com.getAttribute("title") || "Card";
 
 const variants = {
-  default: 'border: 1px solid #e5e7eb',
-  outlined: 'border: 2px solid #3b82f6',
-  elevated: 'box-shadow: 0 4px 6px rgba(0,0,0,0.1)',
+  default: "border: 1px solid #e5e7eb",
+  outlined: "border: 2px solid #3b82f6",
+  elevated: "box-shadow: 0 4px 6px rgba(0,0,0,0.1)",
 };
 
 com.innerHTML = `
@@ -452,9 +476,9 @@ com.innerHTML = `
 
 ```typescript
 // data-table.com.ts
-import { generateTableRows } from './table-utils';
+import { generateTableRows } from "./table-utils";
 
-const data = com.getAttribute('data') || '[]';
+const data = com.getAttribute("data") || "[]";
 const rows = generateTableRows(JSON.parse(data));
 
 com.innerHTML = `
@@ -482,8 +506,8 @@ If a component doesn't need attributes or logic, use [HTML components](./compone
 
 ```typescript
 // debug-component.com.ts
-const value = com.getAttribute('value');
-console.log('Building component with value:', value);
+const value = com.getAttribute("value");
+console.log("Building component with value:", value);
 
 com.innerHTML = `<p>${value}</p>`;
 ```
@@ -514,13 +538,17 @@ cat web/index.html | grep "expected-content"
 
 ```typescript
 // image-gallery.com.ts
-const images = com.getAttribute('images')?.split(',') || [];
+const images = com.getAttribute("images")?.split(",") || [];
 
-const imageElements = images.map((img, idx) => `
+const imageElements = images
+  .map(
+    (img, idx) => `
   <div class="gallery-item">
     <img src="${img.trim()}" alt="Image ${idx + 1}" loading="lazy">
   </div>
-`).join('');
+`,
+  )
+  .join("");
 
 com.innerHTML = `
   <div class="image-gallery">
@@ -539,8 +567,11 @@ com.innerHTML = `
 
 ```typescript
 // progress-bar.com.ts
-const progress = Math.min(100, Math.max(0, parseInt(com.getAttribute('progress') || '0')));
-const label = com.getAttribute('label') || `${progress}%`;
+const progress = Math.min(
+  100,
+  Math.max(0, parseInt(com.getAttribute("progress") || "0")),
+);
+const label = com.getAttribute("label") || `${progress}%`;
 
 com.innerHTML = `
   <div class="progress-bar-container">
@@ -554,14 +585,14 @@ com.innerHTML = `
 
 ```typescript
 // code-block.com.ts
-import { codeToHtml } from 'shiki';
+import { codeToHtml } from "shiki";
 
-const code = com.getAttribute('code') || '';
-const lang = com.getAttribute('lang') || 'typescript';
+const code = com.getAttribute("code") || "";
+const lang = com.getAttribute("lang") || "typescript";
 
 const html = await codeToHtml(code, {
   lang,
-  theme: 'github-dark',
+  theme: "github-dark",
 });
 
 com.innerHTML = `
@@ -587,8 +618,8 @@ bun add shiki
 
 ```typescript
 // social-share.com.ts
-const url = com.getAttribute('url') || '';
-const title = com.getAttribute('title') || '';
+const url = com.getAttribute("url") || "";
+const title = com.getAttribute("title") || "";
 
 const encodedUrl = encodeURIComponent(url);
 const encodedTitle = encodeURIComponent(title);
@@ -620,7 +651,7 @@ Add types for better development experience:
 /// <reference path="./tkeron.d.ts" />
 
 // Now 'com' has full type information
-const attr = com.getAttribute('name'); // TypeScript knows about this
+const attr = com.getAttribute("name"); // TypeScript knows about this
 ```
 
 ## Performance Considerations
@@ -631,7 +662,7 @@ Complex components increase build time:
 
 ```typescript
 // ⚠️ Expensive at build time
-const data = await fetch('https://api.example.com/large-dataset');
+const data = await fetch("https://api.example.com/large-dataset");
 ```
 
 For large datasets, consider caching or pre-processing.

package/docs/getting-started.md

@@ -3,16 +3,19 @@
 ## Installation
 
 **Requires [Bun](https://bun.sh) runtime:**
+
 ```bash
 curl -fsSL https://bun.sh/install | bash
 ```
 
 **Install Tkeron:**
+
 ```bash
 bun install -g tkeron
 ```
 
 **Verify:**
+
 ```bash
 tk
 ```
@@ -65,6 +68,7 @@ tk build websrc web
 ```
 
 **Parameters:**
+
 - First argument: source directory (default: `websrc`)
 - Second argument: output directory (default: `web`)
 
@@ -96,6 +100,7 @@ tk dev
 ```
 
 This will:
+
 1. Build your project
 2. Start a server at `http://localhost:3000`
 3. Watch for file changes
@@ -108,6 +113,7 @@ tk dev websrc web 8080 0.0.0.0
 ```
 
 **Parameters:**
+
 - Source directory (default: `websrc`)
 - Output directory (default: `web`)
 - Port (default: `3000`)
@@ -143,15 +149,15 @@ Edit `websrc/index.html`:
 ```html
 <!DOCTYPE html>
 <html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>My First Tkeron Site</title>
-</head>
-<body>
-  <h1>My Website</h1>
-  <greeting></greeting>
-  <greeting></greeting>
-</body>
+  <head>
+    <meta charset="UTF-8" />
+    <title>My First Tkeron Site</title>
+  </head>
+  <body>
+    <h1>My Website</h1>
+    <greeting></greeting>
+    <greeting></greeting>
+  </body>
 </html>
 ```
 
@@ -189,15 +195,15 @@ Open `web/index.html` in your browser. You'll see the greeting component inlined
 
 ### What Gets Processed?
 
-| File Type | Purpose | In Output? |
-|-----------|---------|------------|
-| `.html` | Regular HTML pages | ✅ Yes |
-| `.ts` / `.js` | Scripts for pages | ✅ Yes (compiled) |
-| `.com.html` | HTML components | ❌ No (inlined) |
-| `.com.ts` | TypeScript components | ❌ No (inlined) |
-| `.pre.ts` | Pre-rendering scripts | ❌ No (executed) |
-| `.css` | Stylesheets | ✅ Yes |
-| Images, fonts, etc. | Static assets | ✅ Yes |
+| File Type           | Purpose               | In Output?        |
+| ------------------- | --------------------- | ----------------- |
+| `.html`             | Regular HTML pages    | ✅ Yes            |
+| `.ts` / `.js`       | Scripts for pages     | ✅ Yes (compiled) |
+| `.com.html`         | HTML components       | ❌ No (inlined)   |
+| `.com.ts`           | TypeScript components | ❌ No (inlined)   |
+| `.pre.ts`           | Pre-rendering scripts | ❌ No (executed)  |
+| `.css`              | Stylesheets           | ✅ Yes            |
+| Images, fonts, etc. | Static assets         | ✅ Yes            |
 
 ## Common Commands
 

package/docs/mcp-server.md

@@ -15,6 +15,7 @@ bun install -g tkeron
 ```
 
 This installs three commands:
+
 - `tk` / `tkeron` - The main CLI tool
 - `tkeron-mcp` - The MCP server
 
@@ -48,7 +49,8 @@ If the global command is not found, use Bun directly:
 ```
 
 **Note:** This is the VS Code format. Other editors (Cursor, Windsurf, etc.) may use different configuration formats.
-```
+
+````
 
 **Find the path:**
 ```bash
@@ -58,7 +60,7 @@ dirname $(which tk)
 
 # The mcp-server.ts is in the same directory
 ls $(dirname $(which tk))/mcp-server.ts
-```
+````
 
 ### Claude Desktop
 
@@ -88,15 +90,16 @@ The server communicates via stdio transport.
 
 The MCP server exposes the following documentation resources:
 
-| URI | Description |
-|-----|-------------|
-| `tkeron://overview` | What Tkeron is, what it does, and what it's not |
-| `tkeron://getting-started` | Installation, first project, and basic workflow |
-| `tkeron://components-html` | Create reusable HTML components with .com.html files |
-| `tkeron://components-typescript` | Build dynamic components with .com.ts files |
-| `tkeron://pre-rendering` | Transform HTML at build time with .pre.ts files |
-| `tkeron://cli-reference` | Complete command-line interface documentation |
-| `tkeron://best-practices` | Patterns, anti-patterns, and limitations |
+| URI                              | Description                                          |
+| -------------------------------- | ---------------------------------------------------- |
+| `tkeron://overview`              | What Tkeron is, what it does, and what it's not      |
+| `tkeron://getting-started`       | Installation, first project, and basic workflow      |
+| `tkeron://components-html`       | Create reusable HTML components with .com.html files |
+| `tkeron://components-typescript` | Build dynamic components with .com.ts files          |
+| `tkeron://pre-rendering`         | Transform HTML at build time with .pre.ts files      |
+| `tkeron://cli-reference`         | Complete command-line interface documentation        |
+| `tkeron://best-practices`        | Patterns, anti-patterns, and limitations             |
+| `tkeron://testing`               | How to test tkeron projects with getBuildResult()    |
 
 ## What AI Agents Can Do
 
@@ -109,25 +112,19 @@ With access to the MCP server, AI agents can:
 - ✅ Provide accurate CLI commands and options
 - ✅ Debug common issues with components and pre-rendering
 - ✅ Recommend best practices and avoid anti-patterns
-- ✅ **Initialize new Tkeron projects directly**
-- ✅ **Build and develop Tkeron projects**
 - ✅ **List and explore example projects**
 - ✅ **Retrieve example code and structures**
+- ✅ **Initialize, build, and develop projects via terminal** (`tk init`, `tk build`, `tk dev`)
 
 ## Available Tools
 
 The MCP server provides the following tools for AI agents:
 
-### Documentation Tool
-
-- **`get_tkeron_docs`**: Retrieve specific documentation topics
-  - Parameters: `topic` (overview, getting-started, components-html, etc.)
-  - Returns the full markdown content of the requested documentation
-
 ### Example Management Tools
 
 - **`list_examples`**: List all available Tkeron example projects
-  - Shows example names, descriptions, and features
+  - No parameters required
+  - Returns example names, descriptions, and paths
   - Helps users discover what's possible with Tkeron
 
 - **`get_example`**: Get the complete source code of an example
@@ -135,22 +132,7 @@ The MCP server provides the following tools for AI agents:
   - Returns file structure and all source code
   - Useful for learning patterns and bootstrapping projects
 
-### Project Management Tools
-
-- **`tkeron_init`**: Initialize a new Tkeron project
-  - Parameters: `projectPath` (absolute path), `force` (optional boolean)
-  - Creates the standard Tkeron structure (websrc/ with sample files)
-  - AI agents can create projects without user intervention
-
-- **`tkeron_build`**: Build a Tkeron project
-  - Parameters: `sourceDir`, `targetDir` (optional)
-  - Processes all `.pre.ts`, `.com.html`, and `.com.ts` files
-  - Generates production-ready output
-
-- **`tkeron_develop`**: Start the development server
-  - Parameters: `sourceDir`, `outputDir`, `port`, `host` (all optional)
-  - Launches hot-reload development server
-  - AI agents can test projects immediately after creation
+> **Note:** The MCP server only provides documentation and examples. It does NOT modify files. The AI agent should use terminal commands (`tk init`, `tk build`, `tk dev`) to manage projects.
 
 ## Benefits
 
@@ -202,6 +184,7 @@ bun install
 ### MCP Client Not Connecting
 
 Check your configuration file syntax:
+
 - Valid JSON
 - Correct command path
 - Proper permissions on the executable