/* =========================================================================
   composing-html / base.js
   Tiny vanilla helpers. No framework. Activated only if the markup needs it.
   ========================================================================= */
(function () {
  'use strict';

  // Copy-to-clipboard for <pre><code> blocks marked .code-wrap or any pre.
  function initCopyButtons() {
    document.querySelectorAll('pre').forEach(function (pre) {
      if (pre.dataset.copyInit) return;
      pre.dataset.copyInit = '1';
      var wrap = pre.parentElement;
      if (!wrap || !wrap.classList.contains('code-wrap')) {
        wrap = document.createElement('div');
        wrap.className = 'code-wrap';
        pre.parentNode.insertBefore(wrap, pre);
        wrap.appendChild(pre);
      }
      var btn = document.createElement('button');
      btn.className = 'copy-btn';
      btn.type = 'button';
      btn.textContent = 'copy';
      btn.addEventListener('click', function () {
        var text = pre.innerText;
        navigator.clipboard.writeText(text).then(function () {
          btn.textContent = 'copied';
          setTimeout(function () { btn.textContent = 'copy'; }, 1400);
        }).catch(function () { btn.textContent = 'err'; });
      });
      wrap.appendChild(btn);
    });
  }

  // Tab groups: <div class="tabgroup"><div class="tabs"><button data-target="x">..</button></div>
  //             <div class="tab-panel" data-id="x">..</div></div>
  function initTabs() {
    document.querySelectorAll('.tabgroup').forEach(function (group) {
      var buttons = group.querySelectorAll('.tabs button[data-target]');
      var panels  = group.querySelectorAll('.tab-panel[data-id]');
      function show(id) {
        buttons.forEach(function (b) { b.setAttribute('aria-selected', b.dataset.target === id ? 'true' : 'false'); });
        panels.forEach(function (p)  { p.dataset.active = p.dataset.id === id ? 'true' : 'false'; });
      }
      buttons.forEach(function (b) { b.addEventListener('click', function () { show(b.dataset.target); }); });
      var first = buttons[0];
      if (first) show(first.dataset.target);
    });
  }

  // Slide deck: arrow-key & space navigation between .slide elements.
  // Activated only when document.body has data-deck="true".
  function initDeck() {
    if (document.body.dataset.deck !== 'true') return;
    var slides = Array.prototype.slice.call(document.querySelectorAll('.slide'));
    if (!slides.length) return;
    function currentIndex() {
      var mid = window.innerHeight / 2;
      for (var i = 0; i < slides.length; i++) {
        var r = slides[i].getBoundingClientRect();
        if (r.top <= mid && r.bottom > mid) return i;
      }
      return 0;
    }
    function go(delta) {
      var i = Math.max(0, Math.min(slides.length - 1, currentIndex() + delta));
      slides[i].scrollIntoView({ behavior: 'smooth', block: 'start' });
    }
    document.addEventListener('keydown', function (e) {
      if (e.target && /^(input|textarea|select)$/i.test(e.target.tagName)) return;
      if (e.key === 'ArrowRight' || e.key === 'PageDown' || e.key === ' ') { e.preventDefault(); go(+1); }
      else if (e.key === 'ArrowLeft' || e.key === 'PageUp') { e.preventDefault(); go(-1); }
      else if (e.key === 'Home') { e.preventDefault(); slides[0].scrollIntoView({ behavior: 'smooth' }); }
      else if (e.key === 'End')  { e.preventDefault(); slides[slides.length - 1].scrollIntoView({ behavior: 'smooth' }); }
    });
  }

  // Drag-to-reorder for editor-style triage boards.
  // Markup: a container with data-sortable="true" and direct children with [draggable="true"].
  // Cross-zone moves work because `dragged` is module-scoped, not per-zone.
  var dragged = null;

  function initSortable() {
    document.querySelectorAll('[data-sortable="true"]').forEach(function (zone) {
      if (zone.dataset.sortInit) return;
      zone.dataset.sortInit = '1';

      zone.addEventListener('dragstart', function (e) {
        var t = e.target.closest('[draggable="true"]');
        if (!t || t.parentElement !== zone) return;
        dragged = t;
        t.style.opacity = '0.4';
        try { e.dataTransfer.effectAllowed = 'move'; } catch (_) {}
      });

      zone.addEventListener('dragend', function () {
        if (dragged) dragged.style.opacity = '';
        dragged = null;
      });

      zone.addEventListener('dragover', function (e) {
        if (!dragged) return;
        e.preventDefault();
        try { e.dataTransfer.dropEffect = 'move'; } catch (_) {}
        var after = null;
        var children = Array.prototype.slice.call(zone.children)
          .filter(function (c) { return c !== dragged && c.draggable; });
        for (var i = 0; i < children.length; i++) {
          var box = children[i].getBoundingClientRect();
          if (e.clientY < box.top + box.height / 2) { after = children[i]; break; }
        }
        if (after) zone.insertBefore(dragged, after);
        else if (dragged.parentElement !== zone || zone.lastElementChild !== dragged) zone.appendChild(dragged);
      });

      zone.addEventListener('drop', function (e) {
        if (dragged) e.preventDefault();
      });
    });
  }

  // Live param controls: any [data-bind] input updates the textContent of [data-out="<name>"].
  // Optional: [data-format="number|percent|ms"].
  function initBindings() {
    var fmt = {
      number:  function (v) { return Number(v).toString(); },
      percent: function (v) { return (Number(v) * 100).toFixed(0) + '%'; },
      ms:      function (v) { return Number(v) + 'ms'; }
    };
    document.querySelectorAll('input[data-bind], select[data-bind]').forEach(function (el) {
      function push() {
        var name = el.dataset.bind;
        var f = fmt[el.dataset.format] || function (v) { return v; };
        document.querySelectorAll('[data-out="' + name + '"]').forEach(function (o) { o.textContent = f(el.value); });
        // CSS-var bridge: --bind-<name>
        document.documentElement.style.setProperty('--bind-' + name, el.value + (el.dataset.unit || ''));
      }
      el.addEventListener('input', push);
      push();
    });
  }

  function ready(fn) {
    if (document.readyState !== 'loading') fn();
    else document.addEventListener('DOMContentLoaded', fn);
  }

  ready(function () {
    initCopyButtons();
    initTabs();
    initDeck();
    initSortable();
    initBindings();
  });
})();

# Palette and primitives

The base CSS is inlined into every artifact. You can use these tokens and
classes inside any `*_html` field — including `freeform.body_html` — without
re-declaring them.

## Color tokens

| Token | Hex | Use |
|---|---|---|
| `--ivory` | `#FAF9F5` | Page background |
| `--paper` | `#FFFFFF` | Card background |
| `--slate` | `#141413` | Headings, inverted background |
| `--clay` | `#D97757` | Brand accent (lines, primary actions) |
| `--clay-d` | `#B85C3E` | Hover/dark variant |
| `--oat` | `#E3DACC` | Soft contrast surface |
| `--olive` | `#788C5D` | Success, secondary accent |
| `--rust` | `#B04A3F` | Errors, destructive |
| `--moss` | `#4A6B3A` | Success text |
| `--g100` … `--g700` | grays | Surfaces, borders, body text |

Semantic aliases: `--ok`, `--warn`, `--err`, `--info`.

## Type stacks

- `--serif` — display headings (h1, h2, big numerics).
- `--sans` — body text (default).
- `--mono` — code, eyebrows, badges, captions.

## Geometry

`--radius-sm` (6px) · `--radius` (10px) · `--radius-lg` (16px) ·
`--border` · `--border-soft` · `--shadow-card` · `--shadow-pop`.

## Layout primitives

- `.page` — main column (1080px max). Variants: `.page--wide` (1280px),
  `.page--narrow` (720px).
- `.masthead` — header strip with `.eyebrow` + `<h1>` + `.subtitle`.
- `.grid .grid--2|3|4|auto` — responsive CSS grid.
- `.stack`, `.row` — vertical / horizontal flex.
- `.card`, `.card--soft`, `.card--elev` — content containers.
- `.rule` — `<hr>` underline below `<h2>`.
- `.colophon` — optional footer strip; pass `colophon="text"` to `page()` to
  show it (off by default).

## Components

- **Eyebrow**: `<div class="eyebrow">SECTION</div>` — small all-caps label
  with a leading clay rule.
- **Badge**: `<span class="badge badge--ok|warn|err|info|clay">v1.0</span>`.
- **Kbd**: `<span class="kbd">⌘K</span>`.
- **Bullets**: `<ul class="bullets"><li>…</li></ul>` — clay dots.
- **Code**: inline `<code>` and block `<pre><code>`. Block code gets a
  `copy` button automatically via `base.js`.
- **Details**: native `<details><summary>…</summary>…</details>` styled.

## Tabs

```html
<div class="tabgroup">
  <div class="tabs">
    <button data-target="a">Tab A</button>
    <button data-target="b">Tab B</button>
  </div>
  <div class="tab-panel" data-id="a">…</div>
  <div class="tab-panel" data-id="b">…</div>
</div>
```

`base.js` wires this automatically and selects the first tab by default.

## Drag-to-reorder

```html
<div data-sortable="true">
  <div draggable="true">…</div>
  <div draggable="true">…</div>
</div>
```

Optional cross-zone drops: add `data-zone="<id>"` to each container.

## Live parameter bindings

```html
<input type="range" data-bind="size" min="0" max="100" value="50" data-format="number" data-unit="px">
<span data-out="size"></span>
<style>.box { width: var(--bind-size, 50px); }</style>
```

The CSS custom property `--bind-<name>` is updated on every input event,
and any `[data-out="<name>"]` element receives the formatted value.

## Helper functions (Python side)

If you're calling templates from a custom builder, `composer.py` exposes:

`esc`, `attrs`, `tag`, `void`, `eyebrow`, `badge`, `kbd`, `code_block`,
`inline_code`, `section`, `card`, `grid`, `stack`, `row`, `bullets`,
`kv_list`, `table`, `details`, `tabs`, `callout`, `slug`.

These all return HTML strings and accept plain Python data.

# Template reference

Detailed parameter spec for each template. Read **only the section you need**;
each template's `describe` output covers the same ground in CLI form.

For all templates: spec keys ending in `_html` are inserted verbatim — escape
your own content there if it contains user input. All other string values are
HTML-escaped automatically.

---

## exploration.comparison_grid

```json
{
  "title": "Three caching approaches",
  "subtitle": "Tradeoffs across latency, memory, complexity",
  "eyebrow": "EXPLORATION",
  "recommendation": "In-memory LRU",
  "options": [
    {
      "name": "In-memory LRU",
      "verdict": "Simplest, lowest latency",
      "summary": "Per-process bounded cache.",
      "pros": ["Sub-µs hits", "No external dep"],
      "cons": ["Per-process duplication", "Cold on restart"],
      "tags": ["latency:fast", "cost:low"]
    }
  ]
}
```

`recommendation` (optional): exact `name` of the option to highlight with a
double border + clay accent + `RECOMMENDED` badge. Up to 3 options render
side-by-side; more wrap to additional rows.

---

## exploration.design_directions

```json
{
  "title": "Brand directions",
  "directions": [
    {
      "name": "Stoneware",
      "vibe": "Warm, grounded, hand-thrown",
      "palette": ["#FAF9F5", "#D97757", "#3D3D3A", "#788C5D"],
      "typography": {"display": "Aa", "body": "The quick brown fox..."},
      "notes": "Pairs with serif display + sans body."
    }
  ]
}
```

Each direction renders as a card with palette swatches, a sample type block,
and notes.

---

## exploration.implementation_plan

```json
{
  "title": "Search v2 rollout",
  "summary_html": "<p>Cutover from BM25 to hybrid.</p>",
  "data_flow": ["Query", "Embed", "Hybrid score", "Rerank", "Response"],
  "milestones": [
    {"name": "Embedding pipeline", "when": "Wk 1", "owner": "alex",
     "deliverables": ["Tokenizer", "Batcher"], "status": "done"},
    {"name": "Hybrid scorer", "when": "Wk 2", "deliverables": ["RRF fusion"], "status": "active"}
  ],
  "risks": [
    {"risk": "Latency spike", "likelihood": "med", "impact": "high",
     "mitigation": "Pre-warm + canary."}
  ]
}
```

`status`: `done | active | next | later` controls the dot color in the
timeline. `data_flow` is a simple list of step names rendered as
arrow-connected boxes.

---

## review.pr_review

```json
{
  "title": "PR #247 — Caching layer",
  "pr": {"repo": "octo/svc", "number": 247, "branch": "feat/cache",
         "author": "@jess", "additions": 312, "deletions": 48},
  "verdict": "Approve with minor follow-ups",
  "summary_html": "<p>Adds in-memory LRU on the search hot path.</p>",
  "findings": [
    {
      "file": "src/search/cache.py",
      "line": 42,
      "severity": "warn",
      "title": "LRU max size hardcoded",
      "body_html": "<p>Pull from config to allow per-env tuning.</p>",
      "snippet": "CACHE_MAX = 1024",
      "snippet_lang": "python"
    }
  ]
}
```

`severity`: `info | nit | warn | block`.

---

## review.code_walkthrough

```json
{
  "title": "How retrieval works",
  "intro_html": "<p>The retrieval path is three stages.</p>",
  "steps": [
    {"heading": "Tokenize", "body_html": "<p>Whitespace + lowercasing.</p>",
     "code": "tokens = text.lower().split()", "lang": "python"}
  ]
}
```

Steps are rendered as numbered (01, 02, …) two-column rows. Narrow page width.

---

## review.module_map

```json
{
  "title": "Service map",
  "intro_html": "<p>Top-level packages.</p>",
  "nodes": [
    {"id": "api", "label": "api", "description": "HTTP handlers", "kind": "core"},
    {"id": "engine", "label": "engine", "description": "ranking", "kind": "core"},
    {"id": "cache", "label": "cache", "description": "LRU", "kind": "util"},
    {"id": "db", "label": "postgres", "description": "index store", "kind": "external"}
  ],
  "edges": [
    {"from": "api", "to": "engine"},
    {"from": "engine", "to": "cache", "label": "hot path"}
  ],
  "legend": [{"label": "core", "kind": "core"}, {"label": "util", "kind": "util"}]
}
```

`kind`: `core | util | external` controls fill/border. `x` and `y` are
optional — auto-laid in a 3-column grid if omitted.

---

## design.design_system

```json
{
  "title": "Birchline design tokens",
  "colors": {
    "Brand": [{"name": "Clay", "hex": "#D97757", "token": "--clay"}],
    "Neutral": [{"name": "Slate", "hex": "#141413", "token": "--slate"}]
  },
  "typography": [
    {"name": "Display", "font_family": "var(--serif)", "size": "48px", "weight": "500", "line_height": "1.1"},
    {"name": "Body", "font_family": "var(--sans)", "size": "16px", "weight": "430"}
  ],
  "spacing": [{"name": "xs", "px": 4}, {"name": "sm", "px": 8}, {"name": "md", "px": 16}],
  "radii": [{"name": "sm", "px": 4}, {"name": "md", "px": 10}, {"name": "lg", "px": 16}]
}
```

Any group of colors is allowed — keys become section labels.

---

## design.component_variants

```json
{
  "title": "Button variants",
  "components": [
    {
      "name": "Button",
      "description": "Sizes × intents.",
      "axes": {
        "Size": ["sm", "md", "lg"],
        "Intent": ["default", "primary", "danger"]
      },
      "cells": [
        {"coords": {"Size": "sm", "Intent": "default"}, "html": "<button>Click</button>"},
        {"coords": {"Size": "md", "Intent": "primary"},
         "html": "<button style='background:var(--clay);color:white;border:none;padding:8px 16px;border-radius:6px;'>Click</button>"}
      ]
    }
  ]
}
```

With ≥2 axes, cells render in a labelled table. With 1 axis, cells render in
an auto grid of cards.

---

## prototype.animation_sandbox

```json
{
  "title": "Easing playground",
  "params": [
    {"name": "duration", "label": "Duration", "type": "range", "min": 100, "max": 2000, "step": 50, "default": 600, "unit": "ms", "format": "ms"},
    {"name": "easing", "label": "Easing", "type": "select", "options": ["ease", "ease-in-out", "linear", "cubic-bezier(.2,.8,.2,1)"], "default": "ease-in-out"}
  ],
  "preview_html": "<div id='ball' style='width:60px;height:60px;background:var(--clay);border-radius:50%;animation:bounce var(--bind-duration,600ms) var(--bind-easing,ease) infinite alternate;'></div><style>@keyframes bounce{from{transform:translateX(0)}to{transform:translateX(200px)}}</style>",
  "preview_height": "240px"
}
```

Each `param`'s value lands in the CSS custom property `--bind-<name>`
(append `unit` to the value) and is mirrored to any element with
`data-out="<name>"`.

---

## prototype.click_flow

```json
{
  "title": "Onboarding flow",
  "screens": [
    {"id": "welcome", "label": "Welcome", "html": "<h2>Welcome</h2><p>...</p>",
     "transitions": [{"label": "Get started →", "to_id": "signup"}]},
    {"id": "signup", "label": "Sign up", "html": "<form>...</form>",
     "transitions": [{"label": "Submit →", "to_id": "done"}]},
    {"id": "done", "label": "Done", "html": "<p>You're in.</p>"}
  ]
}
```

Transitions are anchor links; clicking jumps to the target screen.

---

## diagram.svg_figure_sheet

```json
{
  "title": "Architecture figures",
  "figures": [
    {"label": "Fig. 1", "caption": "Request flow",
     "svg": "<svg viewBox='0 0 200 100'>...</svg>",
     "span": 1}
  ]
}
```

`span: 2` makes a figure occupy the full row in the 2-column grid.

---

## diagram.flowchart

```json
{
  "title": "Deploy pipeline",
  "orientation": "vertical",
  "steps": [
    {"id": "build", "label": "Build", "kind": "start"},
    {"id": "test", "label": "Tests pass?", "kind": "decision",
     "branches": [{"label": "yes", "to_id": "stage"}, {"label": "no", "to_id": "fail"}]},
    {"id": "stage", "label": "Deploy staging", "kind": "process",
     "details_html": "<p>Blue/green swap.</p>"},
    {"id": "prod", "label": "Deploy prod", "kind": "end"},
    {"id": "fail", "label": "Notify", "kind": "end"}
  ]
}
```

`kind`: `start | process | decision | end`. Steps with `details_html` get
collapsible expanders below the diagram.

---

## deck.slide_deck

```json
{
  "title": "Q2 review",
  "slides": [
    {"kind": "title", "title": "Q2 Roundup", "subtitle": "What shipped",
     "eyebrow": "PLATFORM", "byline": "may 9 · alex"},
    {"kind": "section", "title": "Shipped", "eyebrow": "PART ONE", "invert": true},
    {"kind": "content", "title": "Search", "body_html": "<ul class='bullets'><li>...</li></ul>"},
    {"kind": "quote", "quote": "Ship to learn.", "attribution": "team retro"},
    {"kind": "code", "title": "API", "code": "client.search(...)", "lang": "python"},
    {"kind": "image", "src": "https://...", "alt": "...", "caption": "..."}
  ]
}
```

If no `kind: title` slide exists, one is auto-prepended from `title` /
`subtitle`. Navigation: arrow keys + space + Page Up/Down + Home/End.

---

## research.feature_explainer

```json
{
  "title": "Streaming responses",
  "intro_html": "<p>How tokens flow.</p>",
  "sections": [
    {
      "id": "transport", "heading": "Transport",
      "body_html": "<p>SSE over HTTP/2.</p>",
      "code_tabs": [
        {"label": "JS", "code": "const r = await fetch(url);", "lang": "javascript"},
        {"label": "Python", "code": "with httpx.stream(...): ...", "lang": "python"}
      ]
    }
  ]
}
```

A sticky TOC links to each section by `id`. Tabs let you compare code samples
across languages without scroll.

---

## research.concept_explainer

```json
{
  "title": "Vector embeddings",
  "body_html": "<p>An embedding is...</p><h2>Distance</h2><p>Cosine similarity...</p>",
  "demo_html": "<div>...interactive demo region...</div>",
  "glossary": [
    {"term": "Cosine sim.", "definition_html": "<code>1 - cos(θ)</code>"}
  ]
}
```

Narrow page width. The `demo_html` slot is rendered inside an elevated card.

---

## report.status_report

```json
{
  "title": "Platform — Week of May 4",
  "subtitle": "Search GA, queue migration in flight",
  "metrics": [
    {"label": "Deploys", "value": "42", "delta": "+12 vs prev", "kind": "ok"},
    {"label": "P95", "value": "180ms", "delta": "-40ms", "kind": "ok"},
    {"label": "Open Sev2s", "value": "3", "delta": "+1", "kind": "warn"}
  ],
  "shipped":  [{"title": "Search GA", "owner": "alex", "body_html": "<p>Public launch.</p>"}],
  "in_flight":[{"title": "Queue migration", "owner": "jess", "progress": 0.6, "body_html": "<p>Cutover Friday.</p>"}],
  "blocked":  [{"title": "OAuth review", "owner": "sec-team", "body_html": "<p>Awaiting compliance.</p>"}]
}
```

`progress` is 0–1; rendered as a clay-filled bar with a percentage label.

---

## report.incident_report

```json
{
  "title": "INC-1247 — Search outage",
  "severity": "sev2",
  "duration": "47m",
  "impact_html": "<p>~12% of searches returned empty results.</p>",
  "summary_html": "<p>Index shard rebalance starved the read pool.</p>",
  "timeline": [
    {"at": "14:02", "event": "Spike in 5xx on /search", "kind": "detected"},
    {"at": "14:08", "event": "Paged on-call", "kind": "triage"},
    {"at": "14:32", "event": "Rolled back rebalance", "kind": "mitigation"},
    {"at": "14:49", "event": "Error rate normal", "kind": "resolved"}
  ],
  "root_cause_html": "<p>The rebalance scheduler had no concurrency cap.</p>",
  "followups": [
    {"title": "Cap rebalance concurrency", "owner": "platform", "due": "May 16", "status": "open"}
  ]
}
```

`severity`: `sev1 | sev2 | sev3 | sev4`.

---

## editor.triage_board

```json
{
  "title": "Triage",
  "columns": [
    {"id": "todo", "label": "To do", "color": "info",
     "items": [{"id": "i1", "title": "Fix auth bug", "tags": ["P1", "bug"]}]},
    {"id": "doing", "label": "Doing", "color": "clay",
     "items": [{"id": "i2", "title": "Refactor cache", "tags": ["P2"]}]},
    {"id": "done", "label": "Done", "color": "olive",
     "items": [{"id": "i3", "title": "Deploy v0.4"}]}
  ]
}
```

Cards are draggable within and across columns. `color`: `clay | olive | info | err`.

---

## editor.flag_editor

```json
{
  "title": "Feature flags",
  "flags": [
    {"id": "new_search", "label": "New search",
     "description": "Vector + BM25 hybrid.", "default": true},
    {"id": "reranker", "label": "Cross-encoder reranker",
     "description": "Cost: ~30ms.", "default": false,
     "requires": ["new_search"]},
    {"id": "legacy_search", "label": "Legacy search",
     "default": false, "conflicts_with": ["new_search"]}
  ]
}
```

When a flag is toggled on, missing `requires` and conflicting
`conflicts_with` flags surface as inline warnings.

---

## editor.prompt_tuner

```json
{
  "title": "Email subject tuner",
  "template": "Hi {{name}}, your {{item}} is {{status}}.",
  "variables": [
    {"name": "name", "label": "Recipient", "default": "Alex"},
    {"name": "item", "label": "Item", "type": "textarea", "default": "order #1234"},
    {"name": "status", "type": "select",
     "options": ["shipped", "delayed", "delivered"], "default": "shipped"}
  ]
}
```

Edit any variable; the rendered prompt updates live. `type`: `text` (default)
| `textarea` | `select`.

---

## freeform

```json
{
  "title": "Refactor proposal",
  "subtitle": "Extract OAuth into its own module",
  "eyebrow": "ARCHITECTURE",
  "body_html": "<section><h2>Why</h2><hr class='rule'><p>...</p></section>",
  "page_class": "page",
  "show_masthead": true
}
```

`page_class`: `page` | `page page--wide` | `page page--narrow`.

`extra_css` and `extra_js` accept raw strings appended after base styles.

`body_attrs`: dict on `<body>` (e.g. `{"data-deck": "true"}` to enable
arrow-key deck navigation on a custom layout).

#!/usr/bin/env python3
"""composing-html / build.py — CLI entry.

Usage
-----
  build.py list                                     # all templates, one line each
  build.py describe <template>                      # parameter reference for one template
  build.py build <template> [--spec FILE|-] [--set K=V ...] [--out FILE]
                                                    # render HTML; spec from FILE, stdin,
                                                    # and/or --set overrides
  build.py check <file.html> [--json]               # lint body/artifact for system drift
                                                    # and miswired interactive hooks

The "build" command reads a JSON spec, runs it through the named template's
builder, and emits a single self-contained HTML document. With no --out, the
result is written to stdout.

--set lets you supply or override a spec field from the command line, including
loading the value from a file via the @PATH suffix:

  build.py build freeform --set title='My Page' --set body_html=@body.html --out out.html

This sidesteps JSON-string escaping for multi-line HTML/CSS/JS bodies.

Templates live in scripts/templates/. Each module registers via the @register
decorator. See SKILL.md for the workflow.
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent
sys.path.insert(0, str(ROOT))

from composer import page

from templates import REGISTRY


def cmd_list(_args) -> int:
    width = max(len(name) for name in REGISTRY) if REGISTRY else 0
    print(f"{len(REGISTRY)} templates available:\n")
    for name in sorted(REGISTRY):
        print(f"  {name.ljust(width)}  {REGISTRY[name]['summary']}")
    print("\nNext: build.py describe <template>")
    return 0


def _infer_default(desc: str):
    """Pick a JSON-valid placeholder value from a spec_keys description string.

    Heuristic — looks for shape hints like 'List', 'Dict', 'Bool', 'List[{...}]'.
    The output is always parseable JSON so the printed skeleton can be edited
    in place rather than retyped.
    """
    d = desc.lower()
    if d.startswith("list") or d.startswith("optional list") or "list[" in d:
        import re as _re
        m = _re.search(r"\{([^}]+)\}", desc)
        if m:
            keys = []
            for raw_key in m.group(1).split(","):
                # Each key looks like "name", "pros[]", "status?", "kind?: 'a|b'".
                key = raw_key.strip().rstrip("?").split(":")[0].strip()
                is_list_key = key.endswith("[]")
                key = key.rstrip("[]").strip()
                if not key or not key.isidentifier():
                    continue
                keys.append((key, is_list_key))
            return [{k: ([] if is_l else "") for k, is_l in keys}] if keys else []
        return []
    if d.startswith("dict") or "dict[" in d:
        return {}
    if "bool" in d.split()[:3]:
        return False
    if d.startswith("optional"):
        return None
    return ""


def cmd_describe(args) -> int:
    name = args.template
    if name not in REGISTRY:
        print(f"unknown template: {name}", file=sys.stderr)
        print(f"see: {sys.argv[0]} list", file=sys.stderr)
        return 2
    entry = REGISTRY[name]
    print(f"# {name}\n\n{entry['summary']}\n")
    print("## Spec keys\n")
    for k, desc in entry["spec_keys"].items():
        required = "" if desc.lower().startswith("optional") else "  (required)"
        print(f"- `{k}`{required}: {desc}")
    print("\n## Starter spec (valid JSON — edit and pass to `build`)\n")
    skeleton = {k: _infer_default(desc) for k, desc in entry["spec_keys"].items()}
    print("```json")
    print(json.dumps(skeleton, indent=2, ensure_ascii=False))
    print("```\n")
    print(f"For richer worked examples, see references/templates.md → ## {name}\n")
    print("Build with:\n")
    print(f"  {sys.argv[0]} build {name} --spec spec.json --out out.html")
    return 0


def _apply_set(spec: dict, set_args: list[str]) -> int:
    """Mutate spec from --set KEY=VALUE / KEY=@FILE entries.

    Escape hatch for fields whose content fights JSON-string escaping
    (multi-line HTML, CSS, JS). Lets the caller keep the spec lean and
    point at raw files for the heavy bits.

    Syntax:
      --set body_html=@body.html        # spec['body_html'] = file contents
      --set title='My Page'             # spec['title']     = 'My Page'

    Returns 0 on success, 2 on error.
    """
    for entry in set_args or []:
        if "=" not in entry:
            print(f"--set expects KEY=VALUE or KEY=@FILE, got: {entry!r}", file=sys.stderr)
            return 2
        key, _, val = entry.partition("=")
        key = key.strip()
        if not key:
            print(f"--set missing key in: {entry!r}", file=sys.stderr)
            return 2
        if val.startswith("@"):
            path = val[1:]
            if not path:
                print(f"--set {key}=@ requires a file path", file=sys.stderr)
                return 2
            try:
                spec[key] = Path(path).read_text(encoding="utf-8")
            except OSError as e:
                print(f"--set {key}=@{path}: {e}", file=sys.stderr)
                return 2
        else:
            spec[key] = val
    return 0


def cmd_build(args) -> int:
    name = args.template
    if name not in REGISTRY:
        print(f"unknown template: {name}", file=sys.stderr)
        return 2

    # Spec is optional when every required field can be supplied via --set.
    if args.spec == "-":
        raw_text = sys.stdin.read()
    elif args.spec:
        raw_text = Path(args.spec).read_text(encoding="utf-8")
    else:
        raw_text = ""

    if raw_text.strip():
        try:
            spec = json.loads(raw_text)
        except json.JSONDecodeError as e:
            print(f"spec is not valid JSON: {e}", file=sys.stderr)
            return 2
        if not isinstance(spec, dict):
            print("spec must be a JSON object (dict)", file=sys.stderr)
            return 2
    else:
        spec = {}

    rc = _apply_set(spec, args.set or [])
    if rc != 0:
        return rc

    if not spec:
        print("empty spec (no --spec content and no --set entries)", file=sys.stderr)
        return 2

    builder = REGISTRY[name]["build"]
    page_kwargs = builder(spec)
    if not isinstance(page_kwargs, dict):
        print(f"template {name} did not return a dict", file=sys.stderr)
        return 2

    html = page(**page_kwargs)
    if args.out:
        Path(args.out).write_text(html, encoding="utf-8")
        print(f"wrote {args.out} ({len(html):,} bytes)", file=sys.stderr)
    else:
        sys.stdout.write(html)
    return 0


def cmd_check(args) -> int:
    from checker import check_html, format_findings, has_errors

    path = Path(args.file)
    if not path.exists():
        print(f"no such file: {args.file}", file=sys.stderr)
        return 2
    html = path.read_text(encoding="utf-8")

    fragment = None
    if args.fragment:
        fragment = True
    elif args.full:
        fragment = False

    findings = check_html(html, fragment=fragment)

    if args.json:
        print(json.dumps(
            [{"rule": f.rule, "severity": f.severity, "message": f.message,
              "detail": f.detail} for f in findings],
            indent=2))
    else:
        print(format_findings(findings))

    return 1 if has_errors(findings) else 0


def main(argv: list[str] | None = None) -> int:
    p = argparse.ArgumentParser(prog="build.py", description="Compose HTML artifacts from a small JSON spec.")
    sub = p.add_subparsers(dest="cmd", required=True)

    sub.add_parser("list", help="List all available templates.").set_defaults(fn=cmd_list)

    pd = sub.add_parser("describe", help="Show the spec for one template.")
    pd.add_argument("template")
    pd.set_defaults(fn=cmd_describe)

    pb = sub.add_parser("build", help="Render a template using the given spec.")
    pb.add_argument("template")
    pb.add_argument("--spec", "-s", default=None,
                    help="Path to JSON spec, or '-' for stdin. Optional if every "
                         "required field is supplied via --set.")
    pb.add_argument("--set", action="append", default=[],
                    metavar="KEY=VALUE",
                    help="Set or override a spec field. 'KEY=VALUE' assigns the "
                         "literal string; 'KEY=@FILE' loads the file contents. "
                         "Repeatable. Avoids JSON-string escaping for multi-line "
                         "HTML/CSS/JS (e.g. --set body_html=@body.html).")
    pb.add_argument("--out", "-o", default=None, help="Write HTML to this file (default: stdout).")
    pb.set_defaults(fn=cmd_build)

    pc = sub.add_parser("check", help="Lint a built artifact or body fragment for "
                                      "design-system drift and miswired hooks.")
    pc.add_argument("file", help="Path to the .html file to check.")
    pc.add_argument("--json", action="store_true", help="Emit findings as JSON.")
    pc.add_argument("--fragment", action="store_true",
                    help="Force fragment mode (body_html, no page chrome).")
    pc.add_argument("--full", action="store_true",
                    help="Force full-artifact mode (skip chrome-leak rule).")
    pc.set_defaults(fn=cmd_check)

    args = p.parse_args(argv)
    return args.fn(args)


if __name__ == "__main__":
    raise SystemExit(main())

"""Deterministic structural linter for composing-html output.

No LLM, no network, stdlib only. Catches the ways body content breaks *out*
of the composer's fixed design system or miswires its interactive hooks —
the inverse of a freehand design linter. The composer supplies a vetted token
palette and type stacks; this checker flags content that bypasses them or
wires `base.js` behaviours (tabs / binds / sortables) to nothing.

Each rule carries a stable `id` that is anchored in SKILL.md (`<!-- rule:ID -->`)
so the teaching and the enforcement stay linked.

Public API:
    check_html(html, *, fragment=None) -> list[Finding]
    format_findings(findings) -> str

Exit-code contract (CLI): 1 if any error-severity finding, else 0.

Deliberately NOT checked in v1: colour-contrast ratios. The token pairs are
pre-vetted, and contrast on author-introduced custom pairs needs colour math +
rendering that a regex pass can't do without false positives. Deferred.
"""

from __future__ import annotations

import html.parser as _hp
import re
from dataclasses import dataclass, field

# --------------------------------------------------------------------------- #
# canonical design tokens (mirror of assets/base.css :root)                   #
# --------------------------------------------------------------------------- #

BASE_TOKENS = {
    "ivory", "paper", "slate", "clay", "clay-d", "oat", "olive", "rust", "moss",
    "g100", "g150", "g200", "g300", "g500", "g700",
    "border", "border-soft",
    "radius", "radius-sm", "radius-lg",
    "shadow-card", "shadow-pop",
    "serif", "sans", "mono",
    "ok", "warn", "err", "info",
}

# colours that are fine as literals (not palette drift)
_COLOR_KEYWORD_OK = {"transparent", "currentcolor", "inherit", "none", "initial", "unset"}

_HEX_RE = re.compile(r"#[0-9a-fA-F]{3,8}\b")
_FUNC_COLOR_RE = re.compile(r"\b(?:rgb|rgba|hsl|hsla)\s*\(", re.IGNORECASE)
_VAR_RE = re.compile(r"var\(\s*--([a-z0-9-]+)", re.IGNORECASE)
_FONT_FAMILY_RE = re.compile(r"font-family\s*:", re.IGNORECASE)
_FONT_SIZE_RE = re.compile(r"font-size\s*:", re.IGNORECASE)


# --------------------------------------------------------------------------- #
# findings                                                                    #
# --------------------------------------------------------------------------- #

@dataclass
class Finding:
    rule: str
    severity: str          # "error" | "warn"
    message: str
    detail: str = ""

    def __str__(self) -> str:
        tail = f" — {self.detail}" if self.detail else ""
        return f"[{self.severity}] {self.rule}: {self.message}{tail}"


# --------------------------------------------------------------------------- #
# minimal DOM (parent pointers; enough for structural rules)                  #
# --------------------------------------------------------------------------- #

_VOID = {"area", "base", "br", "col", "embed", "hr", "img", "input", "link",
         "meta", "param", "source", "track", "wbr"}


@dataclass
class Node:
    tag: str
    attrs: dict
    parent: Node | None = None
    children: list = field(default_factory=list)

    @property
    def classes(self) -> set:
        return set((self.attrs.get("class") or "").split())


class _DOM(_hp.HTMLParser):
    def __init__(self):
        super().__init__(convert_charrefs=True)
        self.root = Node("#root", {})
        self._stack = [self.root]
        self.nodes: list[Node] = []

    def handle_starttag(self, tag, attrs):
        node = Node(tag, {k: (v or "") for k, v in attrs}, parent=self._stack[-1])
        self._stack[-1].children.append(node)
        self.nodes.append(node)
        if tag not in _VOID:
            self._stack.append(node)

    def handle_startendtag(self, tag, attrs):
        node = Node(tag, {k: (v or "") for k, v in attrs}, parent=self._stack[-1])
        self._stack[-1].children.append(node)
        self.nodes.append(node)

    def handle_endtag(self, tag):
        for i in range(len(self._stack) - 1, 0, -1):
            if self._stack[i].tag == tag:
                del self._stack[i:]
                break


def _parse(html: str) -> _DOM:
    dom = _DOM()
    dom.feed(html)
    return dom


def _ancestors(node: Node):
    p = node.parent
    while p is not None:
        yield p
        p = p.parent


# --------------------------------------------------------------------------- #
# rules                                                                       #
# --------------------------------------------------------------------------- #

def _is_fragment(html: str) -> bool:
    head = html.lstrip()[:200].lower()
    return not (head.startswith("<!doctype") or head.startswith("<html") or "<html" in head[:200])


def _rule_chrome_leak(html: str, dom: _DOM, fragment: bool, out: list):
    # SKILL.md output rule 1: body_html must never contain page chrome.
    # Only meaningful for fragments — a full artifact is *expected* to have it.
    if not fragment:
        return
    for node in dom.nodes:
        if node.tag in ("html", "head", "link"):
            out.append(Finding("chrome-leak", "error",
                               f"<{node.tag}> in body content",
                               "the composer supplies page chrome; body_html must not"))
        elif node.tag in ("style", "script"):
            out.append(Finding("chrome-leak", "warn",
                               f"top-level <{node.tag}> in body content",
                               "prefer extra_css / extra_js spec fields"))


def _defined_tokens(html: str, dom: _DOM) -> set:
    """Tokens legitimately available: base palette + --bind-* (created by
    data-bind hooks) + any custom --x declared in an author <style>."""
    defined = set(BASE_TOKENS)
    for m in re.finditer(r"data-bind\s*=\s*[\"']([a-z0-9_-]+)", html, re.IGNORECASE):
        defined.add("bind-" + m.group(1))
    # author-declared custom properties:  --foo:
    for m in re.finditer(r"(?<![a-z0-9-])--([a-z0-9-]+)\s*:", html, re.IGNORECASE):
        defined.add(m.group(1))
    return defined


def _rule_undefined_token(html: str, dom: _DOM, fragment: bool, out: list):
    defined = _defined_tokens(html, dom)
    seen = set()
    for m in _VAR_RE.finditer(html):
        name = m.group(1).lower()
        if name not in defined and name not in seen:
            seen.add(name)
            out.append(Finding("undefined-token", "error",
                               f"var(--{name}) references an undefined token",
                               "typo, or a token that isn't in the palette / not declared here"))


def _style_strings(dom: _DOM):
    for node in dom.nodes:
        st = node.attrs.get("style")
        if st:
            yield node, st


def _rule_hardcoded_color(html: str, dom: _DOM, fragment: bool, out: list):
    reported = 0
    for node, st in _style_strings(dom):
        if _HEX_RE.search(st) or _FUNC_COLOR_RE.search(st):
            reported += 1
            if reported <= 8:
                out.append(Finding("hardcoded-color", "warn",
                                   f"literal colour in style= on <{node.tag}>",
                                   "use a palette token, e.g. var(--clay), var(--g500)"))
    if reported > 8:
        out.append(Finding("hardcoded-color", "warn",
                           f"...and {reported - 8} more literal-colour style attributes"))


def _rule_inline_typography(html: str, dom: _DOM, fragment: bool, out: list):
    for node, st in _style_strings(dom):
        if _FONT_FAMILY_RE.search(st):
            out.append(Finding("inline-typography", "warn",
                               f"font-family in style= on <{node.tag}>",
                               "use the type stacks: var(--serif), var(--sans), var(--mono)"))
        if _FONT_SIZE_RE.search(st):
            out.append(Finding("inline-typography", "warn",
                               f"font-size in style= on <{node.tag}>",
                               "prefer the heading scale / existing type sizes"))


def _rule_nested_card(html: str, dom: _DOM, fragment: bool, out: list):
    for node in dom.nodes:
        if "card" in node.classes:
            if any("card" in a.classes for a in _ancestors(node)):
                out.append(Finding("nested-card", "warn",
                                   f"<{node.tag} class=card> nested inside another .card",
                                   "card-in-card; flatten or use a plain container"))


def _rule_broken_tabs(html: str, dom: _DOM, fragment: bool, out: list):
    targets = [(n, n.attrs.get("data-target")) for n in dom.nodes if n.attrs.get("data-target")]
    panel_ids = {n.attrs.get("data-id") for n in dom.nodes if "tab-panel" in n.classes}
    panel_ids.discard(None)
    target_vals = {t for _, t in targets}
    for node, t in targets:
        if t not in panel_ids:
            out.append(Finding("broken-tabs", "error",
                               f'data-target="{t}" has no matching .tab-panel[data-id="{t}"]',
                               "tab button wired to a missing panel"))
    for n in dom.nodes:
        if "tab-panel" in n.classes:
            pid = n.attrs.get("data-id")
            if pid and pid not in target_vals:
                out.append(Finding("broken-tabs", "warn",
                                   f'.tab-panel[data-id="{pid}"] has no button targeting it',
                                   "orphan panel — unreachable"))


def _rule_broken_bind(html: str, dom: _DOM, fragment: bool, out: list):
    binds = {n.attrs.get("data-bind") for n in dom.nodes if n.attrs.get("data-bind")}
    outs = {n.attrs.get("data-out") for n in dom.nodes if n.attrs.get("data-out")}
    var_binds = {m.group(1)[5:] for m in _VAR_RE.finditer(html)
                 if m.group(1).lower().startswith("bind-")}
    for b in binds:
        if b not in outs and b not in var_binds:
            out.append(Finding("broken-bind", "warn",
                               f'data-bind="{b}" has no consumer',
                               f'no [data-out="{b}"] and no var(--bind-{b})'))
    for o in outs:
        if o not in binds:
            out.append(Finding("broken-bind", "warn",
                               f'[data-out="{o}"] has no matching data-bind="{o}"',
                               "output element will never update"))


def _rule_broken_sortable(html: str, dom: _DOM, fragment: bool, out: list):
    for node in dom.nodes:
        if "data-sortable" in node.attrs:
            # descendants
            stack = list(node.children)
            has_draggable = False
            while stack:
                cur = stack.pop()
                if (cur.attrs.get("draggable") or "").lower() == "true":
                    has_draggable = True
                    break
                stack.extend(cur.children)
            if not has_draggable:
                out.append(Finding("broken-sortable", "warn",
                                   f"<{node.tag} data-sortable> has no draggable children",
                                   'add draggable="true" to the reorderable items'))


def _rule_heading_skip(html: str, dom: _DOM, fragment: bool, out: list):
    prev = None
    for node in dom.nodes:
        if len(node.tag) == 2 and node.tag[0] == "h" and node.tag[1].isdigit():
            lvl = int(node.tag[1])
            if prev is not None and lvl > prev + 1:
                out.append(Finding("heading-skip", "warn",
                                   f"heading jumps h{prev} -> h{lvl}",
                                   "don't skip heading levels"))
            prev = lvl


def _rule_img_no_alt(html: str, dom: _DOM, fragment: bool, out: list):
    for node in dom.nodes:
        if node.tag == "img" and "alt" not in node.attrs:
            out.append(Finding("img-no-alt", "warn",
                               "<img> without alt attribute",
                               'add alt="" (empty for decorative)'))


_RULES = [
    _rule_chrome_leak,
    _rule_undefined_token,
    _rule_hardcoded_color,
    _rule_inline_typography,
    _rule_nested_card,
    _rule_broken_tabs,
    _rule_broken_bind,
    _rule_broken_sortable,
    _rule_heading_skip,
    _rule_img_no_alt,
]


# --------------------------------------------------------------------------- #
# public                                                                      #
# --------------------------------------------------------------------------- #

def check_html(html: str, *, fragment: bool | None = None) -> list[Finding]:
    if fragment is None:
        fragment = _is_fragment(html)
    dom = _parse(html)
    out: list[Finding] = []
    for rule in _RULES:
        rule(html, dom, fragment, out)
    return out


def format_findings(findings: list[Finding]) -> str:
    if not findings:
        return "OK — no findings."
    errs = sum(1 for f in findings if f.severity == "error")
    warns = sum(1 for f in findings if f.severity == "warn")
    lines = [str(f) for f in findings]
    lines.append(f"\n{errs} error(s), {warns} warning(s).")
    return "\n".join(lines)


def has_errors(findings: list[Finding]) -> bool:
    return any(f.severity == "error" for f in findings)

"""composing-html / composer.py

Page shell + primitive helpers shared by every template module.

Templates receive a structured spec (a dict) and return a single HTML string
that goes into <body>. The composer wraps it with <head>, inlines base.css /
base.js. If a caller passes `colophon=`, adds a colophon footer. Templates never write <html>, <head>,
<style>, <script>, or <link>.

Helpers provided here are deliberately small. Each takes plain Python data
(strings, dicts, lists) and returns an HTML string. Nothing fancy — keep the
output readable when someone opens the file in DevTools.
"""

from __future__ import annotations

import html
import json
import re
from collections.abc import Iterable
from pathlib import Path
from typing import Any

ASSETS = Path(__file__).resolve().parent.parent / "assets"


# --------------------------------------------------------------------------- #
# escaping                                                                    #
# --------------------------------------------------------------------------- #

def esc(value: Any) -> str:
    """Escape for text content. Lists are joined with spaces. None → ''."""
    if value is None:
        return ""
    if isinstance(value, (list, tuple)):
        return " ".join(esc(v) for v in value)
    return html.escape(str(value), quote=True)


def attrs(mapping: dict | None) -> str:
    """Render a dict of attributes. Drops None / False; True → bare attr.

    Keys with underscores are translated to hyphens so Python kwargs like
    ``data_target`` become ``data-target``.
    """
    if not mapping:
        return ""
    parts = []
    for k, v in mapping.items():
        if v is None or v is False:
            continue
        key = k.replace("_", "-")
        if v is True:
            parts.append(key)
        else:
            parts.append(f'{key}="{html.escape(str(v), quote=True)}"')
    return (" " + " ".join(parts)) if parts else ""


# --------------------------------------------------------------------------- #
# primitives                                                                  #
# --------------------------------------------------------------------------- #

def tag(name: str, inner: str = "", **attributes: Any) -> str:
    return f"<{name}{attrs(attributes)}>{inner}</{name}>"


def void(name: str, **attributes: Any) -> str:
    return f"<{name}{attrs(attributes)}>"


def eyebrow(text: str) -> str:
    return f'<div class="eyebrow">{esc(text)}</div>' if text else ""


def badge(label: str, kind: str | None = None) -> str:
    cls = "badge" + (f" badge--{kind}" if kind else "")
    return f'<span class="{cls}">{esc(label)}</span>'


def kbd(key: str) -> str:
    return f'<span class="kbd">{esc(key)}</span>'


def code_block(source: str, lang: str | None = None) -> str:
    cls = f' class="lang-{esc(lang)}"' if lang else ""
    return f'<pre><code{cls}>{esc(source)}</code></pre>'


def inline_code(source: str) -> str:
    return f"<code>{esc(source)}</code>"


def section(title: str | None = None, body: str = "", id: str | None = None,
            wide: bool = False) -> str:
    head = ""
    if title:
        head = f'<h2>{esc(title)}</h2><hr class="rule">'
    sec_attrs = attrs({"id": id, "class": "wide" if wide else None})
    return f"<section{sec_attrs}>{head}{body}</section>"


def card(body: str, title: str | None = None, *, soft: bool = False,
         elev: bool = False, extra_class: str = "") -> str:
    classes = ["card"]
    if soft: classes.append("card--soft")
    if elev: classes.append("card--elev")
    if extra_class: classes.append(extra_class)
    head = f"<h3>{esc(title)}</h3>" if title else ""
    return f'<div class="{" ".join(classes)}">{head}{body}</div>'


def grid(items: Iterable[str], cols: int | str = "auto", gap: int = 20) -> str:
    cls = f"grid grid--{cols}"
    style = f"gap:{gap}px;"
    return f'<div class="{cls}" style="{style}">{"".join(items)}</div>'


def stack(items: Iterable[str], gap: int = 16) -> str:
    return f'<div class="stack" style="gap:{gap}px;">{"".join(items)}</div>'


def row(items: Iterable[str], gap: int = 12) -> str:
    return f'<div class="row" style="gap:{gap}px;">{"".join(items)}</div>'


def bullets(items: Iterable[str]) -> str:
    return '<ul class="bullets">' + "".join(f"<li>{esc(i)}</li>" for i in items) + "</ul>"


def kv_list(pairs: dict[str, Any]) -> str:
    """Definition-list-style key/value rendering."""
    rows = "".join(
        f'<div style="display:flex;gap:12px;padding:8px 0;border-bottom:1px solid var(--g150);">'
        f'<div style="font-family:var(--mono);font-size:12px;color:var(--g500);min-width:140px;">{esc(k)}</div>'
        f'<div>{esc(v)}</div></div>'
        for k, v in pairs.items()
    )
    return f'<div>{rows}</div>'


def raw(html_string: str) -> _Raw:
    """Wrap a string to opt out of HTML escaping in `table` and `callout` cells.

    Use this when a cell genuinely needs to contain HTML markup the caller
    constructed (e.g. a `badge()` result). Plain strings are always escaped.
    """
    return _Raw(html_string)


class _Raw(str):
    """Marker subclass for opt-in raw HTML in cells. Treated as str everywhere
    except composer functions that switch on `isinstance(x, _Raw)`."""
    __slots__ = ()


def _cell(value: Any) -> str:
    return str(value) if isinstance(value, _Raw) else esc(value)


def table(columns: list[str], rows: list[list[Any]]) -> str:
    head = "<thead><tr>" + "".join(f"<th>{esc(c)}</th>" for c in columns) + "</tr></thead>"
    body = "<tbody>" + "".join(
        "<tr>" + "".join(f"<td>{_cell(cell)}</td>" for cell in r) + "</tr>"
        for r in rows
    ) + "</tbody>"
    return f"<table>{head}{body}</table>"


def details(summary: str, body: str, *, open: bool = False) -> str:
    return f'<details{" open" if open else ""}><summary>{esc(summary)}</summary>{body}</details>'


def tabs(panels: list[dict[str, Any]]) -> str:
    """panels: [{id, label, html}]"""
    btns = "".join(f'<button data-target="{esc(p["id"])}">{esc(p["label"])}</button>' for p in panels)
    body = "".join(f'<div class="tab-panel" data-id="{esc(p["id"])}">{p["html"]}</div>' for p in panels)
    return f'<div class="tabgroup"><div class="tabs">{btns}</div>{body}</div>'


def callout(text: Any, kind: str = "info", icon: str | None = None) -> str:
    """Render an info/ok/warn/err callout box. Pass `raw(html)` to opt out of escaping."""
    color = {"info": "var(--info)", "ok": "var(--ok)", "warn": "var(--warn)", "err": "var(--err)"}.get(kind, "var(--info)")
    bg    = {"info": "#DCE7EE", "ok": "#E8EFE0", "warn": "#F8ECCB", "err": "#F4DAD5"}.get(kind, "#DCE7EE")
    icon_html = f'<span style="font-weight:700;">{esc(icon)}</span>' if icon else ""
    return (f'<div style="border-left:3px solid {color};background:{bg};padding:12px 16px;'
            f'border-radius:0 var(--radius-sm) var(--radius-sm) 0;display:flex;gap:10px;align-items:flex-start;">'
            f'{icon_html}<div>{_cell(text)}</div></div>')


# --------------------------------------------------------------------------- #
# page shell                                                                  #
# --------------------------------------------------------------------------- #

def page(*, title: str, body: str,
         subtitle: str | None = None,
         eyebrow_text: str | None = None,
         page_class: str = "page",
         body_attrs: dict | None = None,
         extra_css: str = "",
         extra_js: str = "",
         show_masthead: bool = True,
         colophon: str | None = None) -> str:
    """Wrap inner body html with the full page shell.

    Inlines base.css and base.js so the artifact is a single, portable file.
    Templates can pass extra_css / extra_js for one-off rules.
    """
    base_css = (ASSETS / "base.css").read_text(encoding="utf-8")
    base_js  = (ASSETS / "base.js").read_text(encoding="utf-8")

    masthead_html = ""
    if show_masthead and (title or subtitle or eyebrow_text):
        parts = []
        if eyebrow_text:
            parts.append(f'<div class="eyebrow">{esc(eyebrow_text)}</div>')
        if title:
            parts.append(f'<h1>{esc(title)}</h1>')
        if subtitle:
            parts.append(f'<p class="subtitle">{esc(subtitle)}</p>')
        masthead_html = f'<header class="masthead">{"".join(parts)}</header>'

    colo_html = (f'<div class="colophon"><span>{esc(colophon)}</span>'
                 f'<span></span></div>') if colophon else ""

    body_attr_str = attrs(body_attrs)

    return (
        "<!doctype html>\n"
        '<html lang="en">\n'
        '<head>\n'
        '<meta charset="utf-8">\n'
        '<meta name="viewport" content="width=device-width,initial-scale=1">\n'
        f'<title>{esc(title or "Untitled")}</title>\n'
        '<style>\n' + base_css + '\n'
        + (extra_css and ("\n/* template extras */\n" + extra_css + "\n") or "") +
        '</style>\n'
        '</head>\n'
        f'<body{body_attr_str}>\n'
        f'<main class="{page_class}">'
        f'{masthead_html}'
        f'{body}'
        f'{colo_html}'
        f'</main>\n'
        '<script>\n' + base_js + '\n'
        + (extra_js and ("\n/* template extras */\n" + extra_js + "\n") or "") +
        '</script>\n'
        '</body>\n'
        '</html>\n'
    )


# --------------------------------------------------------------------------- #
# helpers                                                                     #
# --------------------------------------------------------------------------- #

_CSS_COLOR_RE = re.compile(
    r"^("
    r"#[0-9a-fA-F]{3,8}"                  # hex
    r"|rgba?\([^)]+\)"                    # rgb / rgba
    r"|hsla?\([^)]+\)"                    # hsl / hsla
    r"|var\(--[a-zA-Z0-9_-]+(?:\s*,\s*[#a-zA-Z0-9.,()% _-]+)?\)"  # var(--token[, fallback])
    r"|[a-zA-Z]{3,30}"                    # named: 'red', 'transparent', 'currentColor'
    r")$"
)


def css_color(value: Any, default: str = "var(--g500)") -> str:
    """Whitelist a CSS color value. Anything that doesn't look like a color
    falls back to `default`. Use this for any color taken from a spec field."""
    if not isinstance(value, str):
        return default
    v = value.strip()
    return v if _CSS_COLOR_RE.match(v) else default


def slug(text: str) -> str:
    s = re.sub(r"[^a-zA-Z0-9]+", "-", str(text)).strip("-").lower()
    return s or "x"


def json_dump(obj: Any) -> str:
    return json.dumps(obj, ensure_ascii=False, indent=2)

"""Tests for composing-html's deterministic checker.

Run with:  python composing-html/tests/test_checker.py    (no pytest needed)
       or  python -m pytest composing-html/tests -q
"""

from __future__ import annotations

import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(ROOT / "scripts"))

from checker import check_html, has_errors


def _rules(html, **kw):
    return {f.rule for f in check_html(html, **kw)}


_PASS = 0
_FAIL = 0


def ok(cond, label):
    global _PASS, _FAIL
    if cond:
        _PASS += 1
    else:
        _FAIL += 1
        print(f"  FAIL: {label}")


# --- clean fragment: no findings ------------------------------------------- #
clean = """
<section>
  <div class="eyebrow">OVERVIEW</div>
  <h2>Status</h2>
  <div class="grid grid--2">
    <div class="card"><p style="color: var(--clay)">All good</p></div>
    <div class="card"><span class="badge badge--ok">v1</span></div>
  </div>
  <img src="x.png" alt="diagram">
</section>
"""
ok(_rules(clean, fragment=True) == set(), "clean fragment yields no findings")
ok(not has_errors(check_html(clean, fragment=True)), "clean fragment has no errors")

# --- chrome leak (fragment only) ------------------------------------------- #
ok("chrome-leak" in _rules('<head><link rel="x"></head><p>hi</p>', fragment=True),
   "chrome-leak fires on <head>/<link> in fragment")
ok("chrome-leak" not in _rules('<!doctype html><html><head></head><body>x</body></html>'),
   "chrome-leak silent on a full artifact")

# --- undefined token ------------------------------------------------------- #
ok("undefined-token" in _rules('<p style="color: var(--cley)">typo</p>', fragment=True),
   "undefined-token catches var(--cley) typo")
ok("undefined-token" not in _rules('<p style="color: var(--clay)">ok</p>', fragment=True),
   "undefined-token silent on valid token")
ok("undefined-token" not in _rules(
       '<input data-bind="size"><span style="width: var(--bind-size)"></span>', fragment=True),
   "undefined-token silent on --bind-* created by data-bind")
ok("undefined-token" not in _rules(
       '<div style="--mytok: 4px; padding: var(--mytok)"></div>', fragment=True),
   "undefined-token silent on author-declared custom property")

# --- hardcoded colour ------------------------------------------------------ #
ok("hardcoded-color" in _rules('<p style="color:#ff0000">red</p>', fragment=True),
   "hardcoded-color catches hex literal")
ok("hardcoded-color" in _rules('<p style="background: rgb(1,2,3)">x</p>', fragment=True),
   "hardcoded-color catches rgb()")

# --- inline typography ----------------------------------------------------- #
ok("inline-typography" in _rules('<p style="font-family: Inter">x</p>', fragment=True),
   "inline-typography catches font-family")
ok("inline-typography" in _rules('<p style="font-size: 22px">x</p>', fragment=True),
   "inline-typography catches font-size")

# --- nested card ----------------------------------------------------------- #
ok("nested-card" in _rules('<div class="card"><div class="card">x</div></div>', fragment=True),
   "nested-card catches card-in-card")
ok("nested-card" not in _rules('<div class="card">x</div><div class="card">y</div>', fragment=True),
   "nested-card silent on sibling cards")
ok("nested-card" not in _rules('<div class="scorecard"><div class="card">x</div></div>', fragment=True),
   "nested-card does not match substring 'scorecard'")

# --- broken tabs ----------------------------------------------------------- #
broken_tabs = '<div class="tabs"><button data-target="a">A</button></div>'
ok("broken-tabs" in _rules(broken_tabs, fragment=True),
   "broken-tabs catches target with no panel")
good_tabs = ('<div class="tabs"><button data-target="a">A</button></div>'
             '<div class="tab-panel" data-id="a">x</div>')
ok("broken-tabs" not in _rules(good_tabs, fragment=True),
   "broken-tabs silent on wired tabs")

# --- broken bind ----------------------------------------------------------- #
ok("broken-bind" in _rules('<input data-bind="size">', fragment=True),
   "broken-bind catches bind with no consumer")
ok("broken-bind" in _rules('<span data-out="ghost"></span>', fragment=True),
   "broken-bind catches orphan data-out")

# --- broken sortable ------------------------------------------------------- #
ok("broken-sortable" in _rules('<div data-sortable="true"><div>x</div></div>', fragment=True),
   "broken-sortable catches no draggable children")
ok("broken-sortable" not in _rules(
       '<div data-sortable="true"><div draggable="true">x</div></div>', fragment=True),
   "broken-sortable silent when draggable present")

# --- heading skip ---------------------------------------------------------- #
ok("heading-skip" in _rules('<h1>a</h1><h3>b</h3>', fragment=True),
   "heading-skip catches h1->h3")
ok("heading-skip" not in _rules('<h1>a</h1><h2>b</h2><h3>c</h3>', fragment=True),
   "heading-skip silent on proper nesting")

# --- img no alt ------------------------------------------------------------ #
ok("img-no-alt" in _rules('<img src="x.png">', fragment=True),
   "img-no-alt catches missing alt")
ok("img-no-alt" not in _rules('<img src="x.png" alt="">', fragment=True),
   "img-no-alt silent on empty alt")

# --- severity contract ----------------------------------------------------- #
ok(has_errors(check_html('<p style="color: var(--nope)">x</p>', fragment=True)),
   "undefined-token is error severity")
ok(not has_errors(check_html('<img src=x>', fragment=True)),
   "img-no-alt alone is not error severity")


print(f"\n{_PASS} passed, {_FAIL} failed")
sys.exit(1 if _FAIL else 0)

"""Smoke + regression tests for composing-html.

Run with:  python -m pytest composing-html/tests -q
        or python composing-html/tests/test_smoke.py        (no pytest needed)

Covers every template builder with a representative spec, then asserts each
output:
  - starts with `<!doctype html>`
  - parses cleanly with html.parser
  - contains the expected content marker
  - does NOT contain raw `<script>alert` or `<img onerror=` injections from
    spec-side strings (regression for the deleted `_looks_like_html` heuristic)
"""

from __future__ import annotations

import html.parser as hp
import json
import sys
import types
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(ROOT / "scripts"))

from composer import callout, css_color, page, raw, table

from templates import REGISTRY

# --------------------------------------------------------------------------- #
# helpers                                                                     #
# --------------------------------------------------------------------------- #

def _parses(html_str: str) -> bool:
    try:
        hp.HTMLParser().feed(html_str); return True
    except Exception:
        return False


def _build(name: str, spec: dict) -> str:
    assert name in REGISTRY, f"template {name!r} not registered"
    return page(**REGISTRY[name]["build"](spec))


# --------------------------------------------------------------------------- #
# representative specs (exercise the interesting branches of each template)   #
# --------------------------------------------------------------------------- #

SPECS: dict[str, dict] = {
    "freeform": {
        "title": "ff", "body_html": "<section><h2>Hi</h2><p>x</p></section>",
    },
    "exploration.comparison_grid": {
        "title": "Compare", "recommendation": "A",
        "options": [
            {"name": "A", "verdict": "best", "summary": "s",
             "pros": ["p1"], "cons": ["c1"], "tags": ["t"]},
            {"name": "B", "summary": "s2"},
        ],
    },
    "exploration.design_directions": {
        "title": "Dir",
        "directions": [
            {"name": "D1", "vibe": "v", "palette": ["#FAF9F5", "#D97757"],
             "typography": {"display": "Aa", "body": "x"}, "notes": "n"},
        ],
    },
    "exploration.implementation_plan": {
        "title": "Plan", "data_flow": ["A", "B"],
        "milestones": [
            {"name": "m", "when": "wk1", "owner": "alex",
             "status": "active", "deliverables": ["d"]}],
        "risks": [{"risk": "r", "likelihood": "med", "impact": "high",
                   "mitigation": "m"}],
    },
    "review.pr_review": {
        "title": "PR", "pr": {"repo": "r", "number": 1, "branch": "b",
                              "author": "a", "additions": 1, "deletions": 1},
        "verdict": "approve", "summary_html": "<p>s</p>",
        "findings": [{"file": "x.py", "line": 1, "severity": "warn",
                      "title": "t", "body_html": "<p>b</p>",
                      "snippet": "x = 1", "snippet_lang": "python"}],
    },
    "review.code_walkthrough": {
        "title": "Walk",
        "steps": [{"heading": "h", "body_html": "<p>b</p>", "code": "x=1", "lang": "python"}],
    },
    "review.module_map": {
        "title": "Map",
        "nodes": [{"id": "a", "label": "A", "kind": "core"},
                  {"id": "b", "label": "B", "kind": "util"}],
        "edges": [{"from": "a", "to": "b", "label": "calls"}],
        "legend": [{"label": "core", "kind": "core"}],
    },
    "design.design_system": {
        "title": "DS",
        "colors": {"Brand": [{"name": "Clay", "hex": "#D97757", "token": "--clay"}]},
        "typography": [{"name": "Body", "font_family": "var(--sans)", "size": "16px", "weight": "400"}],
        "spacing": [{"name": "sm", "px": 8}],
        "radii": [{"name": "sm", "px": 4}],
    },
    "design.component_variants": {
        "title": "CV",
        "components": [{
            "name": "Button",
            "axes": {"Size": ["sm", "md"], "Intent": ["primary"]},
            "cells": [{"coords": {"Size": "sm", "Intent": "primary"}, "html": "<button>x</button>"}],
        }],
    },
    "prototype.animation_sandbox": {
        "title": "Sandbox",
        "params": [{"name": "d", "label": "Dur", "type": "range",
                    "min": 0, "max": 1000, "default": 300, "unit": "ms"}],
        "preview_html": "<div></div>",
    },
    "prototype.click_flow": {
        "title": "Flow",
        "screens": [
            {"id": "a", "label": "A", "html": "<p>A</p>",
             "transitions": [{"label": "→", "to_id": "b"}]},
            {"id": "b", "label": "B", "html": "<p>B</p>"},
        ],
    },
    "diagram.svg_figure_sheet": {
        "title": "Figs",
        "figures": [{"label": "F1", "caption": "c",
                     "svg": "<svg viewBox='0 0 10 10'><rect width='10' height='10'/></svg>"}],
    },
    "diagram.flowchart": {
        "title": "Flow", "orientation": "vertical",
        "steps": [{"id": "s1", "label": "Start", "kind": "start"},
                  {"id": "s2", "label": "End",   "kind": "end"}],
    },
    "deck.slide_deck": {
        "title": "Deck",
        "slides": [{"kind": "title", "title": "T"},
                   {"kind": "content", "title": "C", "body_html": "<p>x</p>"}],
    },
    "research.feature_explainer": {
        "title": "Feat",
        "sections": [{"id": "a", "heading": "A", "body_html": "<p>x</p>",
                      "code_tabs": [{"label": "py", "code": "x=1", "lang": "python"}]}],
    },
    "research.concept_explainer": {
        "title": "Concept", "body_html": "<p>x</p>",
        "glossary": [{"term": "t", "definition_html": "<code>v</code>"}],
    },
    "report.status_report": {
        "title": "Status",
        "metrics": [{"label": "X", "value": "1", "delta": "+1", "kind": "ok"}],
        "shipped": [{"title": "s", "owner": "o"}],
        "in_flight": [{"title": "i", "progress": 0.5}],
        "blocked": [{"title": "b"}],
    },
    "report.incident_report": {
        "title": "INC", "severity": "sev2", "duration": "30m",
        "impact_html": "<p>i</p>", "summary_html": "<p>s</p>",
        "timeline": [{"at": "14:00", "event": "e", "kind": "detected"}],
        "root_cause_html": "<p>rc</p>",
        "followups": [{"title": "f", "owner": "o", "due": "d", "status": "open"}],
    },
    "editor.triage_board": {
        "title": "Board",
        "columns": [{"id": "todo", "label": "Todo", "color": "info",
                     "items": [{"id": "i1", "title": "x", "tags": ["P1"]}]}],
    },
    "editor.flag_editor": {
        "title": "Flags",
        "flags": [{"id": "a", "label": "A", "default": True},
                  {"id": "b", "label": "B", "default": False, "requires": ["a"]}],
    },
    "editor.prompt_tuner": {
        "title": "Tuner", "template": "Hi {{name}}",
        "variables": [{"name": "name", "default": "x"}],
    },
}


# --------------------------------------------------------------------------- #
# tests                                                                       #
# --------------------------------------------------------------------------- #

def test_every_template_has_a_spec():
    missing = sorted(set(REGISTRY) - set(SPECS))
    assert not missing, f"specs missing for: {missing}"


def test_every_template_renders_and_parses():
    failures = []
    for name, spec in SPECS.items():
        try:
            html = _build(name, spec)
            assert html.startswith("<!doctype html>"), f"{name}: no doctype"
            assert "</html>" in html, f"{name}: no </html>"
            assert _parses(html), f"{name}: parser raised"
        except Exception as e:
            failures.append((name, str(e)))
    assert not failures, "\n".join(f"{n}: {e}" for n, e in failures)


# --- security regressions ------------------------------------------------- #

INJECT = "<script>alert(1)</script><img src=x onerror=alert(1)>"


def test_table_does_not_emit_raw_script():
    out = table(["x"], [[INJECT]])
    assert "<script>" not in out
    assert "&lt;script&gt;" in out


def test_callout_escapes_plain_strings():
    out = callout(INJECT)
    assert "<script>" not in out
    assert "&lt;script&gt;" in out


def test_table_raw_opt_in_works():
    out = table(["x"], [[raw("<b>ok</b>")]])
    assert "<b>ok</b>" in out


def test_implementation_plan_owner_attr_is_quoted():
    out = _build("exploration.implementation_plan", {
        "title": "p",
        "milestones": [{"name": "m", "when": "wk1", "owner": "alex",
                        "deliverables": ["d"]}],
    })
    # Owner div must use a quoted style attribute, not `style=font-...`.
    assert 'style="font-family:var(--mono)' in out
    assert 'style=font-family' not in out


def test_prompt_tuner_defends_against_script_breakout():
    out = _build("editor.prompt_tuner", {
        "title": "x",
        "template": "before </script><img src=x onerror=alert(1)> after",
        "variables": [{"name": "x", "default": ""}],
    })
    # Inside the inlined JS string literal, </ must be escaped to <\/.
    # The plain literal `</script>` must not appear except as the closing tag
    # of the actual <script> we emit ourselves.
    closing_tags = out.count("</script>")
    assert closing_tags == 1, (
        f"expected exactly one </script> (the real closer); found {closing_tags}"
    )


def test_flag_editor_escapes_id_in_attrs():
    out = _build("editor.flag_editor", {
        "title": "f",
        "flags": [{"id": 'a"b', "label": "L", "default": True,
                   "requires": ['x"y']}],
    })
    # The injected " must be HTML-escaped inside both the data-id and
    # data-requires attributes; the surrounding attribute uses double quotes.
    assert 'data-id="a&quot;b"' in out
    assert "&quot;" in out  # JSON " inside data-requires is escaped


def test_flag_editor_handles_missing_id():
    out = _build("editor.flag_editor", {
        "title": "f",
        "flags": [{"label": "no-id", "default": False}],
    })
    assert "</html>" in out  # no KeyError


def test_module_map_does_not_mutate_spec():
    spec = {"nodes": [{"id": "a", "label": "A"}, {"id": "b", "label": "B"}],
            "edges": [{"from": "a", "to": "b"}]}
    snap = json.dumps(spec, sort_keys=True)
    _build("review.module_map", spec)
    assert json.dumps(spec, sort_keys=True) == snap, (
        "module_map mutated the caller's spec — nodes still hold injected x/y"
    )


def test_module_map_warns_on_unknown_edge(capsys):
    spec = {"nodes": [{"id": "a", "label": "A"}],
            "edges": [{"from": "a", "to": "missing"}]}
    _build("review.module_map", spec)
    err = capsys.readouterr().err
    assert "unknown id" in err or "missing" in err


def test_slide_deck_raises_on_unknown_kind():
    try:
        _build("deck.slide_deck", {"slides": [{"kind": "contant", "title": "x"}]})
    except ValueError as e:
        assert "unknown slide kind" in str(e)
    else:
        raise AssertionError("expected ValueError")


def test_css_color_rejects_injection():
    assert css_color("#D97757") == "#D97757"
    assert css_color("var(--clay)") == "var(--clay)"
    assert css_color("rgb(217,119,87)") == "rgb(217,119,87)"
    assert css_color("red;background-image:url(http://x)") != "red;background-image:url(http://x)"
    assert css_color("javascript:alert(1)") != "javascript:alert(1)"
    assert css_color("transparent") == "transparent"


def test_describe_emits_valid_json():
    """Regression for #8 — the printed skeleton must round-trip via json.loads."""
    import contextlib
    import io
    import re

    import build as _build_mod

    class _Args:
        pass
    for name in REGISTRY:
        a = _Args(); a.template = name
        buf = io.StringIO()
        with contextlib.redirect_stdout(buf):
            _build_mod.cmd_describe(a)
        out = buf.getvalue()
        m = re.search(r"```json\n(.*?)\n```", out, re.DOTALL)
        assert m, f"{name}: no JSON block in describe output"
        json.loads(m.group(1))  # raises if invalid


# --------------------------------------------------------------------------- #
# --set CLI override behavior                                                 #
# --------------------------------------------------------------------------- #

def test_apply_set_inline_value():
    from build import _apply_set
    spec = {}
    rc = _apply_set(spec, ["title=Hello", "subtitle=World"])
    assert rc == 0
    assert spec == {"title": "Hello", "subtitle": "World"}


def test_apply_set_preserves_equals_in_value():
    """KEY=VALUE uses str.partition('='), so '=' inside the value survives."""
    from build import _apply_set
    spec = {}
    rc = _apply_set(spec, ["extra_css=.x { content: 'a=b'; }"])
    assert rc == 0
    assert spec["extra_css"] == ".x { content: 'a=b'; }"


def test_apply_set_loads_file_with_at_prefix():
    """KEY=@FILE loads the file's raw contents — newlines, quotes, all OK."""
    import tempfile

    from build import _apply_set
    with tempfile.TemporaryDirectory() as td:
        p = Path(td) / "body.html"
        body = '<section>\n  "multi-line" & <em>special</em> content\n</section>'
        p.write_text(body, encoding="utf-8")
        spec = {}
        rc = _apply_set(spec, [f"body_html=@{p}"])
        assert rc == 0
        assert spec["body_html"] == body
        # The whole point: content can include newlines and quotes that
        # would otherwise need careful JSON-string escaping.
        assert "\n" in spec["body_html"]
        assert '"' in spec["body_html"]


def test_apply_set_overrides_existing_field():
    from build import _apply_set
    spec = {"title": "from-json", "extra_css": "/* old */"}
    rc = _apply_set(spec, ["title=from-set"])
    assert rc == 0
    assert spec == {"title": "from-set", "extra_css": "/* old */"}


def test_apply_set_rejects_bad_syntax():
    from build import _apply_set
    spec = {}
    rc = _apply_set(spec, ["no_equals_sign"])
    assert rc == 2
    rc = _apply_set({}, ["=missing-key"])
    assert rc == 2


def test_apply_set_rejects_missing_file():
    from build import _apply_set
    spec = {}
    rc = _apply_set(spec, ["body_html=@/tmp/definitely-does-not-exist-xyz.html"])
    assert rc == 2


def test_cli_build_with_only_set_and_no_spec():
    """End-to-end: --set alone (no --spec) renders a valid page."""
    import subprocess
    import tempfile
    cli = ROOT / "scripts" / "build.py"
    with tempfile.TemporaryDirectory() as td:
        body = Path(td) / "body.html"
        body.write_text(
            '<section><h2>Multi-line</h2>\n<p>Has "quotes" & <em>tags</em>.</p></section>',
            encoding="utf-8",
        )
        out = Path(td) / "out.html"
        result = subprocess.run(
            [sys.executable, str(cli), "build", "freeform",
             "--set", "title=No-spec demo",
             "--set", f"body_html=@{body}",
             "--out", str(out)],
            capture_output=True, text=True,
        )
        assert result.returncode == 0, f"CLI failed: {result.stderr}"
        rendered = out.read_text(encoding="utf-8")
        assert "<!doctype html>" in rendered.lower()
        assert "Multi-line" in rendered
        assert '"quotes"' in rendered
        assert "No-spec demo" in rendered  # title made it through


def test_cli_build_set_overrides_spec_file():
    """When --spec and --set both supply the same key, --set wins."""
    import subprocess
    import tempfile
    cli = ROOT / "scripts" / "build.py"
    with tempfile.TemporaryDirectory() as td:
        spec = Path(td) / "spec.json"
        spec.write_text(
            json.dumps({"title": "from-spec", "body_html": "<p>spec body</p>"}),
            encoding="utf-8",
        )
        body = Path(td) / "body.html"
        body.write_text("<p>set body wins</p>", encoding="utf-8")
        out = Path(td) / "out.html"
        result = subprocess.run(
            [sys.executable, str(cli), "build", "freeform",
             "--spec", str(spec),
             "--set", f"body_html=@{body}",
             "--out", str(out)],
            capture_output=True, text=True,
        )
        assert result.returncode == 0, f"CLI failed: {result.stderr}"
        rendered = out.read_text(encoding="utf-8")
        assert "set body wins" in rendered
        assert "spec body" not in rendered
        assert "from-spec" in rendered  # title from spec was kept


# --------------------------------------------------------------------------- #
# direct entrypoint                                                           #
# --------------------------------------------------------------------------- #

def _run_directly() -> int:
    """Plain runner so the suite works without pytest installed."""
    failed = 0
    fns = [v for k, v in globals().items() if k.startswith("test_") and isinstance(v, types.FunctionType)]
    for fn in fns:
        # Stub `capsys` for the one test that uses it.
        import io
        import sys as _sys
        if "capsys" in fn.__code__.co_varnames:
            buf_err = io.StringIO()
            old_err = _sys.stderr
            _sys.stderr = buf_err
            try:
                class _CS:  # minimal capsys stand-in
                    def readouterr(self_inner, _buf=buf_err):
                        return types.SimpleNamespace(out="", err=_buf.getvalue())
                fn(_CS())
                print(f"  ✓ {fn.__name__}")
            except AssertionError as e:
                failed += 1; print(f"  ✗ {fn.__name__}: {e}")
            finally:
                _sys.stderr = old_err
        else:
            try:
                fn(); print(f"  ✓ {fn.__name__}")
            except AssertionError as e:
                failed += 1; print(f"  ✗ {fn.__name__}: {e}")
            except Exception as e:
                failed += 1; print(f"  ✗ {fn.__name__}: {type(e).__name__}: {e}")
    print(f"\n{len(fns) - failed}/{len(fns)} passed")
    return 1 if failed else 0


if __name__ == "__main__":
    raise SystemExit(_run_directly())