npm - tkeron - Versions diffs - 6.0.0 → 6.0.1 - Mend

tkeron 6.0.0 → 6.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/examples/with_global_styles/websrc/global-styles.com.ts ADDED Viewed

@@ -0,0 +1,5 @@
+import { join } from "path";
+const css = await Bun.file(join(__dirname, "styles.css")).text();
+com.innerHTML = `<style>${css}</style>`;

package/examples/with_global_styles/websrc/good.html ADDED Viewed

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Good — global-styles component</title>
+    <global-styles></global-styles>
+  </head>
+  <body>
+    <h1>Good: <code>&lt;global-styles&gt;</code></h1>
+    <p>
+      The <code>&lt;global-styles&gt;</code> component reads
+      <code>styles.css</code> at build time and injects it as a
+      <code>&lt;style&gt;</code> block directly in <code>&lt;head&gt;</code>.
+    </p>
+    <p>
+      Check <code>web/good.html</code>: no external CSS file, all styles are
+      inline. Zero extra HTTP requests.
+    </p>
+    <a href="index.html">Back to index</a>
+  </body>
+</html>

package/examples/with_global_styles/websrc/index.html ADDED Viewed

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Global Styles — Overview</title>
+  </head>
+  <body>
+    <h1>Global Styles Import</h1>
+    <p>
+      Two approaches for adding shared CSS to a tkeron page. Compare the
+      compiled output in <code>web/</code>.
+    </p>
+    <ul>
+      <li>
+        <a href="bad.html">Bad — <code>&lt;link rel="stylesheet"&gt;</code></a>:
+        CSS ends up in a separate file (extra HTTP request).
+      </li>
+      <li>
+        <a href="good.html">Good — <code>&lt;global-styles&gt;</code></a>:
+        CSS is inlined at build time (no extra request).
+      </li>
+    </ul>
+  </body>
+</html>

package/examples/with_global_styles/websrc/styles.css ADDED Viewed

@@ -0,0 +1,24 @@
+body {
+  font-family: system-ui, sans-serif;
+  max-width: 640px;
+  margin: 2rem auto;
+  padding: 0 1rem;
+  color: #1a1a1a;
+  line-height: 1.6;
+}
+h1 {
+  font-size: 1.5rem;
+  margin-bottom: 0.5rem;
+}
+p {
+  margin: 0.75rem 0;
+}
+code {
+  background: #f0f0f0;
+  padding: 0.1em 0.35em;
+  border-radius: 3px;
+  font-size: 0.875em;
+}

package/examples/with_style_dedup/websrc/tag-chip.com.html ADDED Viewed

@@ -0,0 +1,15 @@
+<style>
+  .tag-chip {
+    display: inline-block;
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    color: white;
+    padding: 0.2rem 0.65rem;
+    border-radius: 999px;
+    font-size: 0.75rem;
+    font-weight: 600;
+    margin: 0.2rem;
+    font-family: monospace;
+    letter-spacing: 0.02em;
+  }
+</style>
+<span class="tag-chip">label...</span>

package/examples/with_style_dedup/websrc/tag-chip.com.ts CHANGED Viewed

@@ -1,19 +1,3 @@
 const label = com.getAttribute("label") || "tag";
-com.innerHTML = `
-  <style>
-    .tag-chip {
-      display: inline-block;
-      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-      color: white;
-      padding: 0.2rem 0.65rem;
-      border-radius: 999px;
-      font-size: 0.75rem;
-      font-weight: 600;
-      margin: 0.2rem;
-      font-family: monospace;
-      letter-spacing: 0.02em;
-    }
-  </style>
-  <span class="tag-chip">${label}</span>
-`;
+const span = com.querySelector(".tag-chip");
+if (span) span.textContent = label;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "tkeron",
-  "version": "6.0.0",
+  "version": "6.0.1",
   "description": "CLI build tool for vanilla web development with TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/skills/tkeron/SKILL.md CHANGED Viewed

@@ -181,7 +181,7 @@ Limits: max **10 iterations**, max **50 nesting levels**, no circular dependenci
   <head>
     <meta charset="UTF-8" />
     <title>My Site</title>
-    <link rel="stylesheet" href="./styles.css" />
+    <global-styles></global-styles>
   </head>
   <body>
     <site-header></site-header>
@@ -191,10 +191,11 @@ Limits: max **10 iterations**, max **50 nesting levels**, no circular dependenci
 </html>
 ```
-**Two non-negotiable rules**:
+**Three non-negotiable rules**:
 1. **`src="index.ts"` with `type="module"`**, NEVER `.js`. Tkeron compiles and rewrites the reference.
-2. **Relative paths only** (`./`, `../`). NEVER absolute (`/styles.css`) — Bun cannot resolve them at build time. Applies to `.html`, `.com.html`, and `url()` in CSS.
+2. **Relative paths only** (`./`, `../`). NEVER absolute (`/file.ext`) — Bun cannot resolve them at build time. Applies to `.html`, `.com.html`, and `url()` in CSS.
+3. **CSS via components, never `<link rel="stylesheet">`**. A `<global-styles>` component reads the `.css` file at build time and inlines it as `<style>` — no extra request, dedup-friendly. See `tkeron-patterns` → "CSS via components".
 ---

package/skills/tkeron-organization/SKILL.md CHANGED Viewed

@@ -39,9 +39,10 @@ websrc/
 │       ├── hero-text.com.md
 │       └── about-section.com.md
 │
-├── styles/
-│   ├── main.css                # Global styles
-│   └── components.css          # Component styles
+├── styles/                     # OPTIONAL — .css source files (or place them
+│   │                              anywhere). Never loaded via <link>; a
+│   │                              .com.ts component reads and inlines them.
+│   └── main.css                 # Tokens + resets + body typography (small!)
 │
 └── utils/
     ├── format.ts               # Helpers (imported by .com.ts or .pre.ts)
@@ -164,7 +165,7 @@ thing.com.html                 → No clear purpose
 ✅ GOOD:
 index.html, about.html, blog-post.html
 api-service.ts, format-utils.ts
-main.css, components.css
+main.css, tokens.css
 ❌ BAD:
 Index.html                     → Always lowercase
@@ -198,7 +199,7 @@ websrc/assets/hero-image.png
 | Per-page `.pre.ts`/`.post.ts` | Same directory as the paired `.html`                           |
 | Shared components             | `websrc/components/<domain>/` (`layout/`, `ui/`, `content/`)   |
 | Local-override components     | Same directory as the page that uses them (wins by priority)   |
-| Global styles                 | `websrc/styles/`                                               |
+| Global styles                 | Free choice (root of `websrc/`, a `styles/` folder, next to the loader component). Source `.css` files are NOT loaded via `<link>`; a `.com.ts` reads them and inlines as `<style>` (see `tkeron-patterns` → "CSS via components"). Per-component CSS lives **inside** each `.com.html`. |
 | Build-time utils (Bun)        | `websrc/utils/` — imported by `.pre.ts`, `.post.ts`, `.com.ts` |
 | Static assets                 | `websrc/assets/` (or wherever — they are copied as-is)         |
 | Output                        | `web/` — **NEVER edit, always in `.gitignore`**                |

package/skills/tkeron-patterns/SKILL.md CHANGED Viewed

@@ -211,25 +211,102 @@ if (!isProd) {
 }
 ```
-### CSS classes, not repeated inline styles
+### CSS via components (NEVER `<link rel="stylesheet">`)
-```css
-/* styles/components.css */
-:root {
-  --primary: #3b82f6;
-  --spacing: 1rem;
-}
+**Rule**: CSS in tkeron lives inside `<style>` blocks emitted by components. Pages MUST NOT use `<link rel="stylesheet">`. This unlocks three properties:
-.card {
-  padding: var(--spacing);
-  border: 1px solid #e5e7eb;
-  border-radius: 8px;
-}
+1. **Auto-dedup**: tkeron keeps a single `<style data-tk-com="...">` in `<head>` no matter how many times the component is used.
+2. **Tree-shaking**: if a component is not used on a page, its CSS does not ship to that page.
+3. **Zero extra requests**: CSS travels inside the HTML download → first paint without waiting for another request.
+#### Per-component CSS — in `.com.html`
+```html
+<!-- card.com.html -->
+<style>
+  .card { padding: 1rem; border: 1px solid #e5e7eb; border-radius: 8px; }
+</style>
+<div class="card"></div>
 ```
 ```typescript
-// card.com.ts
-com.innerHTML = `<div class="card">${content}</div>`;
+// card.com.ts (optional — only if logic is needed)
+const body = com.querySelector(".card");
+if (body) body.textContent = com.getAttribute("text") || "";
+```
+> If a `.com.html` exists next to a `.com.ts`, the HTML is loaded into `com.innerHTML` **before** the `.com.ts` runs. The `<style>` is preserved and dedup applies. Do NOT re-emit the `<style>` from `.com.ts`.
+**Build output — dedup in action.** Component used 6 times → `<head>` receives exactly **one** `<style data-tk-com="tag-chip">` block:
+```html
+<!-- websrc/index.html — source has 6 <tag-chip> uses -->
+<tag-chip label="TypeScript"></tag-chip>
+<tag-chip label="HTML"></tag-chip>
+<tag-chip label="CSS"></tag-chip>
+<tag-chip label="Bun"></tag-chip>
+<tag-chip label="tkeron"></tag-chip>
+<tag-chip label="zero deps"></tag-chip>
+```
+```html
+<!-- web/index.html — tkeron output -->
+<head>
+  <!-- ONE style block, regardless of how many times the component was used -->
+  <style data-tk-com="tag-chip">
+    .tag-chip { display: inline-block; background: ...; color: white; ... }
+  </style>
+</head>
+<body>
+  <span class="tag-chip">TypeScript</span>
+  <span class="tag-chip">HTML</span>
+  <span class="tag-chip">CSS</span>
+  <span class="tag-chip">Bun</span>
+  <span class="tag-chip">tkeron</span>
+  <span class="tag-chip">zero deps</span>
+</body>
+```
+#### Global CSS — keep `.css` file, inline via a component
+For truly shared CSS (resets, tokens, body typography) you can keep a real `.css` file in source (so the editor gives you CSS tooling). Do **not** import it with `<link>`. Inline it through a build-time component — a `.com.ts` is the natural fit because it can read files at build time:
+```typescript
+// any-name.com.ts (e.g. global-styles.com.ts, site-css.com.ts — name is free,
+// just respect the custom-element hyphen rule)
+import { join } from "path";
+const css = await Bun.file(join(__dirname, "main.css")).text();
+com.innerHTML = `<style>${css}</style>`;
+```
+```html
+<!-- any page -->
+<head>
+  <global-styles></global-styles>
+</head>
+```
+The `.css` file can live wherever the user prefers (root of `websrc/`, next to the component, in a `styles/` folder — free choice). What matters is that the page references the **component**, not the `.css` file. Keep the global CSS **small**: it ships on every page. Anything component-specific belongs in that component's `.com.html`.
+**Build output — `<link>` vs component.** Both source patterns compile, but the output is fundamentally different:
+```html
+<!-- ❌ websrc/page.html uses <link rel="stylesheet" href="./styles.css"> -->
+<!-- web/page.html output: -->
+<link rel="stylesheet" href="./page.css" />
+<!-- + a separate page.css file is emitted next to page.html -->
+<!-- = 1 extra HTTP request, blocks first paint -->
+```
+```html
+<!-- ✅ websrc/page.html uses <global-styles></global-styles> -->
+<!-- web/page.html output: -->
+<style>
+  /* full content of styles.css inlined — zero extra files, zero extra requests */
+  :root { --accent: #38bdf8; }
+  body { margin: 0; font-family: system-ui; }
+</style>
+<!-- no .css file emitted alongside page.html -->
 ```
 ---
@@ -298,6 +375,20 @@ Tkeron serves the output from a subdirectory. Absolute paths (`/assets/...`) poi
 Applies to **every `href`, `src` and `url()`** pointing to local assets in `websrc/`.
+### ❌ `<link rel="stylesheet">` in HTML
+Generates an extra HTTP request, blocks first paint, and bypasses tkeron's per-component dedup and tree-shaking.
+```html
+<!-- ❌ BAD — extra request, no dedup, no tree-shaking -->
+<link rel="stylesheet" href="./styles.css" />
+<!-- ✅ GOOD — inlined at build time via a component -->
+<global-styles></global-styles>
+```
+See "CSS via components" above for the `global-styles.com.ts` pattern.
 ### ❌ Event listeners in `.com.ts`
 ```typescript
@@ -470,9 +561,10 @@ if (isNaN(count) || count < 0 || count > 100) {
 ### Output size
-- CSS classes instead of inline styles
+- CSS classes instead of repeated inline `style="..."`
 - Lean components (little HTML per component)
-- Shared external CSS (`components.css`)
+- CSS lives in `<style>` inside `.com.html` → auto-dedup + tree-shaking
+- Global CSS via `<global-styles>` component (inlined), NEVER `<link rel="stylesheet">`
 - CSS variables for colors/spacing
 ---
@@ -487,7 +579,7 @@ When creating/editing a tkeron project:
 4. ✅ Browser code → `.ts`. Build code → `.com.ts` / `.pre.ts` / `.post.ts`
 5. ✅ Build-time fetch → always with AbortController + timeout
 6. ✅ Escape dynamic content (`escapeHtml`)
-7. ✅ CSS classes, not repeated inline styles
+7. ✅ CSS via components (`<style>` in `.com.html`), never `<link rel="stylesheet">`
 8. ✅ **Maximum pre-render**: HTML structure in `.html` / components, JS only fills data
 9. ✅ npm packages only at build time, CDN for the browser
 10. ✅ `tk build` after every edit, then verify `web/`. NEVER `tk dev` synchronously in agent sessions

package/skills/tkeron-troubleshooting/SKILL.md CHANGED Viewed

@@ -35,13 +35,17 @@ Something is wrong
 ### `Cannot resolve "/styles.css"`
-**Cause**: absolute path. Bun resolves from the source file, not from the server root.
+**Cause**: absolute path in a `<link rel="stylesheet">`. Two problems: the path is absolute (Bun resolves from the source file, not the server root), and `<link rel="stylesheet">` is itself an anti-pattern in tkeron.
+**Fix**: replace the `<link>` with a `<global-styles>` component that inlines the CSS at build time. See `tkeron-patterns` → "CSS via components".
 ```html
-<!-- ❌ -->
+<!-- ❌ BAD -->
 <link rel="stylesheet" href="/styles.css" />
-<!-- ✅ -->
+<!-- ⚠️ Works but anti-pattern (extra request, no dedup) -->
 <link rel="stylesheet" href="./styles.css" />
+<!-- ✅ GOOD — inlined, no extra request, dedup-friendly -->
+<global-styles></global-styles>
 ```
 ### `Component name must contain hyphen`

package/examples/init_sample/websrc/counter-card.com.html DELETED Viewed

@@ -1,12 +0,0 @@
-<section>
-  <h2>🎯 Client-side TypeScript</h2>
-  <p style="margin-bottom: 0.75rem">Interactive features in the browser:</p>
-  <div class="counter">
-    <button id="increment">Click me!</button>
-    <div class="count">Clicks: <span id="count">0</span></div>
-  </div>
-  <p style="font-size: 0.85rem; color: #666; margin-top: 0.75rem">
-    ✓ Event handling & DOM manipulation<br />✓ Regular TypeScript for
-    interactivity
-  </p>
-</section>

package/examples/init_sample/websrc/favicon.ico DELETED Viewed

Binary file

package/examples/init_sample/websrc/hero-section.com.html DELETED Viewed

@@ -1,53 +0,0 @@
-<div class="hero">
-  <div>
-    <img src="./profile.png" alt="tkeron logo" class="logo" />
-    <h1>tkeron</h1>
-    <p class="subtitle">Build-time TypeScript for modern web development</p>
-  </div>
-  <div class="features">
-    <ul style="list-style: none">
-      <li>⚡ Fast builds with Bun</li>
-      <li>🎯 Build-time HTML generation</li>
-      <li>🧩 HTML & TypeScript components</li>
-      <li>🔧 Pure TypeScript & HTML</li>
-    </ul>
-  </div>
-  <div style="margin-top: 1.5rem; display: flex; gap: 0.75rem; width: 100%">
-    <a
-      href="https://www.npmjs.com/package/tkeron"
-      target="_blank"
-      style="
-        flex: 1;
-        padding: 0.65rem;
-        background: rgba(203, 56, 55, 0.9);
-        color: white;
-        text-decoration: none;
-        border-radius: 6px;
-        text-align: center;
-        font-weight: 600;
-        font-size: 0.85rem;
-        transition: background 0.2s;
-      "
-    >
-      📦 npm
-    </a>
-    <a
-      href="https://github.com/tkeron/tkeron"
-      target="_blank"
-      style="
-        flex: 1;
-        padding: 0.65rem;
-        background: rgba(36, 41, 46, 0.9);
-        color: white;
-        text-decoration: none;
-        border-radius: 6px;
-        text-align: center;
-        font-weight: 600;
-        font-size: 0.85rem;
-        transition: background 0.2s;
-      "
-    >
-      ⭐ GitHub
-    </a>
-  </div>
-</div>

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

@@ -1,17 +0,0 @@
-// TypeScript component - runs at build time with logic
-const count = com.getAttribute("count") || "3";
-const numCount = parseInt(count, 10);
-// Generate list dynamically
-const items = [];
-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("")}
-    </ul>
-  </div>
-`;

/package/examples/init_sample/websrc/{profile.png → assets/profile.png} RENAMED Viewed

File without changes

/package/examples/init_sample/websrc/{html-components-card.com.html → components/ui/html-components-card.com.html} RENAMED Viewed

File without changes