npm - templa-js - Versions diffs - 0.10.0 - Mend

templa-js 0.10.0

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 (20) hide show

package/AGENTS.md +413 -0
package/LICENSE +21 -0
package/PLANNER.md +285 -0
package/README.md +326 -0
package/bin/templa.js +549 -0
package/examples/_partials/about-body.html +8 -0
package/examples/_partials/common-footer.html +6 -0
package/examples/_partials/common-head.html +4 -0
package/examples/_partials/common-header.html +15 -0
package/examples/_partials/common-layout.html +5 -0
package/examples/_partials/common-subhero.html +7 -0
package/examples/_partials/index-cta.html +8 -0
package/examples/_partials/index-features.html +13 -0
package/examples/_partials/index-hero.html +9 -0
package/examples/about.html +14 -0
package/examples/css/style.css +16 -0
package/examples/index.html +15 -0
package/examples/serve.json +1 -0
package/package.json +40 -0
package/templa.js +266 -0

package/PLANNER.md ADDED Viewed

@@ -0,0 +1,285 @@
+# PLANNER.md — AI orchestrator prompt for templa project skeletons
+You are about to design the **skeleton** of a templa project from a free-form site brief. Read this entire file before doing anything. Your single deliverable is a written plan in chat — the user will save it as `plan.md` at their project root if they accept it. **You will not create or modify any files in this step.**
+If you have not already, also read `AGENTS.md` (same directory). It is the source of truth for templa's two-phase workflow, syntax, and conventions. This file complements `AGENTS.md`; it does not replace it.
+## Your role
+You are the orchestrator. Given a free-form site brief, your job is to produce a complete, executable plan — detailed enough that downstream sub-agents (or you, in a follow-up step) can implement the skeleton without asking another question.
+The plan covers the serial part of building a templa site: design tokens, layout, chrome partials, and empty page shells. Parallel content fill happens after this plan is approved and the skeleton built.
+## Hard rules
+1. **Do not create or modify any file.** Output the plan only. The user reviews and approves before any implementation step.
+2. **Do not run any build, `npm`, or shell command.** This is a planning step.
+3. **Default to the canonical `common-*` set** — `common-head`, `common-layout`, `common-header`, `common-footer`, `common-subhero`. Add a new `common-*` template only when the brief unambiguously needs one (e.g. a recurring site-wide CTA banner). Each addition is a cost, not a default.
+4. **Honor templa conventions.** `common-layout.html` is a body fragment (no `<html>` / `<body>`). Partials receive data via plain HTML attributes; `data-*` attributes are reserved as metadata and skipped. Section files ship with co-located `<style data-merge="css/style.css">` blocks and class names matching the filename.
+5. **If something in the brief is ambiguous, list it under "Open questions" at the end of the plan.** Do not invent and do not guess silently.
+## Project layout assumed by this plan
+All paths in the plan are relative to the **project root**. The expected layout:
+```
+project-root/
+├── plan.md            ← this plan, lives here
+├── src/               ← templa source (build input)
+│   ├── css/style.css
+│   ├── _partials/
+│   ├── assets/        ← images, copied to dist/ as-is
+│   └── *.html         ← entry pages
+└── dist/              ← build output (gitignored, not authored)
+```
+The build command is therefore `npx templa-js build -i ./src -o ./dist` (the templa CLI defaults). `plan.md` stays at root and is never inside `src/` (so it never leaks into the build output).
+## Input you will receive
+A free-form site brief from the user. It may include any of:
+- Project name and one-line pitch
+- Target audience
+- Brand vibe (warm / clean / playful / minimal / dark / editorial / …)
+- Color or typography hints
+- Pages they want
+- Content sections per page
+- Specific features (FAQ, contact form, image gallery, blog, pricing table, …)
+It may be a single paragraph or several pages. Read it twice. Extract intent before writing.
+## Process — walk these in order
+### 1. Restate the brief in 3–5 lines
+Compress the user's brief to its essentials. Confirms you understood and surfaces any gap.
+### 2. Decide the page set
+List every entry HTML file the site will produce. Default minimum: `index.html`. Add pages named or strongly implied by the brief (`about.html`, `contact.html`, `products.html`, `pricing.html`, …). Pages are bare filenames at the source root.
+### 3. Wireframe + section list per page
+For each page, produce **both**:
+(a) A small ASCII wireframe showing the visual structure top-to-bottom, including grid arrangements (e.g. cards in 3 columns), and labelling each section. Keep it readable — boxes drawn with `┌─┬─┐` style, ~40–60 chars wide. Show the layout chrome (header, footer) so the sub-agent sees the full page envelope.
+(b) A concise section list under the wireframe with one-line notes per section (filename, purpose, `common-*` template used if any, attributes it accepts).
+Example for a home page:
+```text
+┌────────────────────────────────────────┐
+│ HEADER (brand · nav)                   │
+├────────────────────────────────────────┤
+│                                        │
+│              HERO                      │
+│           [bg image]                   │
+│           Tea, slowly                  │
+│         [Browse our teas]              │
+│                                        │
+├────────────────────────────────────────┤
+│  A few favourites                      │
+│  ┌──────┐ ┌──────┐ ┌──────┐             │
+│  │ card │ │ card │ │ card │             │
+│  └──────┘ └──────┘ └──────┘             │
+├────────────────────────────────────────┤
+│  Questions                             │
+│  ▶ Q1                                  │
+│  ▶ Q2                                  │
+│  ▶ Q3                                  │
+├────────────────────────────────────────┤
+│ FOOTER                                 │
+└────────────────────────────────────────┘
+```
+Sections (top → bottom):
+- `_partials/index-hero.html` — landing hero, attrs image / heading / subheading / ctaLabel / ctaHref. Optional fields wrapped in `<template if="ctaLabel">` inside the section.
+- `_partials/index-favourites.html` — section with `<h2>` + grid of 3 inline `<article>` cards (no separate template; markup lives in this section file)
+- `_partials/index-faq.html` — inline Alpine accordion (lives only on this page)
+The wireframe is for both you (the orchestrator confirming structure) and the content sub-agent who will implement the page.
+### 4. Decide the section list per page
+For each page in §2, list the section files that will exist as `_partials/[pagename]-[sectionname].html`. The wireframe in §3 gives you the order; this step turns that into a flat file list.
+Use the shared `common-subhero.html` for inner-page headers — do not introduce per-page subhero variants. Anything else gets its own `[pagename]-[sectionname].html` file.
+If a non-trivial section type would recur across two or more pages (testimonials, blog post snippets, team-member cards, pricing rows), surface it as an "open question" at the end of the plan rather than silently inventing a new `common-*`. The orchestrator decides whether to extend Phase 1 with a new `common-*` template or to inline the duplication across pages.
+### 5. Decide design tokens
+Pick concrete values; do not stay vague. Provide all of:
+- **Color** — 4–6 CSS-variable tokens with real hex codes that suit the inferred vibe:
+  `--color-bg`, `--color-surface`, `--color-text`, `--color-muted`, `--color-accent`, `--color-accent-dark`, `--color-border`.
+- **Typography** — one serif heading family + one sans body family. Use real Google Fonts names with the matching `family=` URL.
+- **Spacing scale** — `--space-1` … `--space-7` (`.25rem` … ~`4rem`). The default scaffold ships these; tune values to fit the brief.
+- **Radius / shadow** — 1–2 values each.
+- **Container widths** — `--max-w` (text column, ~720px) and optionally `--max-w-wide` (~1100px).
+If the brief was vague on aesthetics, infer from the project type and brand vibe and note explicitly that the values are an inference the user can override.
+### 6. Decide the `common-*` templates
+(All paths below are project-root relative.)
+- **`src/_partials/common-head.html`** — `<head>` chrome: charset, viewport, theme-color, font preconnect/links, `./css/style.css` link. Title comes from the page's `<template src="…common-head.html" title="…">` attribute.
+- **`src/_partials/common-layout.html`** — body fragment: invokes `common-header`, wraps a default `<slot>` in `<main>`, invokes `common-footer`.
+- **`src/_partials/common-header.html`** — `<header>` element: brand + navigation anchors, each with `data-nav="<page-id>"` for active styling driven by `body[data-page="..."]` selectors in `src/css/style.css`.
+- **`src/_partials/common-footer.html`** — `<footer>` element with copyright/social, identical on every page.
+- **`src/_partials/common-subhero.html`** — `<section>` for inner-page headers, parameterized by `title` and optionally `bg`. Used by every page except the home page.
+A project may add more `common-*` (rare). If you add any, justify it in §7's open questions.
+### 7. Produce the file inventory
+A complete listing of every file the skeleton will create, **paths relative to the project root**. Each line: path + a one-line role comment. Group by purpose. Example skeleton for a 3-page site (home, about, contact):
+```text
+src/css/style.css                       // tokens + base + chrome (locked in Phase 1)
+src/_partials/common-head.html          // <head> chrome (charset, viewport, fonts, css link)
+src/_partials/common-layout.html        // body skeleton: header / main slot / footer
+src/_partials/common-header.html        // <header>: brand + nav with data-nav
+src/_partials/common-footer.html        // <footer>: copyright + socials
+src/_partials/common-subhero.html       // shared inner-page subhero (title, optional bg)
+src/_partials/index-hero.html           // index — landing hero (sub-agent owned)
+src/_partials/index-features.html       // index — features list
+src/_partials/index-cta.html            // index — closing CTA
+src/_partials/about-body.html           // about — prose / company story
+src/_partials/contact-form.html         // contact — contact form
+src/_partials/contact-map.html          // contact — embedded map
+src/index.html                          // page entry — sections: hero, features, cta
+src/about.html                          // page entry — sections: subhero, body
+src/contact.html                        // page entry — sections: subhero, form, map
+src/assets/                             // images / fonts / etc., copied to dist/ as-is
+```
+Every `[pagename]-[sectionname].html` listed above is a unit of Phase 2 sub-agent work. Every `common-*.html` is locked after Phase 1.
+### 8. Sketch the section-fill dispatch
+One sub-agent per `[pagename]-[sectionname].html` file. For each, give a 2–3-line brief: what the section contains, which design tokens to reach for, any image/asset references, any Alpine.js bits to author inline.
+The dispatch is genuinely parallel — none of the section files share file content, so sub-agents never collide.
+Example:
+- Sub-agent A → `src/_partials/index-hero.html` — large landing hero, headline + subhead + CTA button. Use `--space-7` top padding, `--font-display` for the headline.
+- Sub-agent B → `src/_partials/index-features.html` — 3-column grid of feature cards (inline `<article>` markup; no shared partial). Use `--space-5` between rows.
+- Sub-agent C → `src/_partials/index-cta.html` — closing CTA strip with `--color-accent` background.
+- Sub-agent D → `src/_partials/about-body.html` — prose-style "company story" article with one image.
+- Sub-agent E → `src/_partials/contact-form.html` — `<form action="contact.php">` with name/email/message fields, inline Alpine validation if the brief asks.
+- Sub-agent F → `src/_partials/contact-map.html` — Google Maps `<iframe>` embed.
+### 9. State the build gate command
+End the plan with this line, verbatim:
+```bash
+npx templa-js build -i ./src -o ./dist
+```
+This is the gate that separates skeleton from content fill. Content sub-agents must not be dispatched until this command succeeds against the placeholder skeleton.
+## Output format — your reply takes this shape
+```markdown
+# Plan: <project name>
+## 1. Brief, restated
+…
+## 2. Page set
+- src/index.html — …
+- src/about.html — …
+## 3. Wireframes + sections per page
+### index.html
+```text
+┌──────────────────────────────────────┐
+│ HEADER                               │
+├──────────────────────────────────────┤
+│            HERO                      │
+├──────────────────────────────────────┤
+│ A few favourites                     │
+│ ┌────┐ ┌────┐ ┌────┐                  │
+│ └────┘ └────┘ └────┘                  │
+├──────────────────────────────────────┤
+│ Questions (FAQ accordion)            │
+├──────────────────────────────────────┤
+│ FOOTER                               │
+└──────────────────────────────────────┘
+```
+- `_partials/index-hero.html` — landing hero, attrs image/heading/subheading/ctaLabel/ctaHref
+- `_partials/index-favourites.html` — 3-column grid of inline `<article>` cards
+- faq — inline Alpine accordion
+### about.html
+```text
+┌──────────────────────────────────────┐
+│ HEADER                               │
+├──────────────────────────────────────┤
+│           SUB-HERO                   │
+├──────────────────────────────────────┤
+│           PROSE                      │
+│            ¶ ¶ [img] ¶ ¶              │
+├──────────────────────────────────────┤
+│ FOOTER                               │
+└──────────────────────────────────────┘
+```
+- `_partials/common-subhero.html` — shared subhero, attrs title/tagline
+- prose — `<article class="prose">` with 4 paragraphs and 1 image
+## 4. Section list per page
+- index — sections: index-hero, index-features, index-cta
+- about — sections: common-subhero (title="About"), about-body
+## 5. Design tokens
+```css
+:root {
+  --color-bg: #faf8f3;
+  --color-text: #1f1f1c;
+  /* … */
+}
+```
+Fonts: Inter (body), Lora (headings).
+(Note: tokens inferred from the "warm, slow" vibe; override if you want.)
+## 6. common-* templates
+- src/_partials/common-head.html — charset, viewport, theme-color, fonts, ./css/style.css
+- src/_partials/common-layout.html — header / <main><slot/></main> / footer
+- src/_partials/common-header.html — brand + nav with data-nav
+- src/_partials/common-footer.html — copyright + socials
+- src/_partials/common-subhero.html — inner-page subhero (title attribute)
+## 7. File inventory
+```text
+… full listing per the example above …
+```
+## 8. Section-fill dispatch
+- Sub-agent A → src/_partials/index-hero.html — landing hero with image + CTA
+- Sub-agent B → src/_partials/index-features.html — 3-column features grid
+- Sub-agent C → src/_partials/index-cta.html — closing CTA strip
+- Sub-agent D → src/_partials/about-body.html — prose "about us" article
+## 9. Build gate
+```bash
+npx templa-js build -i ./src -o ./dist
+```
+## Open questions
+- (only if any; otherwise omit this section)
+```
+End the plan with one line:
+> Plan complete — awaiting user approval before any file is written.
+## After you finish
+Stop. Wait for the next instruction. Implementation (writing files, building, dispatching content sub-agents) is a separate step driven by a different prompt or an upcoming SKILL.

package/README.md ADDED Viewed

@@ -0,0 +1,326 @@
+# templa
+> 🍤 A tiny HTML template loader. Pronounced **"tempura"**.
+>
+> Wraps your data in `<template src>` like batter wraps ingredients.
+`templa` is a tiny dependency-free script that lets you split HTML into reusable partials, pass parameters, and use Handlebars-like syntax — all powered by the native `<template>` element.
+It works in two modes:
+- **Runtime** (`templa.js`) — partials are fetched and inlined in the browser
+- **Build** (`npx templa-js build`) — partials are inlined ahead of time into static HTML
+```html
+<!-- index.html -->
+<body>
+  <template src="_partials/header.html" title="Home" loggedIn="yes"></template>
+  <main>...</main>
+  <template src="_partials/footer.html"></template>
+  <script src="templa.js"></script>
+  <script type="module">await templa.start();</script>
+</body>
+```
+```html
+<!-- _partials/header.html -->
+<header>
+  <h1>{{title}}</h1>
+  <template if="loggedIn">
+    <a href="/logout">Logout</a>
+  </template>
+  <template unless="loggedIn">
+    <a href="/login">Login</a>
+  </template>
+</header>
+```
+## Why templa?
+- **No build step** — drop in a `<script>` tag
+- **No dependencies** — pure vanilla JavaScript
+- **Standard HTML** — uses the native `<template>` element, not custom tags
+- **Tiny** — ~240 lines of source, ~3.5KB gzipped
+- **HTML-native** — `{{var}}` for values; `<template if>` / `<template unless>` for conditionals
+- **Recursive** — partials inside partials just work
+- **Resource-aware** — waits for `<link rel="stylesheet">` and `<script src>` inside partials before resolving
+## Install
+### Via `<script>` tag (CDN)
+```html
+<!-- minified (auto-generated by jsDelivr) -->
+<script src="https://cdn.jsdelivr.net/npm/templa-js/templa.min.js"></script>
+<!-- or unminified, for debugging -->
+<script src="https://cdn.jsdelivr.net/npm/templa-js/templa.js"></script>
+```
+> jsDelivr serves `templa.min.js` by minifying the source on the fly, so there is no separate minified file to maintain. Pin a version with `templa-js@0.0.1` if you want immutable URLs.
+### Via npm
+```bash
+npm install templa-js
+```
+## Init
+Bootstrap a new project in the current directory:
+```bash
+npx templa-js init           # minimal src/ tree
+npx templa-js init --ai      # also write AGENTS.md and PLANNER.md
+npx templa-js init --force   # overwrite existing files
+```
+The result is a buildable project: run `npx templa-js build` immediately afterwards and `dist/` will be produced. The `--ai` flag adds two project-root markdown files that brief AI coding agents on templa's conventions and a planning prompt for site skeletons.
+## Usage
+### Basic
+Mark any place you want a partial with a `<template>` element:
+```html
+<template src="_partials/nav.html"></template>
+```
+Then call `templa.start()` to expand all of them:
+```html
+<script src="templa.js"></script>
+<script type="module">
+  await templa.start();
+  // any post-init: Alpine.initTree(document.body), AOS.init(), Swiper, …
+</script>
+```
+`templa.start()` returns a Promise that resolves once head + body partials have been expanded. The module-script form is required for top-level `await`. Anything written after the `await` runs once the DOM has been fully assembled — perfect for plugins like Alpine.js, AOS, Swiper, etc.
+### Passing data
+Each attribute on the calling `<template>` becomes a string-valued data key inside the partial.
+```html
+<template src="_partials/card.html" title="Hello" body="Welcome."></template>
+```
+Conditionals (`<template if="key">`) are existence-based, so any non-empty string is truthy — `featured="yes"` is enough to enable a block.
+Reserved attributes — these are not collected as data: `src` (the partial path), `slot` (slot filler name), `if` / `unless` (conditional markers). Any `data-*` attribute is also skipped, by HTML metadata convention.
+### Template syntax
+| Syntax | Effect |
+|---|---|
+| `{{key}}` | HTML-escaped variable |
+| `{{{key}}}` | Raw variable (no escape) — use only for trusted HTML |
+| `<template if="key">…</template>` | Block kept when `data[key]` is truthy |
+| `<template unless="key">…</template>` | Block kept when `data[key]` is falsy |
+Conditionals can be nested. Variables fall through unchanged when the key is missing from `data`.
+### Layouts and slots
+A partial can declare insertion points with `<slot>`. Pages fill those slots by writing content inside the calling `<template src>`.
+Keep layouts as **body fragments** (no `<!DOCTYPE>` / `<html>` / `<head>` / `<body>` wrapper) so they work in both runtime and build modes. Each page provides its own document skeleton and embeds the layout where the body content goes.
+```html
+<!-- _layouts/main.html (body fragment) -->
+<header><slot name="nav">Default Nav</slot></header>
+<main><slot></slot></main>
+<footer><slot name="footer">&copy; 2026</slot></footer>
+```
+```html
+<!-- page.html -->
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Home</title>
+</head>
+<body>
+  <template src="_layouts/main.html">
+    <template slot="nav">
+      <a href="/">Home</a>
+      <a href="/about">About</a>
+    </template>
+    <h1>Welcome</h1>
+    <p>Anything outside &lt;template slot&gt; goes into the default slot.</p>
+    <!-- footer slot is omitted, so its fallback renders -->
+  </template>
+  <script src="https://cdn.jsdelivr.net/npm/templa-js/templa.min.js"></script>
+  <script type="module">await templa.start();</script>
+</body>
+</html>
+```
+Rules:
+- `<slot>` (no name) receives every node from the calling `<template>` that is not wrapped in `<template slot="...">`.
+- `<slot name="X">` receives the content of the matching `<template slot="X">` filler.
+- A slot's own children are the **fallback** — they render when no filler is supplied.
+- Slot fillers may themselves contain `<template src="...">` partials; they are expanded recursively in the call site's directory context.
+This pattern works identically with the build CLI — `npx templa-js build` inlines the layout into the output and you can drop the script tags.
+### Nested partials
+Partials can include other partials. `templa` keeps expanding until no `<template src>` remains.
+### Loading order
+`templa.start()` kicks off head expansion **synchronously** so its fetches overlap with the rest of HTML parsing — critical when partials in `<head>` include `<link rel="stylesheet">`. Body expansion waits for `DOMContentLoaded`. The returned Promise resolves once both phases complete.
+### Relative paths in nested partials
+`<template src>` inside a partial is resolved relative to **that partial's URL**, not the page. So `_partials/layout.html` can reference `<template src="./header.html">` and it will resolve to `_partials/header.html` correctly.
+Other resources (`<img src>`, `<link href>`, `<script src>`) still resolve against the page URL — use absolute or root-relative paths for those.
+### Co-located styles
+A partial can carry its own CSS in a `<style>` block tagged with `data-merge="<file>"`. The build CLI extracts it once per partial and appends it to the named output stylesheet — even if the partial is used 100 times, its rules are written exactly once.
+```html
+<!-- _partials/card.html -->
+<style data-merge="style.css">
+  .card { background: #fff; border: 1px solid #ddd; padding: 1rem; }
+</style>
+<article class="card">
+  <h3>{{title}}</h3>
+</article>
+```
+At runtime, the same dedupe applies: the `<style>` block stays in the DOM for the first expansion of a given partial and is stripped on subsequent ones. A `<style>` without `data-merge` is treated as plain inline CSS (existing behaviour).
+### Caching and recursion
+- Identical `<template src>` URLs are fetched once per page (in-memory cache).
+- A safety guard stops expansion after 50 passes to prevent infinite loops from circular includes.
+## API
+### `templa.start()`
+Loads all `<template src>` elements (head first, then body). Returns a Promise that resolves once everything is mounted. Use with `await` from a `<script type="module">`.
+### `templa.run(selector?)`
+Lower-level: runs a single expansion pass against `selector` (default: `'template[src]'`). Returns a Promise. Useful if you load partials dynamically.
+```js
+await templa.run('#my-region template[src]');
+```
+## Content Security Policy
+The runtime never calls `eval` or `new Function`. There is no `'unsafe-eval'` requirement; a plain `script-src 'self'` works.
+For pages that don't need a runtime at all, build with `npx templa-js build` — the output is plain HTML with no template syntax left.
+## Caveats
+- `{{key}}` HTML-escapes its value. If you need to inject HTML, use `{{{key}}}` and make sure the value is trusted.
+- Original `<template src>` elements are removed from the DOM after expansion.
+- This project is in early development (0.0.x). API may change.
+## Build (CLI)
+For static deployment, expand all `<template src>` ahead of time:
+```bash
+npx templa-js build -i ./src -o ./dist
+```
+The CLI reads every `.html` file under the source directory, recursively inlines its partials with the same syntax as the runtime, and writes the result to the output directory.
+### File convention
+Files and directories whose names start with `_` are treated as partials and are **not** copied to the output:
+```
+src/
+├── index.html              ← entry, written to dist/
+├── about.html              ← entry, written to dist/
+└── _partials/              ← skipped (partials only)
+    ├── header.html
+    └── footer.html
+```
+Reference partials with a relative path:
+```html
+<template src="_partials/header.html" title="Home"></template>
+```
+### Options
+| Flag | Default | Description |
+|---|---|---|
+| `-i <dir>` | `./src` | Source directory |
+| `-o <dir>` | `./dist` | Output directory (cleared before each build) |
+| `--version` | | Print version |
+| `--help` | | Print usage |
+### Build vs runtime
+Both modes share the same template syntax, so a partial works in either:
+| | Runtime (`templa.js`) | Build (`npx templa-js`) |
+|---|---|---|
+| When partials are inlined | At page load, in the browser | Once, ahead of time |
+| Dependencies | none | none |
+| Output | dynamic DOM | static HTML files |
+| Use case | quick prototypes, dev | production deploy, SEO, static hosting |
+You can also use both: ship the static HTML for first paint and keep `templa.js` for any partials you want to load dynamically later.
+## Recommended companion: Alpine.js
+`templa` handles **composition** (partials, layouts, variables, conditionals at build or load time). For **interactive behaviour** (modals, dropdowns, counters, form state), pair it with [Alpine.js](https://alpinejs.dev/) — also HTML-first, no build step, ~15&nbsp;KB.
+```html
+<!-- somewhere in your <head> -->
+<script src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js" defer></script>
+<!-- in any partial -->
+<section x-data="{ open: false }">
+  <button @click="open = !open">Toggle</button>
+  <div x-show="open">Hidden until clicked.</div>
+</section>
+```
+Decision rule: templa for everything that can be resolved before the user clicks; Alpine for everything that depends on user interaction.
+## Working with AI agents
+If you use Claude Code, Cursor, Aider, Copilot, or similar AI tools, two files do most of the work:
+- [`AGENTS.md`](./AGENTS.md) — file conventions, two-phase workflow, syntax, common pitfalls. Drop it into a templa project root and the agent reads it as the source of truth.
+- [`PLANNER.md`](./PLANNER.md) — an instruction prompt that turns a free-form site brief into a concrete `plan.md` (page set, wireframes, section list, design tokens, file inventory) before any file is written.
+## Philosophy
+templa is not trying to replace HTML. It exists because HTML does not yet have a native way to include partials, compose layouts, and pass small pieces of data between templates.
+**The biggest competitor is native HTML. That is also the goal.** If one day HTML supports this natively, templa has done its job. Until then, templa is a tiny bridge.
+Concrete consequences of that stance:
+- Attribute names follow the platform: `<template src>` mirrors `<img src>` / `<script src>` / `<iframe src>`. We deliberately don't use `data-src`. The bare `src` lets editors and IDEs treat it like a real file reference (path completion, jump-to-file, refactor-rename).
+- Conditionals are written as `<template if="key">…</template>` and `<template unless="key">…</template>` — no `{{#if}}` Mustache block, no expressions, no helpers. They are existence-based only.
+- Co-located styles use `data-merge="style.css"` — a `data-*` attribute, because that is HTML's documented hook for component-private metadata.
+- Anything beyond block-level conditionals (conditional attributes, dynamic class lists, loops) is out of scope for the core and lives in plugins.
+The core stays small enough to read in one sitting. Everything else is a plugin.
+## License
+[MIT](./LICENSE)