# v0.7.1a — Tiny Template Engine (the 3 primitives)

**Owner**: VibeCoder thread (412100071272671) — spec + bridge filter registry
**Owner**: Oscar Website thread (415655444668635) — template parser + render
**Target**: ~1-2h, ship this week (2026-07-29 → 2026-08-01)
**Follow-up**: v0.7.1b (next week) = filter registry UI + visual schema inspector

## Why

v0.7.0 ships with a `String.replace` hack to fill widget templates ("Post title" → rec.title). It works but it can't:
- Pipe values through filters (dates, markdown, truncation)
- Iterate over list fields (gallery, tags, related items)
- Handle missing fields gracefully
- Let operators write reusable templates

The 3 primitives below unlock dynamic content without building a full visual editor (that's v0.7.1b).

## The 3 primitives

### 1. `{{field}}` — value substitution

```html
<h2>{{title}}</h2>
<p class="author">By {{author}}</p>
```

Substitutes the field's value. If the field is missing, the spec decides (see Open Questions).

### 2. `{{field | filter}}` — pipe through a filter

```html
<p>Published {{published_at | date("%B %d, %Y")}}</p>
<div class="body">{{body | markdown | truncate(280)}}</div>
<img src="{{cover_image | default('/img/fallback.png')}}" />
```

Pipes the value through one or more named filters. Filters are a flat registry served by the bridge. v0.7.1a ships with a small starter set (see below); v0.7.1b adds the UI to discover/chain them.

**Date format syntax** (Q5, locked): **strftime subset**. Operators know it from Python/Unix. Supports:
- `%Y` 4-digit year, `%y` 2-digit
- `%m` month (01-12), `%B` full month name, `%b` short month name
- `%d` day of month (01-31), `%e` day without leading zero
- `%H` hour 24h, `%M` minute, `%S` second
- `%A` full weekday, `%a` short weekday
- `%Z` timezone name, `%z` UTC offset

Examples: `"%Y-%m-%d"`, `"%B %d, %Y"`, `"%H:%M"`. No external dep. v0.7.1b can swap in moment.js if operators need locale support.

**Starter filter set** (v0.7.1a):
- `date(format)` — formats an ISO date string with strftime subset (see above)
- `markdown` — renders a markdown string to safe HTML. Uses a tiny parser (no CommonMark, just enough for the common cases: headings, bold, italic, links, code, lists, paragraphs).
- `truncate(n)` — truncates a string to `n` characters, appending `…` if cut.
- `default(value)` — returns `value` if the field is missing/null/empty.
- `upper`, `lower`, `capitalize` — string case.
- `safe` — marks a string as safe HTML (no escaping). Operators opt into this when they trust the field.
- `json` — stringifies an object as JSON. For debug fields.

**Syntax** (single `|`, no `|` inside filter args):
- `{{field | filter}}` — no args
- `{{field | filter("arg")}}` — single string arg
- `{{field | filter(42)}}` — single number arg
- `{{field | filter("arg1", "arg2")}}` — multiple args

No nested expressions in v0.7.1a. v0.7.1b can add `{{field | filter(otherField)}}` if needed.

### 3. `{{#each items}}...{{/each}}` — list iteration

```html
<ul class="tags">
  {{#each tags}}
    <li>{{this}}</li>
  {{/each}}
</ul>
```

Iterates over a list field. Inside the block, `{{this}}` is the current item (use `{{this.field}}` for object items). The block renders once per item.

For object lists (e.g. `{{#each related_posts}}`):
```html
<div class="related">
  {{#each related_posts}}
    <a href="/blog/{{this.slug}}">{{this.title}}</a>
  {{/each}}
</div>
```

**Nested `{{#each}}`** (Q3 from Oscar's review, locked): the scanner handles nesting via a depth counter. Inside one `{{#each}}`, you can open another:
```html
<div class="post">
  <h2>{{title}}</h2>
  <ul class="comments">
    {{#each comments}}
      <li>
        <strong>{{author}}</strong>: {{body}}
        {{#each replies}}
          <p class="reply">↳ {{author}}: {{body}}</p>
        {{/each}}
      </li>
    {{/each}}
  </ul>
</div>
```

The scanner uses a stack: each `{{#each X}}` pushes a binding, the matching `{{/each}}` pops it. Inside the block, `{{this}}` resolves to the top of the stack. Max depth: 3 levels (more than that and operators should rethink the data model). 4+ throws a warning.

v0.7.1a supports arrays of strings and arrays of flat objects. Nested objects (objects inside objects, not lists inside lists) deferred to v0.7.1b.

## Engine design (v0.7.1a)

**Where it lives**: client-side, in `edge-panel.js`. ~100 lines of JS, no new dependencies. No bridge changes (the filter registry lives on the bridge but the parser/renderer is client-side; the bridge just serves the filter metadata for v0.7.1b's picker UI).

**API**:
```js
const engine = new TemplateEngine({
  filters: filterRegistry,  // [{name, description, args: [{name, type, default}]}]
});

const html = engine.render(template, record);
// → "string of HTML with values substituted + filters applied"
```

**Pseudocode**:
```js
function render(template, record, filters) {
  // 1. Tokenize: scan template for {{...}} blocks
  // 2. For each {{...}} block:
  //    a. If `{{#each X}}...{{/each}}`: find matching end, recurse on each item
  //    b. Else if `{{X | filter | filter2}}`: resolve X, apply filters in order
  //    c. Else `{{X}}`: resolve X
  // 3. Concatenate output
}
```

**Error handling** (v0.7.1a):
- Unknown field: returns empty string (Q1) + logs a warning to the console
- Unknown filter: returns the original value + logs a warning
- Filter throws: returns the input value + logs a warning
- Missing field with `| default("fallback")`: returns the default (Q3)
- Template syntax error: returns the original template text + logs a warning (so the page doesn't go blank)

This is **fail-soft with logs**: a broken template doesn't crash the page, but the operator sees `console.warn` in the dev tools. **v0.7.1a logs to console only** (per Oscar's review). v0.7.1b adds an in-panel warning indicator (visible feedback in the UI).

**Security** (v0.7.1a):
- Default: HTML-escape all substituted values (no XSS)
- `| safe` filter explicitly opts out of escaping (for trusted fields like admin-controlled HTML)
- Never allow `{{> partial}}` or any filesystem-accessing syntax in v0.7.1a (that's a v0.7.2+ thing)

## Where the engine runs in v0.7.0 → v0.7.1a migration

v0.7.0's `renderRegionRecords` does:
```js
template.replace('Post title', rec.title).replace('Post excerpt…', rec.body)...
```

v0.7.1a replaces this with:
```js
const html = engine.render(template, rec, filterRegistry);
```

Templates that use the old v0.7.0 `{{field}}` syntax keep working — `{{title}}` is already a valid primitive.

## Open questions for operator signoff

1. **Missing field behavior**: empty string, `null`, or `{{field}}` literal? 
   - My pick: empty string (cleanest output). But operators might prefer seeing the missing marker.
2. **Should `{{#each}}` support `{{else}}`?**
   - My pick: not in v0.7.1a. v0.7.1b if needed.
3. **Default filter behavior on missing field**:
   - `{{field | default("fallback")}}` — return `"fallback"`
   - Should the default run before or after the missing-field check?
   - My pick: default runs on the *value*, so a missing field gets the default. That's the obvious behavior.
4. **Where does the filter registry live?**
   - My pick: bridge endpoint `GET /api/agent/templating/filters` returns the list. Operators don't need it for v0.7.1a (filters are hardcoded in the engine) but the endpoint should exist for v0.7.1b's picker.
5. **Date format strings**: ISO moment, simple, or strftime?
   - My pick: simple format ("MMM d, yyyy" not "%b %-d, %Y"). ISO moment would pull in another dep. v0.7.1b can swap if operators need strftime.
6. **Markdown engine**: which one? marked (heavy, 30KB), snarkdown (tiny, 2KB), or a homegrown parser (1KB, supports 80% of cases)?
   - My pick: snarkdown. 2KB, handles the common cases (headings, bold, italic, links, code, lists, paragraphs). Operators can switch later if they need more.

## What's NOT in v0.7.1a

- Filter registry picker UI (v0.7.1b)
- Visual schema inspector (v0.7.1b)
- Drag-to-insert fields (v0.7.1b)
- Nested object fields in `{{#each}}` (v0.7.1b)
- `{{> partial}}` includes (v0.7.2+)
- Conditional `{{#if}}` (v0.7.1b)
- Template versioning (operators editing the same template from two panels — v0.7.2+)

## Acceptance

- `{{title}}` substitutes correctly
- `{{body | markdown | truncate(280)}}` works end-to-end
- `{{#each tags}}<li>{{this}}</li>{{/each}}` renders a list
- Missing field doesn't crash; operator panel shows a warning
- Unknown filter doesn't crash; operator panel shows a warning
- No XSS in any test case (e.g. `{{body | safe}}` only when explicit)
- Performance: rendering 100 records with 5 fields each in < 50ms (not measurable for a single page)

## Estimated

- Spec doc: 30 min (this doc)
- Engine implementation: 1h (100 lines of JS in edge-panel.js)
- Test: 30 min (playwright screenshot before/after, 5-10 cases)
- Total: 2h

## File to edit

`avidtech6/freshvibe-cms/runtime/edge-panel/edge-panel.js` — replace the v0.7.0 `renderRegionRecords` String.replace hack with `engine.render(template, record, filterRegistry)`.

**Branch**: base off `fes-v2-world-class` HEAD (`6c9df6b`).

— end of v0.7.1a spec —