From ac180405ba86be5dec9a8891015f716e741b59fb Mon Sep 17 00:00:00 2001
From: jnbdz <237008+jnbdz@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:43:09 -0400
Subject: [PATCH 1/2] Add the v0.1 design doc for the HTMT reference
 implementation.

---
 .../specs/2026-07-19-js-htf-design.md         | 115 ++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-19-js-htf-design.md

diff --git a/docs/superpowers/specs/2026-07-19-js-htf-design.md b/docs/superpowers/specs/2026-07-19-js-htf-design.md
new file mode 100644
index 0000000..86d79ce
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-19-js-htf-design.md
@@ -0,0 +1,115 @@
+# js-HTF v0.1 Design
+
+js-HTF is the JavaScript reference implementation of HTMT (HyperText Markup Templating): a templating engine that binds JSON data into HTML using `ht-*` attributes with JSONPath expressions, as documented in the [HTMT repository](https://github.com/ViewDescriptorProtocol/HTMT).
+
+## Goals
+
+- Implement the full documented HTMT attribute set: `ht-bind`, `ht-loop`, `ht-template`, `ht-attr-[name]`, `ht-show`, `ht-hide`, `ht-switch`, `ht-case`, `ht-class-[name]`, and every `ht-root-*` variant with the documented precedence rule (the local attribute wins over its `ht-root-*` twin).
+- Browser-first: render live DOM in the browser; tests run in Node against happy-dom. The core never touches browser-only APIs beyond the DOM itself, so server-side rendering can be added later without redesign.
+- Serve as the spec's conformance suite: every example in the HTMT docs becomes a test fixture.
+
+## Non-goals (v0.1)
+
+- No reactivity, state management, or event handling. Rendering is one-shot: `render(element, data)` produces the final DOM; re-rendering re-runs from a pristine copy.
+- No arbitrary JavaScript in attribute expressions — only JSONPath plus the small comparison grammar below.
+- No auto-initialization or DOM watching; that is htmx-HTF's role.
+- No server-side (string) rendering target yet.
+
+## Relationship to HTMX and Alpine.js
+
+**HTMX** is complementary, not overlapping. HTMX transports HTML fragments and swaps them into the DOM; it has no built-in answer for JSON responses and delegates that to client-side templating. HTMT is that missing piece: HTMX moves the data, HTMT binds it. The htmx-HTF repository will provide the integration.
+
+**Alpine.js** overlaps on rendering directives (`x-text`/`x-for`/`x-show` map closely onto `ht-bind`/`ht-loop`/`ht-show`) but differs in intent:
+
+1. Alpine attributes contain arbitrary JavaScript evaluated at runtime; HTMT expressions are JSONPath plus a tiny comparison grammar — declarative, CSP-safe, and implementable in any language.
+2. Alpine is a reactive mini-framework with component state and events; HTMT is a one-shot binding of server-provided JSON into markup.
+3. HTMT is a language-neutral spec with js-HTF as its reference implementation — the same templates and data could be rendered by a JVM or Android implementation, which is the VDP cross-platform premise.
+
+Guarding this boundary is a design constraint: features that push js-HTF toward Alpine's territory (state, events, reactivity) are out of scope for the spec, not just deferred.
+
+## Technology choices
+
+- **Plain ESM JavaScript with JSDoc types.** No build step; the source is the artifact. Types are checked with `tsc --checkJs` (no emit).
+- **json-p3** is the sole runtime dependency: an RFC 9535-compliant JSONPath engine, CSP-safe (no `eval`/`new Function`), usable in browser and Node.
+- **Vitest + happy-dom** for tests; **typescript** as a dev-only type checker.
+
+## Public API
+
+```js
+import { render } from 'js-htf';
+
+render(element, data, options?);
+```
+
+- `element`: the DOM element whose subtree contains `ht-*` attributes.
+- `data`: the JSON data object; it is the root context (`$`) at the top of the walk and the permanent target of `ht-root-*` expressions.
+- `options.templates`: where `ht-template` definitions are collected from (default: the element's owner document).
+- `options.debug`: when true, warnings (e.g. unmatched paths) are logged with the element and expression concerned.
+
+On first render, a pristine clone of the element's subtree is stored in a `WeakMap` keyed by the element. Subsequent `render` calls restore from the clone before rendering, making re-rendering with new data idempotent.
+
+`render` never half-commits: the walk runs on the pristine clone and the result is swapped in only if the whole walk succeeds. A thrown error leaves the previously rendered DOM intact.
+
+## Module layout
+
+```
+src/
+  index.js       public API (render), pristine-clone bookkeeping
+  walker.js      depth-first DOM walk, runs the handler pipeline per element
+  context.js     context stack: { root, current } — what "$" resolves against
+  path.js        JSONPath resolution via json-p3 (single-value and array modes)
+  expr.js        expression layer: <path>, <path> == <literal>, <path> != <literal>
+  handlers/
+    template.js    ht-template registration; <template> elements are inert
+    switchcase.js  ht-switch / ht-case branch pruning
+    visibility.js  ht-show / ht-hide via the hidden attribute
+    loop.js        ht-loop cloning and per-item recursion
+    bind.js        ht-bind text binding
+    attr.js        ht-attr-[name] attribute binding
+    classes.js     ht-class-[name] conditional classes
+```
+
+Each handler is a focused module: it receives the element, the context stack, and helpers, and can be tested in isolation. The walker composes them in a fixed pipeline order per element:
+
+1. `ht-template` — skip `<template>` elements in output (definitions were already collected in a pre-pass over `options.templates` before the walk starts).
+2. `ht-switch` / `ht-case` — resolve the switch expression once; prune non-matching case branches.
+3. `ht-show` / `ht-hide` — set or clear the `hidden` attribute.
+4. `ht-loop` — clone the per-item template (children, or a referenced `ht-template`) once per array item, recursing with the item as the new current context.
+5. `ht-bind` — bind text content.
+6. `ht-attr-[name]` — bind attributes.
+7. `ht-class-[name]` — toggle classes.
+
+Every handler checks its `ht-root-*` twin: the root variant resolves against the root context, and when both the local and root variants are present the local one wins (per the HTMT rooting documentation).
+
+## Semantics
+
+- **Context and `$`.** `$` resolves against the current context: the whole data object at the top of the walk, the loop item inside `ht-loop`. `ht-root-*` always resolves against the original root data. In nested loops `$` is the innermost item; `ht-root-*` is the only escape hatch (no parent-context syntax).
+- **`ht-bind`** sets `textContent` to the first JSONPath match, replacing placeholder children. No match renders the empty string (plus a debug warning). Values are always inserted as text, never parsed as HTML.
+- **`ht-attr-[name]`** sets the attribute to the resolved value coerced to a string (`true` becomes an empty-string boolean attribute); `null`, `undefined`, or `false` removes the attribute (so boolean attributes like `disabled` behave naturally).
+- **`ht-show` / `ht-hide`** toggle the standard `hidden` attribute. `ht-show` hides on a falsy result; `ht-hide` hides on a truthy result. The element remains in the DOM.
+- **`ht-class-[name]`** adds the class when the expression is truthy, removes it otherwise.
+- **`ht-switch` / `ht-case`.** The switch expression is resolved once. Child elements with `ht-case` are kept only when their literal strictly equals the resolved value; the rest are removed from the DOM. There is no default-case syntax.
+- **`ht-loop`.** The expression must yield an array (e.g. `$.users[*]` or a filter). The element's original children are the per-item template: cloned, rendered with the item as context, appended in document order. Zero items leaves an empty container. When `ht-template="id"` accompanies `ht-loop`, the registered template's content is instantiated per item instead of the children.
+- **`ht-template`** on a `<template>` element registers its content under the id; the element itself never renders. Referencing an unregistered id is a render error.
+- **Expression grammar** (`expr.js`): a bare JSONPath (truthiness = JavaScript truthiness; missing path = false), or `<path> == <literal>` / `<path> != <literal>`. Literals are single-quoted strings, numbers, `true`, `false`, and `null`. `ht-case` values use the same literal syntax. Anything beyond this grammar belongs in data preprocessing, as the HTMT docs advise.
+
+## Error handling
+
+Errors split by whose fault they are:
+
+- **Template errors throw.** Malformed JSONPath or expression syntax, `ht-case` outside an `ht-switch`, `ht-loop` over a non-array result, and unregistered template ids throw an `HtfError` naming the element and attribute. A reference implementation fails loud so incompatible templates cannot spread silently.
+- **Data absences do not throw.** A path matching nothing renders empty (`ht-bind`), evaluates false (conditions), or iterates zero times (`ht-loop`). With `options.debug`, each absence logs a warning naming the element and path.
+
+## Testing
+
+- **Conformance fixtures**: every example in the HTMT docs becomes an integration fixture — template HTML, JSON payload, expected output HTML. The suite doubles as the spec's conformance suite and is reusable by future implementations in other languages.
+- **Unit tests** per handler and for `expr.js`/`path.js` cover the edge rules in the Semantics section.
+- **Type checking**: `tsc --checkJs` over the JSDoc annotations.
+- **CI**: a GitHub Actions workflow runs the test suite and type check on push and pull request (node LTS), following the VDP repo's workflow pattern.
+
+## Repo conventions
+
+- Branches: work lands on `develop`, fast-forwarded to `main` (same as VDP and HTMT).
+- `CHANGELOG.md` in Keep a Changelog format; `CONTRIBUTING.md` mirroring HTMT's.
+- README: quick-start example, API reference, and the "Relationship to HTMX and Alpine.js" positioning section.
+- MIT license (already in place).

From 0a72bb3bb516ee000f13646da8a834ee374f797c Mon Sep 17 00:00:00 2001
From: jnbdz <237008+jnbdz@users.noreply.github.com>
Date: Sun, 19 Jul 2026 13:24:44 -0400
Subject: [PATCH 2/2] Add the v0.1 implementation plan.

---
 .../plans/2026-07-19-js-htf-v0-1.md           | 1948 +++++++++++++++++
 1 file changed, 1948 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-19-js-htf-v0-1.md

diff --git a/docs/superpowers/plans/2026-07-19-js-htf-v0-1.md b/docs/superpowers/plans/2026-07-19-js-htf-v0-1.md
new file mode 100644
index 0000000..3ee8da4
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-19-js-htf-v0-1.md
@@ -0,0 +1,1948 @@
+# js-HTF v0.1 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build js-HTF v0.1, the JavaScript reference implementation of the HTMT `ht-*` attribute templating spec, per `docs/superpowers/specs/2026-07-19-js-htf-design.md`.
+
+**Architecture:** A one-shot tree-walk interpreter: `render(element, data)` clones a pristine copy of the element, walks it depth-first with a `{root, current}` context, and runs a fixed pipeline of per-attribute handler modules on each element. JSONPath resolution is delegated to json-p3; a tiny expression layer adds `==`/`!=` comparisons.
+
+**Tech Stack:** Plain ESM JavaScript with JSDoc types (no build step), json-p3 (only runtime dependency), Vitest + happy-dom for tests, TypeScript as a dev-only type checker (`tsc --checkJs`).
+
+## Global Constraints
+
+- Source is plain `.js` ESM with JSDoc annotations — no TypeScript source files, no build/transpile step.
+- `json-p3` is the ONLY runtime dependency. Dev dependencies: `vitest`, `happy-dom`, `typescript`. Nothing else.
+- Git commits: plain sentences ending with a period (e.g. "Add the ht-loop handler."). NEVER include AI attribution, Co-Authored-By trailers, or session links.
+- All work lands on the `develop` branch (already checked out); `main` is fast-forwarded only at the end, by the user's say-so.
+- Rendered output preserves the `ht-*` attributes (the spec is silent; we keep them for transparency — re-rendering uses the pristine WeakMap clone, not the attributes).
+- Bound values are ALWAYS inserted as text (`textContent`) or attribute values — never parsed as HTML.
+- Template-author errors throw `HtfError`; missing data paths never throw (empty text / false condition / zero iterations + optional debug warning).
+- The machine has no `npx`; run local binaries via npm scripts (`npm test`, `npm run typecheck`) or `./node_modules/.bin/…`.
+- Repo root is `/home/jn/Projects/ViewDescriptorProtocol/js-HTF` — all paths below are relative to it.
+
+---
+
+### Task 1: Project scaffolding
+
+**Files:**
+- Create: `package.json`, `vitest.config.js`, `jsconfig.json`, `test/smoke.test.js`
+
+**Interfaces:**
+- Consumes: nothing (first task).
+- Produces: a working `npm test` (Vitest + happy-dom) and installed `json-p3` whose exports later tasks import as `import { query, JSONPathSyntaxError } from 'json-p3'`.
+
+- [ ] **Step 1: Write `package.json`**
+
+```json
+{
+  "name": "js-htf",
+  "version": "0.1.0",
+  "description": "JavaScript reference implementation of HTMT (HyperText Markup Templating)",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": { ".": "./src/index.js" },
+  "files": ["src"],
+  "license": "MIT",
+  "repository": "github:ViewDescriptorProtocol/js-HTF",
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p jsconfig.json"
+  }
+}
+```
+
+- [ ] **Step 2: Write `vitest.config.js`**
+
+```js
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: { environment: 'happy-dom' },
+});
+```
+
+- [ ] **Step 3: Write `jsconfig.json`**
+
+```json
+{
+  "compilerOptions": {
+    "checkJs": true,
+    "noEmit": true,
+    "strict": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "target": "es2022",
+    "lib": ["es2022", "dom", "dom.iterable"],
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.js"]
+}
+```
+
+- [ ] **Step 4: Install dependencies**
+
+Run: `npm install json-p3 && npm install -D vitest happy-dom typescript`
+Expected: `package.json` gains `dependencies.json-p3` and the three devDependencies; `package-lock.json` appears.
+
+- [ ] **Step 5: Verify json-p3's export names**
+
+Run: `node -e "import('json-p3').then(m => console.log(typeof m.query, typeof m.JSONPathSyntaxError))"`
+Expected: `function function`. If either prints `undefined`, STOP and check `node_modules/json-p3/README.md` for the actual names of the query function and syntax-error class, then use those names everywhere this plan says `query` / `JSONPathSyntaxError`.
+
+- [ ] **Step 6: Write `test/smoke.test.js`**
+
+```js
+import { it, expect } from 'vitest';
+import { query } from 'json-p3';
+
+it('json-p3 resolves a basic path', () => {
+  expect(query('$.a.b', { a: { b: 42 } }).values()).toEqual([42]);
+});
+
+it('happy-dom provides a working document', () => {
+  const el = document.createElement('div');
+  el.innerHTML = '<span>hi</span>';
+  expect(el.querySelector('span')?.textContent).toBe('hi');
+});
+```
+
+- [ ] **Step 7: Run the smoke test**
+
+Run: `npm test`
+Expected: 2 passed.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add package.json package-lock.json vitest.config.js jsconfig.json test/smoke.test.js
+git commit -m "Set up the package scaffolding with vitest, happy-dom, and json-p3."
+```
+
+---
+
+### Task 2: Errors, context, and JSONPath resolution
+
+**Files:**
+- Create: `src/errors.js`, `src/context.js`, `src/path.js`
+- Test: `test/path.test.js`
+
+**Interfaces:**
+- Consumes: `query`, `JSONPathSyntaxError` from `json-p3`.
+- Produces:
+  - `HtfError` class: `new HtfError(message, element?, attribute?)`, `name === 'HtfError'`.
+  - `createContext(root) -> {root, current}` and `withCurrent(ctx, current) -> {root, current}` from `src/context.js`.
+  - `queryAll(pathExpr, ctx, useRoot=false) -> any[]` and `queryFirst(pathExpr, ctx, useRoot=false) -> any|undefined` from `src/path.js`.
+
+- [ ] **Step 1: Write the failing test `test/path.test.js`**
+
+```js
+import { describe, it, expect } from 'vitest';
+import { createContext, withCurrent } from '../src/context.js';
+import { queryAll, queryFirst } from '../src/path.js';
+import { HtfError } from '../src/errors.js';
+
+const data = { site: { name: 'VDP' }, users: [{ name: 'Ada' }, { name: 'Grace' }] };
+
+describe('path resolution', () => {
+  it('resolves against the current context by default', () => {
+    const ctx = withCurrent(createContext(data), data.users[0]);
+    expect(queryFirst('$.name', ctx)).toBe('Ada');
+  });
+
+  it('resolves against the root when useRoot is true', () => {
+    const ctx = withCurrent(createContext(data), data.users[0]);
+    expect(queryFirst('$.site.name', ctx, true)).toBe('VDP');
+  });
+
+  it('returns all matches with queryAll', () => {
+    const ctx = createContext(data);
+    expect(queryAll('$.users[*].name', ctx)).toEqual(['Ada', 'Grace']);
+  });
+
+  it('returns undefined / empty for a missing path', () => {
+    const ctx = createContext(data);
+    expect(queryFirst('$.nope.nothing', ctx)).toBeUndefined();
+    expect(queryAll('$.nope.nothing', ctx)).toEqual([]);
+  });
+
+  it('throws HtfError on malformed JSONPath', () => {
+    const ctx = createContext(data);
+    expect(() => queryFirst('$..[', ctx)).toThrow(HtfError);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `./node_modules/.bin/vitest run test/path.test.js`
+Expected: FAIL — cannot find module `../src/context.js`.
+
+- [ ] **Step 3: Write `src/errors.js`**
+
+```js
+/** Error thrown for template-author mistakes discovered during rendering. */
+export class HtfError extends Error {
+  /**
+   * @param {string} message
+   * @param {Element} [element] offending element, when known
+   * @param {string} [attribute] offending attribute name, when known
+   */
+  constructor(message, element, attribute) {
+    const where = element
+      ? ` at <${element.tagName.toLowerCase()}${attribute ? ` ${attribute}` : ''}>`
+      : '';
+    super(`${message}${where}`);
+    this.name = 'HtfError';
+    this.element = element;
+    this.attribute = attribute;
+  }
+}
+```
+
+- [ ] **Step 4: Write `src/context.js`**
+
+```js
+/**
+ * @typedef {object} Context
+ * @property {any} root    what ht-root-* expressions resolve against
+ * @property {any} current what "$" resolves against here (loop item, or root at top)
+ */
+
+/**
+ * @param {any} root
+ * @returns {Context}
+ */
+export function createContext(root) {
+  return { root, current: root };
+}
+
+/**
+ * @param {Context} ctx
+ * @param {any} current
+ * @returns {Context}
+ */
+export function withCurrent(ctx, current) {
+  return { root: ctx.root, current };
+}
+```
+
+- [ ] **Step 5: Write `src/path.js`**
+
+```js
+import { query, JSONPathSyntaxError } from 'json-p3';
+import { HtfError } from './errors.js';
+
+/**
+ * Resolve a JSONPath against the context.
+ * @param {string} pathExpr
+ * @param {import('./context.js').Context} ctx
+ * @param {boolean} [useRoot] resolve against ctx.root instead of ctx.current
+ * @returns {any[]} all matched values (empty when nothing matches)
+ */
+export function queryAll(pathExpr, ctx, useRoot = false) {
+  const data = useRoot ? ctx.root : ctx.current;
+  try {
+    return query(pathExpr, data).values();
+  } catch (err) {
+    if (err instanceof JSONPathSyntaxError) {
+      throw new HtfError(`invalid JSONPath "${pathExpr}": ${err.message}`);
+    }
+    throw err;
+  }
+}
+
+/**
+ * @param {string} pathExpr
+ * @param {import('./context.js').Context} ctx
+ * @param {boolean} [useRoot]
+ * @returns {any | undefined} first matched value
+ */
+export function queryFirst(pathExpr, ctx, useRoot = false) {
+  return queryAll(pathExpr, ctx, useRoot)[0];
+}
+```
+
+- [ ] **Step 6: Run to verify pass**
+
+Run: `./node_modules/.bin/vitest run test/path.test.js`
+Expected: 5 passed.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/errors.js src/context.js src/path.js test/path.test.js
+git commit -m "Add the error type, render context, and JSONPath resolution."
+```
+
+---
+
+### Task 3: Expression layer
+
+**Files:**
+- Create: `src/expr.js`
+- Test: `test/expr.test.js`
+
+**Interfaces:**
+- Consumes: `queryFirst` (Task 2), `HtfError` (Task 2).
+- Produces, from `src/expr.js`:
+  - `evaluate(exprStr, ctx, useRoot=false) -> any` — bare path returns first match; `==`/`!=` comparison returns boolean.
+  - `evaluateBool(exprStr, ctx, useRoot=false) -> boolean` — JS truthiness; missing path is false.
+  - `parseLiteral(raw) -> any` — `'string'`, number, `true`, `false`, `null`; throws `HtfError` otherwise.
+
+- [ ] **Step 1: Write the failing test `test/expr.test.js`**
+
+```js
+import { describe, it, expect } from 'vitest';
+import { createContext } from '../src/context.js';
+import { evaluate, evaluateBool, parseLiteral } from '../src/expr.js';
+import { HtfError } from '../src/errors.js';
+
+const ctx = createContext({
+  user: { role: 'admin', age: 30, active: true },
+  users: [{ name: 'Ada', isActive: true }, { name: 'Bob', isActive: false }],
+});
+
+describe('parseLiteral', () => {
+  it('parses each literal form', () => {
+    expect(parseLiteral("'admin'")).toBe('admin');
+    expect(parseLiteral('42')).toBe(42);
+    expect(parseLiteral('true')).toBe(true);
+    expect(parseLiteral('false')).toBe(false);
+    expect(parseLiteral('null')).toBe(null);
+  });
+
+  it('rejects garbage', () => {
+    expect(() => parseLiteral('admin')).toThrow(HtfError);
+  });
+});
+
+describe('evaluate', () => {
+  it('bare path returns the first match', () => {
+    expect(evaluate('$.user.role', ctx)).toBe('admin');
+  });
+
+  it('== compares strictly against a literal', () => {
+    expect(evaluate("$.user.role == 'admin'", ctx)).toBe(true);
+    expect(evaluate('$.user.age == 30', ctx)).toBe(true);
+    expect(evaluate("$.user.role == 'guest'", ctx)).toBe(false);
+  });
+
+  it('!= negates the comparison', () => {
+    expect(evaluate("$.user.role != 'guest'", ctx)).toBe(true);
+  });
+
+  it('does not mistake == inside a filter for the comparison operator', () => {
+    expect(evaluate("$.users[?(@.name == 'Ada')].isActive", ctx)).toBe(true);
+  });
+});
+
+describe('evaluateBool', () => {
+  it('is JS truthiness for bare paths', () => {
+    expect(evaluateBool('$.user.active', ctx)).toBe(true);
+  });
+
+  it('is false for a missing path', () => {
+    expect(evaluateBool('$.user.missing', ctx)).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `./node_modules/.bin/vitest run test/expr.test.js`
+Expected: FAIL — cannot find module `../src/expr.js`.
+
+- [ ] **Step 3: Write `src/expr.js`**
+
+```js
+import { queryFirst } from './path.js';
+import { HtfError } from './errors.js';
+
+/**
+ * Find a top-level == or != — outside single quotes, brackets, and parens —
+ * so filters like [?(@.a == 'x')] stay part of the JSONPath.
+ * @param {string} s
+ * @returns {{op: '==' | '!=', index: number} | null}
+ */
+function findOperator(s) {
+  let depth = 0;
+  let inStr = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (inStr) {
+      if (c === "'") inStr = false;
+      continue;
+    }
+    if (c === "'") inStr = true;
+    else if (c === '[' || c === '(') depth++;
+    else if (c === ']' || c === ')') depth--;
+    else if (depth === 0 && (c === '=' || c === '!') && s[i + 1] === '=') {
+      return { op: /** @type {'==' | '!='} */ (c + '='), index: i };
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse an HTMT literal: 'string', number, true, false, null.
+ * @param {string} raw
+ * @returns {any}
+ */
+export function parseLiteral(raw) {
+  const s = raw.trim();
+  if (s.length >= 2 && s.startsWith("'") && s.endsWith("'")) return s.slice(1, -1);
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (s === 'null') return null;
+  if (s !== '' && !Number.isNaN(Number(s))) return Number(s);
+  throw new HtfError(`invalid literal "${raw}"`);
+}
+
+/**
+ * Evaluate an HTMT expression: a bare JSONPath (first match) or
+ * "<path> == <literal>" / "<path> != <literal>" (strict comparison).
+ * @param {string} exprStr
+ * @param {import('./context.js').Context} ctx
+ * @param {boolean} [useRoot]
+ * @returns {any}
+ */
+export function evaluate(exprStr, ctx, useRoot = false) {
+  const found = findOperator(exprStr);
+  if (!found) return queryFirst(exprStr.trim(), ctx, useRoot);
+  const left = queryFirst(exprStr.slice(0, found.index).trim(), ctx, useRoot);
+  const right = parseLiteral(exprStr.slice(found.index + 2));
+  return found.op === '==' ? left === right : left !== right;
+}
+
+/**
+ * @param {string} exprStr
+ * @param {import('./context.js').Context} ctx
+ * @param {boolean} [useRoot]
+ * @returns {boolean} JS truthiness; a missing path is false
+ */
+export function evaluateBool(exprStr, ctx, useRoot = false) {
+  return Boolean(evaluate(exprStr, ctx, useRoot));
+}
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `./node_modules/.bin/vitest run test/expr.test.js`
+Expected: 8 passed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/expr.js test/expr.test.js
+git commit -m "Add the HTMT expression layer."
+```
+
+---
+
+### Task 4: Binding lookup helpers
+
+**Files:**
+- Create: `src/handlers/util.js`
+- Test: `test/handlers-util.test.js`
+
+**Interfaces:**
+- Consumes: nothing (pure DOM helpers).
+- Produces, from `src/handlers/util.js`:
+  - `getBinding(el, name) -> {expr, useRoot, attribute} | null` — checks `ht-<name>` then `ht-root-<name>`; local wins.
+  - `getPrefixedBindings(el, prefix) -> Array<{key, expr, useRoot, attribute}>` — collects `ht-<prefix>-*` and `ht-root-<prefix>-*`; a local binding suppresses the root binding for the same key.
+
+- [ ] **Step 1: Write the failing test `test/handlers-util.test.js`**
+
+```js
+import { describe, it, expect } from 'vitest';
+import { getBinding, getPrefixedBindings } from '../src/handlers/util.js';
+
+function el(html) {
+  const div = document.createElement('div');
+  div.innerHTML = html;
+  return /** @type {Element} */ (div.firstElementChild);
+}
+
+describe('getBinding', () => {
+  it('returns null when neither variant is present', () => {
+    expect(getBinding(el('<p></p>'), 'bind')).toBeNull();
+  });
+
+  it('finds the local variant', () => {
+    expect(getBinding(el('<p ht-bind="$.a"></p>'), 'bind'))
+      .toEqual({ expr: '$.a', useRoot: false, attribute: 'ht-bind' });
+  });
+
+  it('finds the root variant', () => {
+    expect(getBinding(el('<p ht-root-bind="$.a"></p>'), 'bind'))
+      .toEqual({ expr: '$.a', useRoot: true, attribute: 'ht-root-bind' });
+  });
+
+  it('local wins when both are present', () => {
+    const b = getBinding(el('<p ht-root-bind="$.r" ht-bind="$.l"></p>'), 'bind');
+    expect(b).toEqual({ expr: '$.l', useRoot: false, attribute: 'ht-bind' });
+  });
+});
+
+describe('getPrefixedBindings', () => {
+  it('collects local and root prefixed bindings', () => {
+    const bindings = getPrefixedBindings(
+      el('<img ht-attr-src="$.a" ht-root-attr-alt="$.b">'), 'attr');
+    expect(bindings).toEqual([
+      { key: 'src', expr: '$.a', useRoot: false, attribute: 'ht-attr-src' },
+      { key: 'alt', expr: '$.b', useRoot: true, attribute: 'ht-root-attr-alt' },
+    ]);
+  });
+
+  it('local suppresses root for the same key', () => {
+    const bindings = getPrefixedBindings(
+      el('<img ht-root-attr-src="$.r" ht-attr-src="$.l">'), 'attr');
+    expect(bindings).toEqual([
+      { key: 'src', expr: '$.l', useRoot: false, attribute: 'ht-attr-src' },
+    ]);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `./node_modules/.bin/vitest run test/handlers-util.test.js`
+Expected: FAIL — cannot find module `../src/handlers/util.js`.
+
+- [ ] **Step 3: Write `src/handlers/util.js`**
+
+```js
+/**
+ * @typedef {object} Binding
+ * @property {string} expr
+ * @property {boolean} useRoot
+ * @property {string} attribute the attribute the expression came from
+ */
+
+/**
+ * Look up an HTMT binding, applying local-over-root precedence.
+ * @param {Element} el
+ * @param {string} name attribute name without the "ht-" prefix, e.g. "bind"
+ * @returns {Binding | null}
+ */
+export function getBinding(el, name) {
+  const local = el.getAttribute(`ht-${name}`);
+  if (local !== null) return { expr: local, useRoot: false, attribute: `ht-${name}` };
+  const root = el.getAttribute(`ht-root-${name}`);
+  if (root !== null) return { expr: root, useRoot: true, attribute: `ht-root-${name}` };
+  return null;
+}
+
+/**
+ * Collect bindings like ht-attr-src / ht-root-attr-src.
+ * @param {Element} el
+ * @param {string} prefix e.g. "attr" or "class"
+ * @returns {Array<Binding & {key: string}>}
+ */
+export function getPrefixedBindings(el, prefix) {
+  const local = `ht-${prefix}-`;
+  const root = `ht-root-${prefix}-`;
+  /** @type {Array<Binding & {key: string}>} */
+  const out = [];
+  for (const { name, value } of Array.from(el.attributes)) {
+    if (name.startsWith(local)) {
+      out.push({ key: name.slice(local.length), expr: value, useRoot: false, attribute: name });
+    } else if (name.startsWith(root)) {
+      out.push({ key: name.slice(root.length), expr: value, useRoot: true, attribute: name });
+    }
+  }
+  return out.filter(
+    (b) => !b.useRoot || !out.some((o) => !o.useRoot && o.key === b.key)
+  );
+}
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `./node_modules/.bin/vitest run test/handlers-util.test.js`
+Expected: 6 passed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/handlers/util.js test/handlers-util.test.js
+git commit -m "Add the attribute binding lookup helpers."
+```
+
+---
+
+### Task 5: Walker skeleton, ht-bind, and the render API
+
+**Files:**
+- Create: `src/handlers/bind.js`, `src/walker.js`, `src/index.js`
+- Test: `test/render.test.js`
+
+**Interfaces:**
+- Consumes: `getBinding` (Task 4), `queryFirst` (Task 2), `createContext` (Task 2), `HtfError` (Task 2).
+- Produces:
+  - `render(element, data, options?) -> element` from `src/index.js`; `options` is `{templates?: ParentNode, debug?: boolean}`. Re-exports `HtfError`.
+  - `walk(el, ctx, state)` from `src/walker.js`.
+  - `State` typedef in `src/walker.js`: `{templates: Map<string, HTMLTemplateElement>, handledCases: WeakSet<Element>, warn: (msg: string, el: Element) => void}`.
+  - `applyBind(el, ctx, state) -> boolean` from `src/handlers/bind.js` (true when it bound, meaning children were replaced).
+
+- [ ] **Step 1: Write the failing test `test/render.test.js`**
+
+```js
+import { describe, it, expect } from 'vitest';
+import { render } from '../src/index.js';
+
+function container(html) {
+  const div = document.createElement('div');
+  div.innerHTML = html;
+  document.body.appendChild(div);
+  return div;
+}
+
+describe('render with ht-bind', () => {
+  it('binds text content, replacing the placeholder', () => {
+    const c = container('<div ht-bind="$.user.name">placeholder</div>');
+    render(c, { user: { name: 'Ada' } });
+    expect(c.innerHTML).toBe('<div ht-bind="$.user.name">Ada</div>');
+  });
+
+  it('recurses into nested elements', () => {
+    const c = container('<section><p ht-bind="$.msg">x</p></section>');
+    render(c, { msg: 'hello' });
+    expect(c.querySelector('p')?.textContent).toBe('hello');
+  });
+
+  it('renders empty text for a missing path', () => {
+    const c = container('<div ht-bind="$.missing">placeholder</div>');
+    render(c, {});
+    expect(c.firstElementChild?.textContent).toBe('');
+  });
+
+  it('re-renders from the pristine template with new data', () => {
+    const c = container('<div ht-bind="$.n">placeholder</div>');
+    render(c, { n: 'one' });
+    render(c, { n: 'two' });
+    expect(c.firstElementChild?.textContent).toBe('two');
+  });
+
+  it('binds ht-* attributes on the root element itself', () => {
+    const c = container('');
+    c.setAttribute('ht-bind', '$.msg');
+    render(c, { msg: 'root bound' });
+    expect(c.textContent).toBe('root bound');
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `./node_modules/.bin/vitest run test/render.test.js`
+Expected: FAIL — cannot find module `../src/index.js`.
+
+- [ ] **Step 3: Write `src/handlers/bind.js`**
+
+```js
+import { getBinding } from './util.js';
+import { queryFirst } from '../path.js';
+
+/**
+ * Apply ht-bind / ht-root-bind: set textContent to the first match.
+ * @param {Element} el
+ * @param {import('../context.js').Context} ctx
+ * @param {import('../walker.js').State} state
+ * @returns {boolean} true when a binding replaced the children
+ */
+export function applyBind(el, ctx, state) {
+  const b = getBinding(el, 'bind');
+  if (!b) return false;
+  const value = queryFirst(b.expr, ctx, b.useRoot);
+  if (value === undefined) {
+    state.warn(`no match for ${b.attribute}="${b.expr}"`, el);
+    el.textContent = '';
+  } else {
+    el.textContent = String(value);
+  }
+  return true;
+}
+```
+
+- [ ] **Step 4: Write `src/walker.js`**
+
+```js
+import { applyBind } from './handlers/bind.js';
+
+/**
+ * @typedef {object} State
+ * @property {Map<string, HTMLTemplateElement>} templates
+ * @property {WeakSet<Element>} handledCases
+ * @property {(msg: string, el: Element) => void} warn
+ */
+
+/**
+ * Depth-first walk running the handler pipeline on each element.
+ * @param {Element} el
+ * @param {import('./context.js').Context} ctx
+ * @param {State} state
+ */
+export function walk(el, ctx, state) {
+  const bound = applyBind(el, ctx, state);
+  if (bound) return;
+  for (const child of Array.from(el.children)) {
+    walk(child, ctx, state);
+  }
+}
+```
+
+- [ ] **Step 5: Write `src/index.js`**
+
+```js
+import { walk } from './walker.js';
+import { createContext } from './context.js';
+import { HtfError } from './errors.js';
+
+/** Pristine pre-render clones, keyed by the live element. */
+const pristine = new WeakMap();
+
+/**
+ * Render HTMT ht-* attributes in element's subtree against data, in place.
+ * @param {Element} element
+ * @param {any} data
+ * @param {{templates?: ParentNode, debug?: boolean}} [options]
+ * @returns {Element} the same element
+ */
+export function render(element, data, options = {}) {
+  let original = pristine.get(element);
+  if (!original) {
+    original = /** @type {Element} */ (element.cloneNode(true));
+    pristine.set(element, original);
+  }
+  /** @type {import('./walker.js').State} */
+  const state = {
+    templates: new Map(),
+    handledCases: new WeakSet(),
+    warn: options.debug
+      ? (msg, el) => console.warn(`[js-htf] ${msg}`, el)
+      : () => {},
+  };
+  const working = /** @type {Element} */ (original.cloneNode(true));
+  walk(working, createContext(data), state);
+  syncAttributes(element, working);
+  element.replaceChildren(...Array.from(working.childNodes));
+  return element;
+}
+
+/**
+ * Make target's attributes identical to source's.
+ * @param {Element} target
+ * @param {Element} source
+ */
+function syncAttributes(target, source) {
+  for (const { name } of Array.from(target.attributes)) {
+    if (!source.hasAttribute(name)) target.removeAttribute(name);
+  }
+  for (const { name, value } of Array.from(source.attributes)) {
+    target.setAttribute(name, value);
+  }
+}
+
+export { HtfError };
+```
+
+- [ ] **Step 6: Run to verify pass**
+
+Run: `./node_modules/.bin/vitest run test/render.test.js`
+Expected: 5 passed.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/handlers/bind.js src/walker.js src/index.js test/render.test.js
+git commit -m "Add the walker and render API with ht-bind support."
+```
+
+---
+
+### Task 6: ht-attr-* and ht-class-* handlers
+
+**Files:**
+- Create: `src/handlers/attr.js`, `src/handlers/classes.js`
+- Modify: `src/walker.js`
+- Test: `test/attr-class.test.js`
+
+**Interfaces:**
+- Consumes: `getPrefixedBindings` (Task 4), `queryFirst` (Task 2), `evaluateBool` (Task 3).
+- Produces: `applyAttrs(el, ctx, state)` and `applyClasses(el, ctx, state)`, both void, called by the walker on every element.
+
+- [ ] **Step 1: Write the failing test `test/attr-class.test.js`**
+
+```js
+import { describe, it, expect } from 'vitest';
+import { render } from '../src/index.js';
+
+function container(html) {
+  const div = document.createElement('div');
+  div.innerHTML = html;
+  document.body.appendChild(div);
+  return div;
+}
+
+describe('ht-attr-*', () => {
+  it('sets the attribute from the resolved value', () => {
+    const c = container('<img ht-attr-src="$.url" alt="a">');
+    render(c, { url: 'https://example.com/x.png' });
+    expect(c.querySelector('img')?.getAttribute('src')).toBe('https://example.com/x.png');
+  });
+
+  it('true renders an empty boolean attribute', () => {
+    const c = container('<button ht-attr-disabled="$.locked">Go</button>');
+    render(c, { locked: true });
+    expect(c.querySelector('button')?.getAttribute('disabled')).toBe('');
+  });
+
+  it('false, null, and missing remove the attribute', () => {
+    const c = container('<button disabled ht-attr-disabled="$.locked">Go</button>');
+    render(c, { locked: false });
+    expect(c.querySelector('button')?.hasAttribute('disabled')).toBe(false);
+  });
+
+  it('numbers are stringified', () => {
+    const c = container('<input ht-attr-maxlength="$.max">');
+    render(c, { max: 12 });
+    expect(c.querySelector('input')?.getAttribute('maxlength')).toBe('12');
+  });
+});
+
+describe('ht-class-*', () => {
+  it('adds the class when the expression is truthy', () => {
+    const c = container(`<div ht-class-active="$.status == 'active'">u</div>`);
+    render(c, { status: 'active' });
+    expect(c.firstElementChild?.classList.contains('active')).toBe(true);
+  });
+
+  it('removes the class when the expression is falsy', () => {
+    const c = container(`<div class="active" ht-class-active="$.status == 'active'">u</div>`);
+    render(c, { status: 'banned' });
+    expect(c.firstElementChild?.classList.contains('active')).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `./node_modules/.bin/vitest run test/attr-class.test.js`
+Expected: FAIL — attributes/classes unchanged (handlers do not exist yet).
+
+- [ ] **Step 3: Write `src/handlers/attr.js`**
+
+```js
+import { getPrefixedBindings } from './util.js';
+import { queryFirst } from '../path.js';
+
+/**
+ * Apply ht-attr-[name] / ht-root-attr-[name] bindings.
+ * @param {Element} el
+ * @param {import('../context.js').Context} ctx
+ * @param {import('../walker.js').State} state
+ */
+export function applyAttrs(el, ctx, state) {
+  for (const b of getPrefixedBindings(el, 'attr')) {
+    const value = queryFirst(b.expr, ctx, b.useRoot);
+    if (value === null || value === undefined || value === false) {
+      if (value === undefined) state.warn(`no match for ${b.attribute}="${b.expr}"`, el);
+      el.removeAttribute(b.key);
+    } else if (value === true) {
+      el.setAttribute(b.key, '');
+    } else {
+      el.setAttribute(b.key, String(value));
+    }
+  }
+}
+```
+
+- [ ] **Step 4: Write `src/handlers/classes.js`**
+
+```js
+import { getPrefixedBindings } from './util.js';
+import { evaluateBool } from '../expr.js';
+
+/**
+ * Apply ht-class-[name] / ht-root-class-[name] bindings.
+ * @param {Element} el
+ * @param {import('../context.js').Context} ctx
+ * @param {import('../walker.js').State} state
+ */
+export function applyClasses(el, ctx, state) {
+  for (const b of getPrefixedBindings(el, 'class')) {
+    el.classList.toggle(b.key, evaluateBool(b.expr, ctx, b.useRoot));
+  }
+}
+```
+
+- [ ] **Step 5: Update `src/walker.js`** (full new body of `walk`)
+
+```js
+import { applyBind } from './handlers/bind.js';
+import { applyAttrs } from './handlers/attr.js';
+import { applyClasses } from './handlers/classes.js';
+
+/**
+ * @typedef {object} State
+ * @property {Map<string, HTMLTemplateElement>} templates
+ * @property {WeakSet<Element>} handledCases
+ * @property {(msg: string, el: Element) => void} warn
+ */
+
+/**
+ * Depth-first walk running the handler pipeline on each element.
+ * @param {Element} el
+ * @param {import('./context.js').Context} ctx
+ * @param {State} state
+ */
+export function walk(el, ctx, state) {
+  const bound = applyBind(el, ctx, state);
+  applyAttrs(el, ctx, state);
+  applyClasses(el, ctx, state);
+  if (bound) return;
+  for (const child of Array.from(el.children)) {
+    walk(child, ctx, state);
+  }
+}
+```
+
+- [ ] **Step 6: Run to verify pass**
+
+Run: `npm test`
+Expected: all tests pass (previous suites included).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/handlers/attr.js src/handlers/classes.js src/walker.js test/attr-class.test.js
+git commit -m "Add the ht-attr and ht-class handlers."
+```
+
+---
+
+### Task 7: ht-show / ht-hide handler
+
+**Files:**
+- Create: `src/handlers/visibility.js`
+- Modify: `src/walker.js`
+- Test: `test/visibility.test.js`
+
+**Interfaces:**
+- Consumes: `getBinding` (Task 4), `evaluateBool` (Task 3).
+- Produces: `applyVisibility(el, ctx, state)`, void; toggles the standard `hidden` attribute; element stays in the DOM.
+
+- [ ] **Step 1: Write the failing test `test/visibility.test.js`**
+
+```js
+import { describe, it, expect } from 'vitest';
+import { render } from '../src/index.js';
+
+function container(html) {
+  const div = document.createElement('div');
+  div.innerHTML = html;
+  document.body.appendChild(div);
+  return div;
+}
+
+describe('ht-show / ht-hide', () => {
+  it('ht-show keeps the element visible when truthy', () => {
+    const c = container('<div ht-show="$.in">x</div>');
+    render(c, { in: true });
+    expect(c.firstElementChild?.hasAttribute('hidden')).toBe(false);
+  });
+
+  it('ht-show hides when falsy (element stays in the DOM)', () => {
+    const c = container('<div ht-show="$.in">x</div>');
+    render(c, { in: false });
+    expect(c.firstElementChild?.hasAttribute('hidden')).toBe(true);
+  });
+
+  it('ht-show hides when the path is missing', () => {
+    const c = container('<div ht-show="$.nope">x</div>');
+    render(c, {});
+    expect(c.firstElementChild?.hasAttribute('hidden')).toBe(true);
+  });
+
+  it('ht-hide hides when truthy', () => {
+    const c = container('<div ht-hide="$.anon">x</div>');
+    render(c, { anon: true });
+    expect(c.firstElementChild?.hasAttribute('hidden')).toBe(true);
+  });
+
+  it('ht-hide leaves visible when falsy', () => {
+    const c = container('<div ht-hide="$.anon">x</div>');
+    render(c, { anon: false });
+    expect(c.firstElementChild?.hasAttribute('hidden')).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `./node_modules/.bin/vitest run test/visibility.test.js`
+Expected: FAIL on the hiding cases (no handler yet).
+
+- [ ] **Step 3: Write `src/handlers/visibility.js`**
+
+```js
+import { getBinding } from './util.js';
+import { evaluateBool } from '../expr.js';
+
+/**
+ * Apply ht-show / ht-hide (and root variants) via the hidden attribute.
+ * @param {Element} el
+ * @param {import('../context.js').Context} ctx
+ * @param {import('../walker.js').State} state
+ */
+export function applyVisibility(el, ctx, state) {
+  const show = getBinding(el, 'show');
+  const hide = getBinding(el, 'hide');
+  /** @type {boolean | null} */
+  let hidden = null;
+  if (show) hidden = !evaluateBool(show.expr, ctx, show.useRoot);
+  if (hide && evaluateBool(hide.expr, ctx, hide.useRoot)) hidden = true;
+  if (hidden === true) el.setAttribute('hidden', '');
+  else if (hidden === false) el.removeAttribute('hidden');
+}
+```
+
+- [ ] **Step 4: Update `src/walker.js`** — add the import and call `applyVisibility(el, ctx, state);` as the FIRST line of `walk` (before `applyBind`):
+
+```js
+import { applyVisibility } from './handlers/visibility.js';
+// inside walk(), before applyBind:
+  applyVisibility(el, ctx, state);
+```
+
+- [ ] **Step 5: Run to verify pass**
+
+Run: `npm test`
+Expected: all tests pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/handlers/visibility.js src/walker.js test/visibility.test.js
+git commit -m "Add the ht-show and ht-hide handlers."
+```
+
+---
+
+### Task 8: ht-switch / ht-case handler
+
+**Files:**
+- Create: `src/handlers/switchcase.js`
+- Modify: `src/walker.js`
+- Test: `test/switchcase.test.js`
+
+**Interfaces:**
+- Consumes: `getBinding` (Task 4), `evaluate`, `parseLiteral` (Task 3), `HtfError` (Task 2), `state.handledCases` (Task 5).
+- Produces:
+  - `applySwitch(el, ctx, state)` — when `el` has `ht-switch`/`ht-root-switch`, resolves it once, removes direct children whose `ht-case` literal is not strictly equal, and marks every direct `ht-case` child in `state.handledCases`.
+  - `rejectOrphanCase(el, state)` — throws `HtfError` for an element carrying `ht-case` that is not in `state.handledCases` (i.e. not a direct child of a switch).
+
+- [ ] **Step 1: Write the failing test `test/switchcase.test.js`**
+
+```js
+import { describe, it, expect } from 'vitest';
+import { render, HtfError } from '../src/index.js';
+
+function container(html) {
+  const div = document.createElement('div');
+  div.innerHTML = html;
+  document.body.appendChild(div);
+  return div;
+}
+
+describe('ht-switch / ht-case', () => {
+  it('keeps only the strictly matching case', () => {
+    const c = container(
+      `<div ht-switch="$.role"><p ht-case="'admin'">A</p><p ht-case="'guest'">G</p></div>`);
+    render(c, { role: 'admin' });
+    const ps = c.querySelectorAll('p');
+    expect(ps.length).toBe(1);
+    expect(ps[0].textContent).toBe('A');
+  });
+
+  it('number cases compare strictly', () => {
+    const c = container(
+      '<div ht-switch="$.n"><p ht-case="1">one</p><p ht-case="2">two</p></div>');
+    render(c, { n: 2 });
+    expect(c.querySelector('p')?.textContent).toBe('two');
+  });
+
+  it('removes every case when nothing matches', () => {
+    const c = container(`<div ht-switch="$.role"><p ht-case="'admin'">A</p></div>`);
+    render(c, { role: 'guest' });
+    expect(c.querySelectorAll('p').length).toBe(0);
+  });
+
+  it('non-case children survive', () => {
+    const c = container(
+      `<div ht-switch="$.role"><h1>Title</h1><p ht-case="'x'">X</p></div>`);
+    render(c, { role: 'y' });
+    expect(c.querySelector('h1')?.textContent).toBe('Title');
+  });
+
+  it('throws HtfError for ht-case without an enclosing ht-switch', () => {
+    const c = container(`<div><p ht-case="'a'">A</p></div>`);
+    expect(() => render(c, {})).toThrow(HtfError);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `./node_modules/.bin/vitest run test/switchcase.test.js`
+Expected: FAIL — both cases survive; no orphan error.
+
+- [ ] **Step 3: Write `src/handlers/switchcase.js`**
+
+```js
+import { getBinding } from './util.js';
+import { evaluate, parseLiteral } from '../expr.js';
+import { HtfError } from '../errors.js';
+
+/**
+ * Apply ht-switch / ht-root-switch: prune non-matching direct ht-case children.
+ * @param {Element} el
+ * @param {import('../context.js').Context} ctx
+ * @param {import('../walker.js').State} state
+ */
+export function applySwitch(el, ctx, state) {
+  const sw = getBinding(el, 'switch');
+  if (!sw) return;
+  const value = evaluate(sw.expr, ctx, sw.useRoot);
+  for (const child of Array.from(el.children)) {
+    const caseAttr = child.getAttribute('ht-case');
+    if (caseAttr === null) continue;
+    state.handledCases.add(child);
+    if (parseLiteral(caseAttr) !== value) child.remove();
+  }
+}
+
+/**
+ * An ht-case that no switch consumed is a template error.
+ * @param {Element} el
+ * @param {import('../walker.js').State} state
+ */
+export function rejectOrphanCase(el, state) {
+  if (el.hasAttribute('ht-case') && !state.handledCases.has(el)) {
+    throw new HtfError('ht-case without an enclosing ht-switch', el, 'ht-case');
+  }
+}
+```
+
+- [ ] **Step 4: Update `src/walker.js`** (full new body of `walk`; switch runs before visibility so pruned branches are never processed)
+
+```js
+import { applySwitch, rejectOrphanCase } from './handlers/switchcase.js';
+import { applyVisibility } from './handlers/visibility.js';
+import { applyBind } from './handlers/bind.js';
+import { applyAttrs } from './handlers/attr.js';
+import { applyClasses } from './handlers/classes.js';
+
+export function walk(el, ctx, state) {
+  rejectOrphanCase(el, state);
+  applySwitch(el, ctx, state);
+  applyVisibility(el, ctx, state);
+  const bound = applyBind(el, ctx, state);
+  applyAttrs(el, ctx, state);
+  applyClasses(el, ctx, state);
+  if (bound) return;
+  for (const child of Array.from(el.children)) {
+    walk(child, ctx, state);
+  }
+}
+```
+
+(Keep the `State` typedef comment block from Task 5 unchanged above the function.)
+
+- [ ] **Step 5: Run to verify pass**
+
+Run: `npm test`
+Expected: all tests pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/handlers/switchcase.js src/walker.js test/switchcase.test.js
+git commit -m "Add the ht-switch and ht-case handlers."
+```
+
+---
+
+### Task 9: ht-loop handler
+
+**Files:**
+- Create: `src/handlers/loop.js`
+- Modify: `src/walker.js`
+- Test: `test/loop.test.js`
+
+**Interfaces:**
+- Consumes: `getBinding` (Task 4), `queryAll` (Task 2), `withCurrent` (Task 2), `HtfError` (Task 2).
+- Produces: `applyLoop(el, ctx, state, walkFn) -> boolean` — true when it looped (children already handled). Template-by-id instantiation is added in Task 10; this task loops over the element's own children.
+- Array semantics: multiple JSONPath matches (e.g. `[*]`, filters) are the items; a single match that is an array is the items; a single non-array match throws `HtfError`; zero matches renders zero items with a warning.
+
+- [ ] **Step 1: Write the failing test `test/loop.test.js`**
+
+```js
+import { describe, it, expect } from 'vitest';
+import { render, HtfError } from '../src/index.js';
+
+function container(html) {
+  const div = document.createElement('div');
+  div.innerHTML = html;
+  document.body.appendChild(div);
+  return div;
+}
+
+describe('ht-loop', () => {
+  it('clones children once per item with the item as $', () => {
+    const c = container('<ul ht-loop="$.users[*]"><li ht-bind="$.name">n</li></ul>');
+    render(c, { users: [{ name: 'Ada' }, { name: 'Grace' }] });
+    const lis = c.querySelectorAll('li');
+    expect(lis.length).toBe(2);
+    expect(lis[0].textContent).toBe('Ada');
+    expect(lis[1].textContent).toBe('Grace');
+  });
+
+  it('accepts a bare path to an array', () => {
+    const c = container('<ul ht-loop="$.users"><li ht-bind="$.name">n</li></ul>');
+    render(c, { users: [{ name: 'Ada' }] });
+    expect(c.querySelectorAll('li').length).toBe(1);
+  });
+
+  it('supports filter expressions', () => {
+    const c = container('<ul ht-loop="$.users[?(@.on)]"><li ht-bind="$.name">n</li></ul>');
+    render(c, { users: [{ name: 'A', on: true }, { name: 'B', on: false }] });
+    expect(c.querySelectorAll('li').length).toBe(1);
+    expect(c.querySelector('li')?.textContent).toBe('A');
+  });
+
+  it('renders an empty container for zero items', () => {
+    const c = container('<ul ht-loop="$.users[*]"><li ht-bind="$.name">n</li></ul>');
+    render(c, { users: [] });
+    expect(c.querySelectorAll('li').length).toBe(0);
+  });
+
+  it('throws HtfError when the result is a single non-array', () => {
+    const c = container('<ul ht-loop="$.users"><li>x</li></ul>');
+    expect(() => render(c, { users: 42 })).toThrow(HtfError);
+  });
+
+  it('ht-root-* escapes the loop scope', () => {
+    const c = container(
+      '<ul ht-loop="$.items[*]"><li><b ht-bind="$.label">l</b><i ht-root-bind="$.total">t</i></li></ul>');
+    render(c, { total: 2, items: [{ label: 'x' }, { label: 'y' }] });
+    const found = Array.from(c.querySelectorAll('i')).map((n) => n.textContent);
+    expect(found).toEqual(['2', '2']);
+  });
+
+  it('nested loops rebind $ to the innermost item', () => {
+    const c = container(
+      '<div ht-loop="$.groups[*]"><section ht-loop="$.members[*]"><span ht-bind="$.n">n</span></section></div>');
+    render(c, { groups: [{ members: [{ n: 'a' }, { n: 'b' }] }] });
+    const found = Array.from(c.querySelectorAll('span')).map((n) => n.textContent);
+    expect(found).toEqual(['a', 'b']);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `./node_modules/.bin/vitest run test/loop.test.js`
+Expected: FAIL — no looping happens.
+
+- [ ] **Step 3: Write `src/handlers/loop.js`**
+
+```js
+import { getBinding } from './util.js';
+import { queryAll } from '../path.js';
+import { withCurrent } from '../context.js';
+import { HtfError } from '../errors.js';
+
+/**
+ * Apply ht-loop / ht-root-loop: clone the per-item template once per item.
+ * @param {Element} el
+ * @param {import('../context.js').Context} ctx
+ * @param {import('../walker.js').State} state
+ * @param {(el: Element, ctx: import('../context.js').Context, state: import('../walker.js').State) => void} walkFn
+ * @returns {boolean} true when the element looped (children handled here)
+ */
+export function applyLoop(el, ctx, state, walkFn) {
+  const b = getBinding(el, 'loop');
+  if (!b) return false;
+
+  const results = queryAll(b.expr, ctx, b.useRoot);
+  /** @type {any[]} */
+  let items;
+  if (results.length === 0) {
+    state.warn(`no match for ${b.attribute}="${b.expr}"`, el);
+    items = [];
+  } else if (results.length === 1) {
+    if (!Array.isArray(results[0])) {
+      throw new HtfError(
+        `${b.attribute}="${b.expr}" did not yield an array`, el, b.attribute);
+    }
+    items = results[0];
+  } else {
+    items = results;
+  }
+
+  const doc = el.ownerDocument;
+  const itemTemplate = doc.createDocumentFragment();
+  while (el.firstChild) itemTemplate.appendChild(el.firstChild);
+
+  for (const item of items) {
+    const clone = /** @type {DocumentFragment} */ (itemTemplate.cloneNode(true));
+    const itemCtx = withCurrent(ctx, item);
+    for (const child of Array.from(clone.children)) {
+      walkFn(child, itemCtx, state);
+    }
+    el.appendChild(clone);
+  }
+  return true;
+}
+```
+
+- [ ] **Step 4: Update `src/walker.js`** (full new body of `walk`; loop runs after visibility, and a looped or bound element does not recurse again)
+
+```js
+import { applySwitch, rejectOrphanCase } from './handlers/switchcase.js';
+import { applyVisibility } from './handlers/visibility.js';
+import { applyLoop } from './handlers/loop.js';
+import { applyBind } from './handlers/bind.js';
+import { applyAttrs } from './handlers/attr.js';
+import { applyClasses } from './handlers/classes.js';
+
+export function walk(el, ctx, state) {
+  rejectOrphanCase(el, state);
+  applySwitch(el, ctx, state);
+  applyVisibility(el, ctx, state);
+  const looped = applyLoop(el, ctx, state, walk);
+  const bound = looped ? false : applyBind(el, ctx, state);
+  applyAttrs(el, ctx, state);
+  applyClasses(el, ctx, state);
+  if (looped || bound) return;
+  for (const child of Array.from(el.children)) {
+    walk(child, ctx, state);
+  }
+}
+```
+
+- [ ] **Step 5: Run to verify pass**
+
+Run: `npm test`
+Expected: all tests pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/handlers/loop.js src/walker.js test/loop.test.js
+git commit -m "Add the ht-loop handler."
+```
+
+---
+
+### Task 10: ht-template registration and instantiation
+
+**Files:**
+- Create: `src/handlers/template.js`
+- Modify: `src/index.js`, `src/walker.js`, `src/handlers/loop.js`
+- Test: `test/template.test.js`
+
+**Interfaces:**
+- Consumes: `state.templates` (Task 5), `HtfError` (Task 2), `applyLoop` (Task 9).
+- Produces:
+  - `collectTemplates(scope) -> Map<string, HTMLTemplateElement>` from `src/handlers/template.js` (scope is a ParentNode with `querySelectorAll`).
+  - `isTemplateDefinition(el) -> boolean` from the same module (a `<template>` with `ht-template`).
+  - The walker removes template definitions from output; `applyLoop` instantiates `state.templates` content when the loop element carries `ht-template="id"`; an unregistered id throws `HtfError`.
+
+- [ ] **Step 1: Write the failing test `test/template.test.js`**
+
+```js
+import { describe, it, expect } from 'vitest';
+import { render, HtfError } from '../src/index.js';
+
+function container(html) {
+  const div = document.createElement('div');
+  div.innerHTML = html;
+  document.body.appendChild(div);
+  return div;
+}
+
+describe('ht-template', () => {
+  it('instantiates a registered template per loop item', () => {
+    const c = container(
+      '<template ht-template="user-info"><p ht-bind="$.name">n</p></template>' +
+      '<div ht-loop="$.users[*]" ht-template="user-info"></div>');
+    render(c, { users: [{ name: 'Ada' }, { name: 'Grace' }] });
+    const ps = c.querySelectorAll('p');
+    expect(ps.length).toBe(2);
+    expect(ps[0].textContent).toBe('Ada');
+  });
+
+  it('removes template definitions from the output', () => {
+    const c = container(
+      '<template ht-template="t"><p>x</p></template><div ht-loop="$.a[*]" ht-template="t"></div>');
+    render(c, { a: [] });
+    expect(c.querySelector('template')).toBeNull();
+  });
+
+  it('finds templates outside the rendered element via options.templates', () => {
+    const library = container('<template ht-template="row"><li ht-bind="$.n">n</li></template>');
+    const c = container('<ul ht-loop="$.xs[*]" ht-template="row"></ul>');
+    render(c, { xs: [{ n: '1' }] }, { templates: library });
+    expect(c.querySelector('li')?.textContent).toBe('1');
+  });
+
+  it('throws HtfError for an unregistered template id', () => {
+    const c = container('<div ht-loop="$.a[*]" ht-template="missing"></div>');
+    // options.templates scopes lookup away from templates registered by other tests
+    expect(() => render(c, { a: [1] }, { templates: c })).toThrow(HtfError);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `./node_modules/.bin/vitest run test/template.test.js`
+Expected: FAIL — no template instantiation.
+
+- [ ] **Step 3: Write `src/handlers/template.js`**
+
+```js
+/**
+ * Collect <template ht-template="id"> definitions from a scope.
+ * @param {ParentNode} scope
+ * @returns {Map<string, HTMLTemplateElement>}
+ */
+export function collectTemplates(scope) {
+  /** @type {Map<string, HTMLTemplateElement>} */
+  const map = new Map();
+  for (const tpl of scope.querySelectorAll('template[ht-template]')) {
+    const id = tpl.getAttribute('ht-template');
+    if (id) map.set(id, /** @type {HTMLTemplateElement} */ (tpl));
+  }
+  return map;
+}
+
+/**
+ * @param {Element} el
+ * @returns {boolean} true for a <template> definition (inert; removed from output)
+ */
+export function isTemplateDefinition(el) {
+  return el.tagName === 'TEMPLATE' && el.hasAttribute('ht-template');
+}
+```
+
+- [ ] **Step 4: Update `src/index.js`** — collect templates in the render pre-pass. Replace the `templates: new Map(),` line and add the import:
+
+```js
+import { collectTemplates } from './handlers/template.js';
+// in render(), replace `templates: new Map(),` with:
+    templates: collectTemplates(options.templates ?? element.ownerDocument),
+```
+
+- [ ] **Step 5: Update `src/walker.js`** — remove template definitions from output. Add the import and make this the first statement of `walk`:
+
+```js
+import { isTemplateDefinition } from './handlers/template.js';
+// first statement of walk():
+  if (isTemplateDefinition(el)) {
+    el.remove();
+    return;
+  }
+```
+
+- [ ] **Step 6: Update `src/handlers/loop.js`** — instantiate a referenced template instead of the children. Replace the three lines starting at `const doc = el.ownerDocument;` (through the `while (el.firstChild) ...` line) with:
+
+```js
+import { HtfError } from '../errors.js';  // already imported
+
+// replacing the itemTemplate construction inside applyLoop:
+  const doc = el.ownerDocument;
+  const templateId = el.getAttribute('ht-template');
+  /** @type {DocumentFragment} */
+  let itemTemplate;
+  if (templateId !== null) {
+    const tpl = state.templates.get(templateId);
+    if (!tpl) {
+      throw new HtfError(
+        `unregistered template id "${templateId}"`, el, 'ht-template');
+    }
+    itemTemplate = /** @type {DocumentFragment} */ (tpl.content.cloneNode(true));
+    el.textContent = '';
+  } else {
+    itemTemplate = doc.createDocumentFragment();
+    while (el.firstChild) itemTemplate.appendChild(el.firstChild);
+  }
+```
+
+- [ ] **Step 7: Run to verify pass**
+
+Run: `npm test`
+Expected: all tests pass.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/handlers/template.js src/index.js src/walker.js src/handlers/loop.js test/template.test.js
+git commit -m "Add ht-template registration and loop instantiation."
+```
+
+---
+
+### Task 11: Render atomicity and debug warnings
+
+**Files:**
+- Test: `test/atomicity.test.js` (no production code expected — these tests verify behavior already built in Tasks 5–10; fix the implementation if any fail)
+
+**Interfaces:**
+- Consumes: `render` (Task 5), loop error behavior (Task 9).
+- Produces: verified spec guarantees — a throwing render leaves the previous DOM intact; `options.debug` logs warnings; no logging otherwise.
+
+- [ ] **Step 1: Write the test `test/atomicity.test.js`**
+
+```js
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render } from '../src/index.js';
+
+function container(html) {
+  const div = document.createElement('div');
+  div.innerHTML = html;
+  document.body.appendChild(div);
+  return div;
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('render atomicity', () => {
+  it('leaves the previously rendered DOM intact when a later render throws', () => {
+    const c = container('<ul ht-loop="$.items"><li ht-bind="$.n">n</li></ul>');
+    render(c, { items: [{ n: 'one' }] });
+    expect(c.querySelector('li')?.textContent).toBe('one');
+    expect(() => render(c, { items: 42 })).toThrow();
+    expect(c.querySelector('li')?.textContent).toBe('one');
+  });
+});
+
+describe('debug warnings', () => {
+  it('warns about missing paths when debug is on', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const c = container('<div ht-bind="$.missing">x</div>');
+    render(c, {}, { debug: true });
+    expect(spy).toHaveBeenCalledOnce();
+    expect(spy.mock.calls[0][0]).toContain('$.missing');
+  });
+
+  it('stays silent when debug is off', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const c = container('<div ht-bind="$.missing">x</div>');
+    render(c, {});
+    expect(spy).not.toHaveBeenCalled();
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify pass**
+
+Run: `./node_modules/.bin/vitest run test/atomicity.test.js`
+Expected: 3 passed. If the atomicity test fails, the bug is in `src/index.js` — `walk` must run on the detached `working` clone with the attribute/children swap only after `walk` returns.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add test/atomicity.test.js
+git commit -m "Verify render atomicity and debug warnings."
+```
+
+---
+
+### Task 12: HTMT docs conformance fixtures
+
+**Files:**
+- Create: `test/fixtures.js`, `test/conformance.test.js`
+
+**Interfaces:**
+- Consumes: `render` (Task 5) and all handlers.
+- Produces: `fixtures` array of `{name, html, data, expected}` reusable by future implementations.
+
+- [ ] **Step 1: Write `test/fixtures.js`** (each fixture is an example from the HTMT docs, adapted to concrete data; expected output keeps the ht-* attributes)
+
+```js
+export const fixtures = [
+  {
+    name: 'ht-bind replaces placeholder content',
+    html: `<div ht-bind="$.user.name">This will be replaced</div>`,
+    data: { user: { name: 'Ada Lovelace' } },
+    expected: `<div ht-bind="$.user.name">Ada Lovelace</div>`,
+  },
+  {
+    name: 'ht-loop renders a list with item-scoped binds',
+    html: `<ul ht-loop="$.users[*]"><li>Name: <span ht-bind="$.name"></span>, Email: <span ht-bind="$.email"></span></li></ul>`,
+    data: {
+      users: [
+        { name: 'Ada', email: 'ada@example.com' },
+        { name: 'Grace', email: 'grace@example.com' },
+      ],
+    },
+    expected:
+      `<ul ht-loop="$.users[*]">` +
+      `<li>Name: <span ht-bind="$.name">Ada</span>, Email: <span ht-bind="$.email">ada@example.com</span></li>` +
+      `<li>Name: <span ht-bind="$.name">Grace</span>, Email: <span ht-bind="$.email">grace@example.com</span></li>` +
+      `</ul>`,
+  },
+  {
+    name: 'ht-loop filter renders only matching items',
+    html: `<div ht-loop="$.users[?(@.isActive)]"><p ht-bind="$.name"></p></div>`,
+    data: {
+      users: [
+        { name: 'Ada', isActive: true },
+        { name: 'Bob', isActive: false },
+        { name: 'Eve', isActive: true },
+      ],
+    },
+    expected: `<div ht-loop="$.users[?(@.isActive)]"><p ht-bind="$.name">Ada</p><p ht-bind="$.name">Eve</p></div>`,
+  },
+  {
+    name: 'ht-template instantiated per loop item',
+    html:
+      `<template ht-template="user-info"><div><h2 ht-bind="$.name">Name</h2><p ht-bind="$.email">Email</p></div></template>` +
+      `<div ht-loop="$.users[*]" ht-template="user-info"></div>`,
+    data: { users: [{ name: 'Ada', email: 'ada@example.com' }] },
+    expected: `<div ht-loop="$.users[*]" ht-template="user-info"><div><h2 ht-bind="$.name">Ada</h2><p ht-bind="$.email">ada@example.com</p></div></div>`,
+  },
+  {
+    name: 'ht-root-bind escapes the loop scope',
+    html: `<ul ht-loop="$.items[*]"><li><span ht-bind="$.label"></span> of <span ht-root-bind="$.total"></span></li></ul>`,
+    data: { total: 2, items: [{ label: 'first' }, { label: 'second' }] },
+    expected:
+      `<ul ht-loop="$.items[*]">` +
+      `<li><span ht-bind="$.label">first</span> of <span ht-root-bind="$.total">2</span></li>` +
+      `<li><span ht-bind="$.label">second</span> of <span ht-root-bind="$.total">2</span></li>` +
+      `</ul>`,
+  },
+  {
+    name: 'local ht-bind wins over ht-root-bind',
+    html: `<div ht-root-bind="$.user.name" ht-bind="$.profile.name">Default Name</div>`,
+    data: { user: { name: 'Root User' }, profile: { name: 'Local Profile' } },
+    expected: `<div ht-root-bind="$.user.name" ht-bind="$.profile.name">Local Profile</div>`,
+  },
+  {
+    name: 'ht-switch keeps only the matching ht-case',
+    html: `<div ht-switch="$.user.role"><div ht-case="'admin'">Admin content</div><div ht-case="'guest'">Guest content</div></div>`,
+    data: { user: { role: 'admin' } },
+    expected: `<div ht-switch="$.user.role"><div ht-case="'admin'">Admin content</div></div>`,
+  },
+  {
+    name: 'ht-class-* toggles classes from comparisons',
+    html: `<div ht-class-active="$.user.status == 'active'" ht-class-banned="$.user.status == 'banned'">U</div>`,
+    data: { user: { status: 'active' } },
+    expected: `<div ht-class-active="$.user.status == 'active'" ht-class-banned="$.user.status == 'banned'" class="active">U</div>`,
+  },
+  {
+    name: 'ht-attr-src binds an attribute',
+    html: `<img ht-attr-src="$.user.avatarUrl" alt="avatar">`,
+    data: { user: { avatarUrl: 'https://example.com/a.png' } },
+    expected: `<img ht-attr-src="$.user.avatarUrl" alt="avatar" src="https://example.com/a.png">`,
+  },
+  {
+    name: 'ht-show hides on falsy and ht-hide shows on falsy',
+    html: `<div ht-show="$.user.isLoggedIn">In</div><div ht-hide="$.user.isAnonymous">Content</div>`,
+    data: { user: { isLoggedIn: false, isAnonymous: false } },
+    expected: `<div ht-show="$.user.isLoggedIn" hidden="">In</div><div ht-hide="$.user.isAnonymous">Content</div>`,
+  },
+];
+```
+
+- [ ] **Step 2: Write `test/conformance.test.js`**
+
+```js
+import { describe, it, expect } from 'vitest';
+import { render } from '../src/index.js';
+import { fixtures } from './fixtures.js';
+
+/** Collapse whitespace-only gaps between tags so fixtures stay readable. */
+function normalize(html) {
+  return html.replace(/>\s+</g, '><').trim();
+}
+
+describe('HTMT docs conformance', () => {
+  for (const f of fixtures) {
+    it(f.name, () => {
+      const container = document.createElement('div');
+      container.innerHTML = f.html;
+      document.body.appendChild(container);
+      render(container, f.data);
+      expect(normalize(container.innerHTML)).toBe(normalize(f.expected));
+      container.remove();
+    });
+  }
+});
+```
+
+- [ ] **Step 3: Run the conformance suite**
+
+Run: `./node_modules/.bin/vitest run test/conformance.test.js`
+Expected: 10 passed. An attribute-ORDER mismatch (not attribute values) means the DOM serializer emits attributes differently than the fixture string — fix the FIXTURE to match the serializer's order, since attribute order is not semantically meaningful.
+
+- [ ] **Step 4: Run everything**
+
+Run: `npm test`
+Expected: all suites pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test/fixtures.js test/conformance.test.js
+git commit -m "Add the HTMT docs conformance fixtures."
+```
+
+---
+
+### Task 13: Type check and CI workflow
+
+**Files:**
+- Create: `.github/workflows/test.yml`
+- Modify: `src/**/*.js` only if `tsc` reports errors
+
+**Interfaces:**
+- Consumes: the `typecheck` npm script (Task 1).
+- Produces: green `npm run typecheck`; CI running tests + typecheck on push and PR.
+
+- [ ] **Step 1: Run the type checker**
+
+Run: `npm run typecheck`
+Expected: exit 0. If there are errors, fix them by tightening JSDoc annotations or adding `/** @type {...} */` casts at the reported lines — do NOT weaken `jsconfig.json` (no `strict: false`, no excluding files).
+
+- [ ] **Step 2: Write `.github/workflows/test.yml`**
+
+```yaml
+name: Test
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/*'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Check types
+        run: npm run typecheck
+```
+
+- [ ] **Step 3: Verify the full local gate**
+
+Run: `npm test && npm run typecheck`
+Expected: both green.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add .github/workflows/test.yml src
+git commit -m "Add JSDoc type checking fixes and the CI workflow."
+```
+
+---
+
+### Task 14: README, CHANGELOG, CONTRIBUTING
+
+**Files:**
+- Modify: `README.md`
+- Create: `CHANGELOG.md`, `CONTRIBUTING.md`
+
+**Interfaces:**
+- Consumes: the public API (Task 5) for the README examples.
+- Produces: user-facing docs; no code.
+
+- [ ] **Step 1: Write `README.md`**
+
+```markdown
+# js-HTF
+
+JavaScript reference implementation of [HTMT](https://github.com/ViewDescriptorProtocol/HTMT)
+(HyperText Markup Templating): declarative data binding for HTML using `ht-*`
+attributes with [JSONPath](https://www.rfc-editor.org/rfc/rfc9535) expressions.
+
+> **Working draft.** js-HTF tracks the HTMT spec, which is in early alpha.
+
+## Install
+
+```bash
+npm install js-htf
+```
+
+## Quick start
+
+```html
+<ul id="users" ht-loop="$.users[*]">
+  <li>
+    <span ht-bind="$.name"></span>
+    <span ht-attr-title="$.email"></span>
+  </li>
+</ul>
+```
+
+```js
+import { render } from 'js-htf';
+
+render(document.getElementById('users'), {
+  users: [
+    { name: 'Ada', email: 'ada@example.com' },
+    { name: 'Grace', email: 'grace@example.com' },
+  ],
+});
+```
+
+Calling `render` again with new data re-renders from a pristine copy of the
+original template — rendering is one-shot, with no retained reactivity.
+
+## API
+
+### `render(element, data, options?)`
+
+Processes every `ht-*` attribute in `element`'s subtree against `data`, in place.
+
+- `options.templates` — where `<template ht-template="id">` definitions are
+  looked up (default: the element's document).
+- `options.debug` — log a warning for each expression that matches nothing.
+
+Template-author mistakes (bad JSONPath, `ht-case` outside `ht-switch`,
+`ht-loop` over a non-array, unknown template id) throw `HtfError`. Missing
+data never throws: text renders empty, conditions are false, loops render
+zero items.
+
+### Supported attributes
+
+All attributes documented in the [HTMT docs](https://github.com/ViewDescriptorProtocol/HTMT/tree/main/docs),
+including every `ht-root-*` variant (root access from nested loop scopes;
+the local attribute wins when both are present).
+
+## Relationship to HTMX and Alpine.js
+
+**HTMX** is complementary: it transports HTML fragments and has no built-in
+answer for JSON responses — HTMT is that missing piece. The
+[htmx-HTF](https://github.com/ViewDescriptorProtocol/htmx-HTF) project provides
+the integration.
+
+**Alpine.js** overlaps on rendering directives, but differs in intent: Alpine
+embeds arbitrary JavaScript in attributes and is a reactive framework with
+component state and events. HTMT expressions are JSONPath plus a small
+comparison grammar — declarative, CSP-safe, and implementable in any
+language — and rendering is a one-shot binding of server-provided JSON.
+That language-neutrality is the point: HTMT is a spec, js-HTF its reference
+implementation, and the same templates could be rendered by implementations
+on other platforms. Features that would push js-HTF toward Alpine's territory
+(state, events, reactivity) are out of scope by design.
+
+## License
+
+[MIT](LICENSE)
+```
+
+- [ ] **Step 2: Write `CHANGELOG.md`**
+
+```markdown
+# Changelog
+
+All notable changes to js-HTF are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] — Unreleased
+
+### Added
+
+- `render(element, data, options)`: one-shot tree-walk rendering of the full
+  HTMT attribute set — `ht-bind`, `ht-loop`, `ht-template`, `ht-attr-[name]`,
+  `ht-show` / `ht-hide`, `ht-switch` / `ht-case`, `ht-class-[name]`, and all
+  `ht-root-*` variants with local-over-root precedence.
+- JSONPath resolution via [json-p3](https://github.com/jg-rp/json-p3)
+  (RFC 9535), plus the HTMT comparison grammar (`==` / `!=` against literals).
+- Re-rendering from pristine template clones; atomic renders (a throwing
+  render leaves the previous DOM intact); `HtfError` for template mistakes;
+  optional debug warnings for unmatched paths.
+- Conformance test suite generated from the HTMT documentation examples.
+```
+
+- [ ] **Step 3: Write `CONTRIBUTING.md`**
+
+```markdown
+# Contributing to js-HTF
+
+js-HTF is the JavaScript reference implementation of the
+[HTMT](https://github.com/ViewDescriptorProtocol/HTMT) spec, which is an early
+working draft. Contributions are welcome.
+
+## How to contribute
+
+- **Discuss first.** For anything beyond a small fix, open a GitHub issue
+  before writing a pull request.
+- **Branches.** Development happens on `develop`; `main` is fast-forwarded
+  from it. Target pull requests at `develop`.
+- **Spec first.** Behavior changes must match the HTMT documentation. If the
+  spec is silent or wrong, raise it in the HTMT repository before changing
+  the implementation.
+
+## Development
+
+Plain ESM JavaScript with JSDoc types — there is no build step.
+
+```bash
+npm install
+npm test            # vitest + happy-dom
+npm run typecheck   # tsc --checkJs over the JSDoc annotations
+```
+
+Every HTMT docs example lives in `test/fixtures.js` as a conformance fixture;
+new spec examples should gain a fixture in the same pull request.
+
+- Add an entry to `CHANGELOG.md`
+  ([Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format) for any
+  user-visible change.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+[MIT License](LICENSE).
+```
+
+- [ ] **Step 4: Final full gate**
+
+Run: `npm test && npm run typecheck`
+Expected: both green.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add README.md CHANGELOG.md CONTRIBUTING.md
+git commit -m "Write the README, CHANGELOG, and CONTRIBUTING docs."
+```
+
+---
+
+## Completion
+
+After Task 14: all tests green, typecheck green, working tree clean, everything on `develop` (do NOT push or fast-forward `main` — the user decides when). Follow-ups that are explicitly OUT of scope for this plan: publishing to npm, the HTMT repo's cross-links to js-HTF, and htmx-HTF.