miki-template 1.3.3 → 1.3.6

package/.github/release-notes/v1.3.1.md

@@ -1,55 +1,55 @@
-# miki-template v1.3.1
-
-## Highlights
-
-- **One-line Express integration**: `miki.setupExpress(app, { extension: 'html', views: dir })` wires the view engine, the views directory, and a `res.render` shim that makes HTMX-style partial responses Just Work.
-
-  ```js
-  const express = require('express');
-  const miki = require('miki-template');
-
-  const app = express();
-  miki.setupExpress(app, { extension: 'html', views: './views' });
-
-  // Full page
-  app.get('/', (req, res) => res.render('home', { user: req.user }));
-
-  // Partial — just append `#partialName` to the view name
-  app.get('/partials/:name', (req, res) =>
-    res.render(`home#${req.params.name}`, { user: req.user })
-  );
-  ```
-
-- **`miki.expressPartialRenderer()` middleware** for drop-in `res.renderPartial(view, locals)` without changing your existing `app.engine()` setup.
-- **`miki.express()`** factory for `app.engine('html', miki.express())` — honors `view#partial` selectors.
-- **`renderPartialFromSource(source, partialName, ctx, opts)`** and **`renderPartialFromFile(...)`** — render a single named `{% partialdef %}` from a string or file. Walks the AST (and the `extends` chain) to find partials nested inside blocks.
-- **`{% include "file.html#partial" with ... %}`** — partial-selector syntax works with `include`, not just `res.render`.
-- **Built-in libraries** (`humanize`, `cache`, `lorem`) are now auto-activated on module load. `{% lorem 5 p %}` works without `{% load lorem %}`.
-
-## Tag fixes
-
-- `{% with x=1, y=2 as pair %}` (multi-pair + alias) parses correctly.
-- `{% with a=x b=y %}` (multi-pair, no alias) now binds each pair instead of being treated as one expression.
-- `{% cycle 'a' 'b' as name %}` now emits nothing but stores the value (Django semantics).
-- `{{ block.super }}` works inside partials that override blocks.
-- `extends` resolves `views` from `options.settings.views` (Express path), `options.views`, or default.
-- Path-traversal protection applies to `extends` *and* `include`, including `include "file#partial"`.
-- `default` vs `default_if_none`: `default` falls back on `''`, `null`, and `undefined`; `default_if_none` only on `null`/`undefined` (Django parity).
-- `removetags` accepts multiple tag names.
-- `Context.get('a.b.c')` returns `undefined` for missing keys (was `''`), so `{% if x %}` and `default_if_none` work correctly.
-
-## Test coverage
-
-**382/382 tests pass.** Added a 190-test integration suite (`tests/integration/`) covering every tag, filter, and feature under both CommonJS and ESM, exercised against a real Express HTTP server on ephemeral ports. The test runner recursively picks up `.test.{cjs,mjs,js}` files.
-
-## Docs
-
-- `README.md` — promoted `miki.setupExpress` to the first listed feature; the Express section leads with the one-liner.
-- `docs/usage.md` — full Express section rewritten with the new setup, options table, and middleware variant.
-- `docs/api.md` — added rows for the new APIs; updated CJS/ESM import snippets.
-- `docs/partialdef.md` — documented `include "file#partial"`, `renderPartialFromSource/File`, and the HTMX-over-HTTP flow.
-- `CHANGELOG.md` — full entry for 1.3.1.
-
-## Compatibility
-
-No breaking changes. All existing public APIs continue to work; new APIs are opt-in.
+# miki-template v1.3.1
+
+## Highlights
+
+- **One-line Express integration**: `miki.setupExpress(app, { extension: 'html', views: dir })` wires the view engine, the views directory, and a `res.render` shim that makes HTMX-style partial responses Just Work.
+
+  ```js
+  const express = require('express');
+  const miki = require('miki-template');
+
+  const app = express();
+  miki.setupExpress(app, { extension: 'html', views: './views' });
+
+  // Full page
+  app.get('/', (req, res) => res.render('home', { user: req.user }));
+
+  // Partial — just append `#partialName` to the view name
+  app.get('/partials/:name', (req, res) =>
+    res.render(`home#${req.params.name}`, { user: req.user })
+  );
+  ```
+
+- **`miki.expressPartialRenderer()` middleware** for drop-in `res.renderPartial(view, locals)` without changing your existing `app.engine()` setup.
+- **`miki.express()`** factory for `app.engine('html', miki.express())` — honors `view#partial` selectors.
+- **`renderPartialFromSource(source, partialName, ctx, opts)`** and **`renderPartialFromFile(...)`** — render a single named `{% partialdef %}` from a string or file. Walks the AST (and the `extends` chain) to find partials nested inside blocks.
+- **`{% include "file.html#partial" with ... %}`** — partial-selector syntax works with `include`, not just `res.render`.
+- **Built-in libraries** (`humanize`, `cache`, `lorem`) are now auto-activated on module load. `{% lorem 5 p %}` works without `{% load lorem %}`.
+
+## Tag fixes
+
+- `{% with x=1, y=2 as pair %}` (multi-pair + alias) parses correctly.
+- `{% with a=x b=y %}` (multi-pair, no alias) now binds each pair instead of being treated as one expression.
+- `{% cycle 'a' 'b' as name %}` now emits nothing but stores the value (Django semantics).
+- `{{ block.super }}` works inside partials that override blocks.
+- `extends` resolves `views` from `options.settings.views` (Express path), `options.views`, or default.
+- Path-traversal protection applies to `extends` *and* `include`, including `include "file#partial"`.
+- `default` vs `default_if_none`: `default` falls back on `''`, `null`, and `undefined`; `default_if_none` only on `null`/`undefined` (Django parity).
+- `removetags` accepts multiple tag names.
+- `Context.get('a.b.c')` returns `undefined` for missing keys (was `''`), so `{% if x %}` and `default_if_none` work correctly.
+
+## Test coverage
+
+**382/382 tests pass.** Added a 190-test integration suite (`tests/integration/`) covering every tag, filter, and feature under both CommonJS and ESM, exercised against a real Express HTTP server on ephemeral ports. The test runner recursively picks up `.test.{cjs,mjs,js}` files.
+
+## Docs
+
+- `README.md` — promoted `miki.setupExpress` to the first listed feature; the Express section leads with the one-liner.
+- `docs/usage.md` — full Express section rewritten with the new setup, options table, and middleware variant.
+- `docs/api.md` — added rows for the new APIs; updated CJS/ESM import snippets.
+- `docs/partialdef.md` — documented `include "file#partial"`, `renderPartialFromSource/File`, and the HTMX-over-HTTP flow.
+- `CHANGELOG.md` — full entry for 1.3.1.
+
+## Compatibility
+
+No breaking changes. All existing public APIs continue to work; new APIs are opt-in.

package/.github/release-notes/v1.3.3.md

@@ -0,0 +1,77 @@
+# miki-template v1.3.3
+
+## Highlights
+
+- **Date/time filter fixed** — `{{ d|date:"yyyy-MM-dd" }}` now returns `"2024-06-15"` instead of `"24242424-JunJun-1515"`. Multi-character tokens (`yyyy`, `MM`, `dd`, `HH`, `mm`, `ii`, `ss`) are matched longest-first; backward-compatible single-character aliases (`m`/`d`/`H`/`i`/`s`) still work for Django-style unpadded values.
+- **Inheritance 4× faster** — `{% extends %}` no longer re-reads the parent file from disk on every render. A 64-entry LRU cache in `src/cache.js` memoises the parent source. Inheritance rendering improved from ~481 rps to **~2,056 rps** in the strict benchmark.
+
+## Installation
+
+```bash
+npm install miki-template@1.3.3
+```
+
+## Quick start
+
+```js
+const miki = require('miki-template');
+const express = require('express');
+
+const app = express();
+miki.setupExpress(app, { extension: 'html', views: './views' });
+
+// Full page
+app.get('/', (req, res) => res.render('home', { user: req.user }));
+
+// HTMX partial — just append #partialName
+app.get('/partials/:name', (req, res) =>
+  res.render(`home#${req.params.name}`, { user: req.user })
+);
+
+app.listen(3000);
+```
+
+## What's changed
+
+### Fixed
+- `date` and `time` filters — multi-character tokens render correctly.
+
+### Performance
+- Inheritance parent-source LRU cache in `src/cache.js` (`getParentSource` / `hasParentSource`). `clearCache()` also clears it.
+
+### Tooling
+- New `benchmarks/stress.mjs` — 37-check strict benchmark (correctness, compile speed, render speed, cache, scale, endurance, partial rendering, async, concurrency). Run with `node benchmarks/stress.mjs`. Exits with code 1 on any failure.
+- `eslint.config.mjs` — added `URL`, `URLSearchParams`, `TextEncoder`, `TextDecoder`, `fetch`, `crypto`, `performance` to the Node 18+ globals list.
+- Removed dead code: unused `elifBranches` variable in `parseIfChanged`, unused `extractPluralMappings` function in `i18n.js`.
+- Renamed unused tag-parser `parser` parameters to `_parser` in `lorem` library and `parseLoad`.
+
+## Verification
+
+| Check | Result |
+|---|---|
+| `npx eslint src/**/*.js` | 0 errors, 0 warnings |
+| `npm test` | 397/397 passing |
+| `node benchmarks/stress.mjs` | 37/37 passing |
+
+## Performance (from the stress benchmark)
+
+| Template | Speed |
+|---|---|
+| Small (76 B) | **175,439 rps** (0.006 ms) |
+| Medium (595 B) | 13,947 rps (0.072 ms) |
+| Large (1.6 KB, 6 sections × 12 items) | 2,277 rps (0.439 ms) |
+| Inheritance child | 2,056 rps (0.486 ms) |
+| Partials (50 entries) | 2,235 rps (0.447 ms) |
+| Scale: 50,000 items | 107 ms median |
+| Endurance: 100,000 renders | 7.5s total, RSS +0.9 MB |
+| Async: 200 concurrent LARGE | 237 ms total |
+
+## Compatibility
+
+No breaking changes. All existing public APIs continue to work; new APIs are opt-in.
+
+## Links
+
+- **Repository**: https://github.com/alainmiki/miki-template
+- **Tag**: https://github.com/alainmiki/miki-template/releases/tag/v1.3.3
+- **Previous**: [v1.3.1](https://github.com/alainmiki/miki-template/releases/tag/v1.3.1)

package/.github/workflows/ci.yml

@@ -1,54 +1,38 @@
-# CI/CD Workflow
-
-name: CI
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-  release:
-    types: [ created ]
-
-jobs:
-  lint:
-    runs-on: windows-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - run: npm ci
-      - name: Lint code
-        run: npx eslint src/**/*.js
-
-  test:
-    runs-on: windows-latest
-    needs: lint
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - run: npm ci
-      - name: Run test suite
-        run: npm test
-
-  publish:
-    runs-on: windows-latest
-    needs: test
-    if: github.event_name == 'release' && github.event.action == 'created'
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-      - run: npm ci
-      - name: Publish package to npm
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+# CI Workflow — lint + test on every push and PR.
+#
+# Releases are handled by .github/workflows/release.yml, which triggers
+# automatically when a `chore(release):` commit lands on main.
+
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - name: Lint code
+        run: npx eslint src/**/*.js
+
+  test:
+    runs-on: windows-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - name: Run test suite
+        run: npm test

package/.github/workflows/release.yml

@@ -0,0 +1,106 @@
+# Release workflow
+#
+# Fully automatic release pipeline. Triggered when a commit to main matches
+# the `chore(release): v*` pattern produced by `npm run release:patch|minor|major`.
+#
+# Flow:
+#   1. Detect the new version in package.json.
+#   2. Lint + test + stress benchmark (must pass before continuing).
+#   3. Create an annotated git tag v<version> and push it.
+#   4. Create a GitHub Release with notes from .github/release-notes/v<version>.md
+#      (or a generic message if the file is missing).
+#   5. Publish the package to npm using the NPM_TOKEN secret.
+#
+# Local usage:
+#   npm run release:patch    # 1.3.3 → 1.3.4
+#   npm run release:minor    # 1.3.3 → 1.4.0
+#   npm run release:major    # 1.3.3 → 2.0.0
+# That bumps package.json, creates a commit, pushes to main, and the rest
+# happens here.
+
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    # Only run for the explicit "chore(release):" commits. Any other
+    # push to main is ignored so contributors can edit package.json
+    # without accidentally publishing.
+    if: startsWith(github.event.head_commit.message, 'chore(release):')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npx eslint src/**/*.js
+
+      - name: Test
+        run: npm test
+
+      - name: Stress benchmark
+        run: node benchmarks/stress.mjs
+
+      - name: Read package version
+        id: ver
+        run: echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+
+      - name: Check tag does not already exist
+        run: |
+          if git rev-parse "v${{ steps.ver.outputs.version }}" >/dev/null 2>&1; then
+            echo "::error::Tag v${{ steps.ver.outputs.version }} already exists."
+            exit 1
+          fi
+
+      - name: Create and push git tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "v${{ steps.ver.outputs.version }}" -m "v${{ steps.ver.outputs.version }}"
+          git push origin "v${{ steps.ver.outputs.version }}"
+
+      - name: Build release body
+        id: notes
+        env:
+          NOTES_FILE: .github/release-notes/v${{ steps.ver.outputs.version }}.md
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          {
+            echo "body<<EOF_RELEASE"
+            if [ -f "$NOTES_FILE" ]; then
+              cat "$NOTES_FILE"
+            else
+              echo "## v${VERSION}"
+              echo ""
+              echo "See [CHANGELOG.md](../../blob/main/CHANGELOG.md) for details."
+            fi
+            echo "EOF_RELEASE"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.ver.outputs.version }}
+          name: v${{ steps.ver.outputs.version }}
+          body: ${{ steps.notes.outputs.body }}
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/AGENT.md

@@ -1,71 +1,71 @@
-# AGENT.md - Agent Instructions, Guardrails, & Architecture Rules
-
-This repository implements a Django-Style Template Engine for Node.js/Express. To ensure high code quality, consistent architecture, and full feature parity with Django without guesswork, all AI agents and developers must strictly follow these instructions and guardrails.
-
----
-
-## 🎯 Core Objectives
-1. **Full Feature Parity**: Match Django's template engine rules for rendering variables, dotted lookups, built-in tags, filters, and template inheritance.
-2. **Deterministic & Secure**: Escape output by default using a safe-string mechanism.
-3. **No Spaghetti Code**: Maintain a strict separation of Lexer, Parser, Renderer, Context, and Tag/Filter registries.
-
----
-
-## ⚠️ Strict Guardrails & Anti-Hallucination Rules
-
-> [!IMPORTANT]
-> **No Guesswork / Assumptions**
-> - If a tag or filter's behavior is not clearly defined in [prd.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/prd.md) or Django documentation, **DO NOT guess**. 
-> - If you notice ambiguities (e.g., how to handle circular extends or nested cycles), raise a question to the user immediately or throw a descriptive compilation error.
-
-> [!WARNING]
-> **No Regex-Based Global Search & Replace**
-> - You **must not** implement tags or filters using global regex replacements on the final string. All templates must go through:
->   `Lexer (String -> Tokens) -> Parser (Tokens -> AST) -> Renderer (AST + Context -> HTML)`.
-> - Direct regex replacement on HTML bypasses nesting, escaping, and blocks, which introduces severe bugs.
-
-> [!CAUTION]
-> **Security Guardrails**
-> - All variable output must be HTML-escaped by default.
-> - A variable is only safe from escaping if it is marked as a `SafeString` (e.g., using the `safe` filter or internally flagged).
-> - Dynamic expression evaluation (such as in `if` tags) **must not** use direct JS `eval()`. Use a safe AST evaluator or sandboxed parser to prevent remote code execution.
-
----
-
-## 🧩 Architectural Guidelines
-
-### 1. Lexing (`src/lexer.js`)
-*   Tokens must be generated for three primary types:
-    - `TEXT`: Plain HTML/text.
-    - `VAR`: Variables wrapped in `{{ ... }}`.
-    - `BLOCK`: Structural tags wrapped in `{% ... %}`.
-*   The Lexer must correctly handle verbatim blocks `{% verbatim %}` and comments `{% comment %}` by suppressing token output or passing raw text tokens.
-
-### 2. Parsing (`src/parser.js`)
-*   The Parser takes a stream of tokens and constructs an AST of nodes.
-*   Every node must implement a `.render(context)` method (async or sync).
-*   For tags that have closing tags (e.g., `{% if %}`...`{% endif %}`), the parser must parse nested tokens recursively until the matching close tag is encountered.
-
-### 3. Context & Scope Isolation (`src/context.js`)
-*   Context must support a stack-like structure: `.push()` to create a new scope, and `.pop()` to revert.
-*   **Variable Lookups**: Support dotted lookups:
-    - Example: `{{ user.profile.name }}` should search `user` in context, then resolve property `profile`, then property `name`.
-    - If a resolved value is a function, call it (without arguments, just like Django).
-    - If a lookup fails, return an empty string `""` by default, unless configured otherwise.
-
-### 4. Template Inheritance (`src/tags/inheritance.js`)
-*   Inheritance works by having a child template load a parent template via `{% extends "parent.html" %}`.
-*   The child overrides blocks defined as `{% block block_name %}`.
-*   During render, the parent's AST is evaluated, but block nodes are replaced by the child's corresponding block nodes.
-*   Support block nesting and the `{{ block.super }}` variable to render parent block content.
-
----
-
-## 🛠️ Step-by-Step Task Execution Protocol
-
-When executing tasks:
-1. **Analyze Requirements**: Check [prd.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/prd.md) and [component.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/component.md).
-2. **Check Existing Tests**: Run current test suite using `npm test` or `node --test` to ensure a green state.
-3. **Write Tests First**: For any new filter, tag, or parser logic, write a corresponding unit test in `tests/` showing the expected template string and its expected output.
-4. **Implement Modular Code**: Put tag handlers in `src/tags/`, filters in `src/filters.js`, and maintain registry isolation.
-5. **Verify**: Ensure the test suite passes, check for escaping vulnerabilities, and check that no scope leaks occur.
+# AGENT.md - Agent Instructions, Guardrails, & Architecture Rules
+
+This repository implements a Django-Style Template Engine for Node.js/Express. To ensure high code quality, consistent architecture, and full feature parity with Django without guesswork, all AI agents and developers must strictly follow these instructions and guardrails.
+
+---
+
+## 🎯 Core Objectives
+1. **Full Feature Parity**: Match Django's template engine rules for rendering variables, dotted lookups, built-in tags, filters, and template inheritance.
+2. **Deterministic & Secure**: Escape output by default using a safe-string mechanism.
+3. **No Spaghetti Code**: Maintain a strict separation of Lexer, Parser, Renderer, Context, and Tag/Filter registries.
+
+---
+
+## ⚠️ Strict Guardrails & Anti-Hallucination Rules
+
+> [!IMPORTANT]
+> **No Guesswork / Assumptions**
+> - If a tag or filter's behavior is not clearly defined in [prd.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/prd.md) or Django documentation, **DO NOT guess**. 
+> - If you notice ambiguities (e.g., how to handle circular extends or nested cycles), raise a question to the user immediately or throw a descriptive compilation error.
+
+> [!WARNING]
+> **No Regex-Based Global Search & Replace**
+> - You **must not** implement tags or filters using global regex replacements on the final string. All templates must go through:
+>   `Lexer (String -> Tokens) -> Parser (Tokens -> AST) -> Renderer (AST + Context -> HTML)`.
+> - Direct regex replacement on HTML bypasses nesting, escaping, and blocks, which introduces severe bugs.
+
+> [!CAUTION]
+> **Security Guardrails**
+> - All variable output must be HTML-escaped by default.
+> - A variable is only safe from escaping if it is marked as a `SafeString` (e.g., using the `safe` filter or internally flagged).
+> - Dynamic expression evaluation (such as in `if` tags) **must not** use direct JS `eval()`. Use a safe AST evaluator or sandboxed parser to prevent remote code execution.
+
+---
+
+## 🧩 Architectural Guidelines
+
+### 1. Lexing (`src/lexer.js`)
+*   Tokens must be generated for three primary types:
+    - `TEXT`: Plain HTML/text.
+    - `VAR`: Variables wrapped in `{{ ... }}`.
+    - `BLOCK`: Structural tags wrapped in `{% ... %}`.
+*   The Lexer must correctly handle verbatim blocks `{% verbatim %}` and comments `{% comment %}` by suppressing token output or passing raw text tokens.
+
+### 2. Parsing (`src/parser.js`)
+*   The Parser takes a stream of tokens and constructs an AST of nodes.
+*   Every node must implement a `.render(context)` method (async or sync).
+*   For tags that have closing tags (e.g., `{% if %}`...`{% endif %}`), the parser must parse nested tokens recursively until the matching close tag is encountered.
+
+### 3. Context & Scope Isolation (`src/context.js`)
+*   Context must support a stack-like structure: `.push()` to create a new scope, and `.pop()` to revert.
+*   **Variable Lookups**: Support dotted lookups:
+    - Example: `{{ user.profile.name }}` should search `user` in context, then resolve property `profile`, then property `name`.
+    - If a resolved value is a function, call it (without arguments, just like Django).
+    - If a lookup fails, return an empty string `""` by default, unless configured otherwise.
+
+### 4. Template Inheritance (`src/tags/inheritance.js`)
+*   Inheritance works by having a child template load a parent template via `{% extends "parent.html" %}`.
+*   The child overrides blocks defined as `{% block block_name %}`.
+*   During render, the parent's AST is evaluated, but block nodes are replaced by the child's corresponding block nodes.
+*   Support block nesting and the `{{ block.super }}` variable to render parent block content.
+
+---
+
+## 🛠️ Step-by-Step Task Execution Protocol
+
+When executing tasks:
+1. **Analyze Requirements**: Check [prd.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/prd.md) and [component.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/component.md).
+2. **Check Existing Tests**: Run current test suite using `npm test` or `node --test` to ensure a green state.
+3. **Write Tests First**: For any new filter, tag, or parser logic, write a corresponding unit test in `tests/` showing the expected template string and its expected output.
+4. **Implement Modular Code**: Put tag handlers in `src/tags/`, filters in `src/filters.js`, and maintain registry isolation.
+5. **Verify**: Ensure the test suite passes, check for escaping vulnerabilities, and check that no scope leaks occur.