From d5c0260678df9d9e091046499d5e488c21655716 Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Wed, 29 Oct 2025 12:42:41 -0700
Subject: [PATCH 01/13] Refine HTL compatibility plan: expression syntax,
 migration docs, and utils:eval()

- #1: Make ${} optional in data-fly-* directives for HTL familiarity
- #2: Create HTL migration documentation explaining key differences
- #3: Add utils:eval() for JavaScript expressions (future consideration)
  - Uses new Function() for full JS power (~150 bytes)
  - Appropriately scary naming with 'eval' to warn developers
  - CSP requires unsafe-eval policy
  - Removed data-fly-use (not needed - context functions work better)
  - Removed context options (DOM manipulation doesn't need HTL's escaping)
---
 HTL_COMPATIBILITY_PLAN.md | 273 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 273 insertions(+)
 create mode 100644 HTL_COMPATIBILITY_PLAN.md

diff --git a/HTL_COMPATIBILITY_PLAN.md b/HTL_COMPATIBILITY_PLAN.md
new file mode 100644
index 0000000..ab31cfb
--- /dev/null
+++ b/HTL_COMPATIBILITY_PLAN.md
@@ -0,0 +1,273 @@
+# HTL/Sightly Compatibility Improvements Plan
+
+This document outlines planned improvements to make Faintly easier to use for developers with HTL/Sightly background.
+
+## Implementation Priority
+
+### ✅ To Implement
+
+#### 1. Standardize Expression Syntax (Refined)
+Make `${}` optional in `data-fly-*` directives for consistency with HTL.
+
+**Current behavior:**
+- `${}` required in text content and regular attributes (explicit evaluation)
+- Bare expressions in `data-fly-*` directive values
+
+**Proposed behavior:**
+- **In `data-fly-*` directives**: Accept both `${expression}` and bare `expression`
+- **In regular attributes and text**: Keep `${}` required (current behavior - efficient and explicit)
+
+**Why this approach:**
+- Avoids evaluating every attribute value (performance concern)
+- No ambiguity - `${}` explicitly marks what should be evaluated
+- Provides HTL-like feel where it matters (directives)
+- Maintains backward compatibility
+
+**Examples:**
+```html
+<!-- Both should work in directives -->
+<div data-fly-test="user.isAdmin">
+<div data-fly-test="${user.isAdmin}">
+
+<!-- Regular attributes still require ${} (unchanged) -->
+<a href="${link}">Link</a>
+<div class="card-${index}">Content</div>
+
+<!-- Text content still requires ${} (unchanged) -->
+<p>Hello ${user.name}</p>
+```
+
+**Implementation notes:**
+- Modify directive processing functions in `directives.js` to strip `${}` wrapper if present
+- Only affects `data-fly-*` attribute value parsing
+- Ensure backward compatibility with existing code
+- Update tests to cover both syntaxes in directives
+- Update README.md to document both syntaxes are supported in directives
+
+---
+
+#### 2. Add HTL Migration Documentation
+Create a dedicated doc linked from README.md with side-by-side comparisons.
+
+**Content to include:**
+- Directive comparison table (HTL vs Faintly)
+- Expression syntax differences
+- Backend integration comparison (`data-sly-use` vs context object)
+  - **Important**: Explain that `data-sly-use` is replaced by context functions
+  - Show how Faintly's automatic function calling provides lazy/conditional loading
+  - Example: `data-fly-content="fetchArticles"` automatically calls the function
+- Context options (`@ context='uri'`) and why they're not needed in Faintly
+  - HTL needs context-aware escaping because it generates HTML strings server-side
+  - Faintly manipulates DOM directly - browser handles escaping automatically
+  - Faintly's security module provides attribute/URL validation without needing context options
+- Common patterns and their equivalents
+- Migration examples from typical HTL components
+
+**Example table:**
+| HTL/Sightly | Faintly | Description |
+|-------------|---------|-------------|
+| `data-sly-test` | `data-fly-test` | Conditional rendering |
+| `data-sly-list` | `data-fly-repeat` | Iteration |
+| `data-sly-use` | context object | Backend integration |
+| `data-sly-template` | `<template data-fly-name>` | Named templates |
+| `data-sly-call` | `data-fly-include` | Template includes |
+| `data-sly-unwrap` | `data-fly-unwrap` | Remove wrapper element |
+| `data-sly-attribute` | `data-fly-attributes` | Set attributes dynamically |
+
+---
+
+### 🤔 Future Consideration
+
+#### 3. JavaScript Expression Evaluation with `utils:eval()`
+Add JavaScript expression evaluation using `utils:eval()` syntax for complex logic and operations.
+
+**Two Primary Use Cases:**
+
+1. **Comparisons** - For `data-fly-test` and `data-fly-not` directives
+2. **Formatting** - For text content and attribute values
+
+**Syntax Examples:**
+
+```html
+<!-- Comparisons in test directives -->
+<div data-fly-test="utils:eval(count > 5)">More than 5</div>
+<div data-fly-test="utils:eval(user.isAdmin || user.isModerator)">Admin or mod</div>
+<div data-fly-test="utils:eval(isValid && isActive)">Valid and active</div>
+<div data-fly-not="utils:eval(status === 'disabled')">Not disabled</div>
+<div data-fly-test="utils:eval((count > 5 && !isDisabled) || isAdmin)">Complex logic</div>
+
+<!-- Ternary operator -->
+<div>${utils:eval(showCount ? count : 'N/A')}</div>
+<div class="${utils:eval(isActive ? 'active' : 'inactive')}">Status</div>
+
+<!-- String/array methods (native JavaScript) -->
+<div>${utils:eval(items.join(', '))}</div>
+<div>${utils:eval(user.name.toUpperCase())}</div>
+<a href="${utils:eval(encodeURIComponent(userUrl))}">Link</a>
+<p>${utils:eval('Hello ' + user.name)}</p>
+
+<!-- Array/object access -->
+<div>${utils:eval(items[0])}</div>
+<div>${utils:eval(user.profile.name)}</div>
+```
+
+**Implementation Approach: JavaScript Evaluation with `new Function()`**
+
+**Architecture:**
+- Separate bundle: `dist/faintly.utils.js` (like security module)
+- Dynamically imported on first `utils:eval()` usage
+- Cached after first load (no reload on subsequent use)
+- Uses `new Function()` to evaluate JavaScript expressions in context scope
+
+**Expression Evaluation:**
+```javascript
+// In src/expressions.js - detect utils:eval(...)
+if (expression.startsWith('utils:eval(') && expression.endsWith(')')) {
+  if (!utilsModule) {
+    utilsModule = await import('./faintly.utils.js');
+  }
+  const expr = expression.slice(11, -1); // Extract expression from utils:eval(...)
+  return utilsModule.evaluate(expr, context);
+}
+
+// In src/faintly.utils.js
+export function evaluate(expr, context) {
+  const fn = new Function('ctx', `with(ctx) { return ${expr}; }`);
+  return fn(context);
+}
+```
+
+**Supports Full JavaScript Syntax:**
+- **Comparisons**: `count > 5`, `status === 'active'`
+- **Logical operators**: `isAdmin || isModerator`, `isValid && isActive`
+- **Ternary**: `condition ? 'yes' : 'no'`
+- **Method calls**: `items.join(', ')`, `name.toUpperCase()`
+- **Array/object access**: `items[0]`, `user.profile.name`
+- **Complex expressions**: `(count > 5 && !isDisabled) || isAdmin`
+
+**Why this approach:**
+- ✅ **Appropriately scary** - `eval` in the name warns developers about what's happening
+- ✅ **Explicit and clear** - `utils:eval(expression)` is self-documenting
+- ✅ Minimal bundle impact (~100-150 bytes)
+- ✅ Full JavaScript expressiveness
+- ✅ Simple implementation, easy to maintain
+- ✅ Error handling - throws on invalid syntax
+- ✅ Supports all use cases without parser limitations
+- ✅ Future-proof - leaves room for `utils:safe()` or other utils later
+
+**Security & CSP Considerations:**
+- ⚠️ Uses `new Function()` which requires `unsafe-eval` CSP policy
+- ⚠️ Context is fully trusted - expressions have access to entire context
+- ⚠️ **Do not put untrusted user input in context** (already documented)
+- ⚠️ Templates are authored by developers (not user-generated)
+- ⚠️ If CSP blocks `unsafe-eval`, this feature cannot be used
+
+**Trade-offs:**
+- **Accepted**: CSP limitation, security responsibility on developer
+- **Benefit**: 400-500 byte savings vs custom parser
+- **Benefit**: No parser complexity or maintenance burden
+- **Benefit**: Full JavaScript power without artificial limitations
+
+**What You Can Use:**
+
+Since expressions are evaluated as JavaScript, you have access to:
+
+*Native JavaScript Operators:*
+- Comparison: `>`, `<`, `>=`, `<=`, `===`, `!==`
+- Logical: `&&`, `||`, `!`
+- Ternary: `condition ? ifTrue : ifFalse`
+- Arithmetic: `+`, `-`, `*`, `/`, `%`
+
+*Native JavaScript Methods:*
+- String: `.toUpperCase()`, `.toLowerCase()`, `.substring()`, `.trim()`, etc.
+- Array: `.join()`, `.map()`, `.filter()`, `.length`, `[index]`, etc.
+- Object: property access with `.` or `[]`
+- Global: `encodeURIComponent()`, `encodeURI()`, `parseInt()`, etc.
+
+*Optional Helper Functions:*
+You can add custom helpers to the context if needed:
+```javascript
+await renderBlock(block, {
+  items,
+  formatMessage: (name, count) => `Hello ${name}, you have ${count} messages`,
+  truncate: (str, len) => str.length > len ? str.slice(0, len) + '...' : str,
+});
+```
+```html
+<div>${utils:eval(formatMessage(user.name, messageCount))}</div>
+<p>${utils:eval(truncate(longText, 100))}</p>
+```
+
+**Implementation Steps:**
+1. Create `src/faintly.utils.js` with JavaScript evaluation function
+2. Modify `src/expressions.js` to detect `utils:eval()` syntax and dynamic import
+3. Add comprehensive tests for:
+   - Comparisons, logical operators, ternary
+   - String/array methods
+   - Complex nested expressions
+   - Error cases (syntax errors, undefined variables)
+   - Context helper functions being called
+4. Build separate `dist/faintly.utils.js` bundle
+5. Document in README with:
+   - Examples of common patterns with `utils:eval()`
+   - **Prominent warning**: Uses `eval` - understand the implications
+   - Security warnings (no untrusted input in context)
+   - CSP requirements (`unsafe-eval` policy required)
+   - When to use `utils:eval()` vs context functions
+6. Ensure bundle stays under 150 bytes (gzipped)
+
+**Error Handling:**
+- Throws JavaScript syntax errors with stack trace
+- Undefined variable errors bubble up naturally
+- Consider wrapping errors with more context (which template/directive)
+
+**Future Extensions:**
+- Optional `utils:safe()` with custom parser if users need CSP compatibility
+  - Example: `utils:safe(gt(count, 5))` - uses safe parser, no eval
+  - Would be a larger bundle but CSP-compatible
+- Additional built-in helper functions based on user feedback
+- Allow passing custom helper functions via context `utils` property
+
+---
+
+## Implementation Order
+
+1. **Standardize expression syntax** (#1) - Foundational change, affects everything
+2. **Add migration documentation** (#2) - Document completed features
+
+## Testing Strategy
+
+- Maintain 100% code coverage
+- Add tests for both old and new syntax (backward compatibility)
+- Add integration tests showing HTL migration patterns
+- Performance tests to ensure no regression
+
+## Bundle Size Constraints
+
+- Core bundle limit: 4KB / 4096 bytes (gzipped)
+- Combined limit: 6KB / 6144 bytes (gzipped)
+- Each feature must be evaluated for size impact
+- May need to optimize existing code if approaching limits
+
+---
+
+## HTL/Sightly Comparison Summary
+
+### Similarities
+- HTML5 data attributes for directives
+- Security-first approach with XSS protection
+- Separation of concerns (logic vs markup)
+- Expression-based templating
+- Conditional rendering and iteration
+- Template reuse and composition
+
+### Key Differences
+- **Execution context**: HTL is server-side (Java/Sling), Faintly is client-side (JavaScript)
+- **Directive prefix**: `data-sly-*` vs `data-fly-*`
+- **Backend integration**: HTL uses `data-sly-use`, Faintly uses context object
+- **Iteration**: `data-sly-list` vs `data-fly-repeat`
+- **Expression syntax**: HTL always uses `${}`, Faintly varies by context (for now)
+
+### Target Outcome
+Make Faintly feel natural to HTL developers while maintaining its lightweight, client-side focus.
+

From 1a21b8fbf2a3f67336d485922d64a0f8418b6d76 Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Wed, 29 Oct 2025 13:36:41 -0700
Subject: [PATCH 02/13] Implement standardized expression syntax for HTL
 compatibility

Add support for both bare and ${}-wrapped expressions in data-fly-* directives.

Changes:
- Add unwrapExpression() in expressions.js to strip ${} wrapper
- Apply unwrapping to all directive processors (test, repeat, content, attributes, unwrap)
- Add comprehensive tests for unwrapExpression (13 new tests)
- Add tests for ${} syntax in all directive types (9 new tests)
- Update README to document both syntax styles
- Maintain 100% test coverage (117 tests passing)

Bundle size: 2729 bytes core / 3375 bytes total (well within limits)

For HTL/Sightly users, directives now accept both syntaxes:
  data-fly-test="condition" and data-fly-test="${condition}"

Regular attributes still require ${}: class="${myClass}"
---
 README.md                                     | 17 +++-
 dist/faintly.js                               | 21 +++--
 src/directives.js                             | 16 ++--
 src/expressions.js                            | 13 +++
 .../attributes/processAttributes.test.js      | 18 ++++
 .../directives/content/processContent.test.js | 24 +++++
 test/directives/repeat/processRepeat.test.js  | 35 +++++++
 test/directives/test/processTest.test.js      | 51 +++++++++++
 test/directives/unwrap/processUnwrap.test.js  | 22 +++++
 test/expressions/unwrapExpression.test.js     | 91 +++++++++++++++++++
 10 files changed, 288 insertions(+), 20 deletions(-)
 create mode 100644 test/expressions/unwrapExpression.test.js

diff --git a/README.md b/README.md
index 31d271d..1b0f4f8 100644
--- a/README.md
+++ b/README.md
@@ -197,8 +197,15 @@ Faintly supports the following directives.
 
 Faintly supports a simple expression syntax for resolving data from the rendering context. It supports only object dot-notation, but will call (optionally async) functions as well. This means that if you need to do something that can't be expressed in dot-notation, then you need to define a custom function for it, and add that function to the rendering context.
 
-For `data-fly-include`, HTML text, and normal attributes, wrap your expression in `${}`.
-
-Escaping: use a leading backslash to prevent evaluation of an expression in text/attributes, e.g. `\${some.value}` will remain literal `${some.value}`.
-
-In all other `data-fly-*` attributes, just set the expression directly as the attribute value, no wrapping needed.
+**In `data-fly-*` directive attributes:**
+- Both bare expressions and `${}` wrapped expressions are supported
+- `data-fly-test="condition"` and `data-fly-test="${condition}"` both work
+- The `${}` syntax is supported for familiarity with HTL/Sightly
+
+**In `data-fly-include`, HTML text, and normal attributes:**
+- You must wrap your expression in `${}`
+- Example: `<div class="${className}">`, `<p>Hello ${user.name}</p>`
+
+**Escaping:**
+- Use a leading backslash to prevent evaluation of an expression in text/attributes
+- Example: `\${some.value}` will remain literal `${some.value}`
diff --git a/dist/faintly.js b/dist/faintly.js
index 0090cc6..1443507 100644
--- a/dist/faintly.js
+++ b/dist/faintly.js
@@ -28,6 +28,13 @@ async function resolveTemplate(context) {
 }
 
 // src/expressions.js
+function unwrapExpression(expression) {
+  const trimmed = expression.trim();
+  if (trimmed.startsWith("${") && trimmed.endsWith("}")) {
+    return trimmed.slice(2, -1).trim();
+  }
+  return expression;
+}
 async function resolveExpression(expression, context) {
   let resolved = context;
   let previousResolvedValue;
@@ -70,7 +77,7 @@ async function processTextExpressions(node, context) {
 // src/directives.js
 async function processAttributesDirective(el, context) {
   if (!el.hasAttribute("data-fly-attributes")) return;
-  const attrsExpression = el.getAttribute("data-fly-attributes");
+  const attrsExpression = unwrapExpression(el.getAttribute("data-fly-attributes"));
   const attrsData = await resolveExpression(attrsExpression, context);
   el.removeAttribute("data-fly-attributes");
   if (attrsData) {
@@ -105,7 +112,7 @@ async function processTest(el, context) {
   if (!testAttrName) return true;
   const nameParts = testAttrName.split(".");
   const contextName = nameParts[1] || "";
-  const testExpression = el.getAttribute(testAttrName);
+  const testExpression = unwrapExpression(el.getAttribute(testAttrName));
   const testData = await resolveExpression(testExpression, context);
   el.removeAttribute(testAttrName);
   const testResult = testAttrName.startsWith("data-fly-not") ? !testData : !!testData;
@@ -117,7 +124,7 @@ async function processTest(el, context) {
 }
 async function processContent(el, context) {
   if (!el.hasAttribute("data-fly-content")) return false;
-  const contentExpression = el.getAttribute("data-fly-content");
+  const contentExpression = unwrapExpression(el.getAttribute("data-fly-content"));
   const content = await resolveExpression(contentExpression, context);
   el.removeAttribute("data-fly-content");
   if (content !== void 0) {
@@ -139,7 +146,7 @@ async function processRepeat(el, context) {
   if (!repeatAttrName) return false;
   const nameParts = repeatAttrName.split(".");
   const contextName = nameParts[1] || "item";
-  const repeatExpression = el.getAttribute(repeatAttrName);
+  const repeatExpression = unwrapExpression(el.getAttribute(repeatAttrName));
   const arr = await resolveExpression(repeatExpression, context);
   if (!arr || Object.keys(arr).length === 0) {
     el.remove();
@@ -195,9 +202,9 @@ async function processInclude(el, context) {
 }
 async function resolveUnwrap(el, context) {
   if (!el.hasAttribute("data-fly-unwrap")) return;
-  const unwrapExpression = el.getAttribute("data-fly-unwrap");
-  if (unwrapExpression) {
-    const unwrapVal = !!await resolveExpression(unwrapExpression, context);
+  const unwrapExpr = el.getAttribute("data-fly-unwrap");
+  if (unwrapExpr) {
+    const unwrapVal = !!await resolveExpression(unwrapExpression(unwrapExpr), context);
     if (!unwrapVal) {
       el.removeAttribute("data-fly-unwrap");
     }
diff --git a/src/directives.js b/src/directives.js
index f6a5ca4..fdd87da 100644
--- a/src/directives.js
+++ b/src/directives.js
@@ -1,11 +1,11 @@
-import { resolveExpression, resolveExpressions } from './expressions.js';
+import { resolveExpression, resolveExpressions, unwrapExpression } from './expressions.js';
 // eslint-disable-next-line import/no-cycle
 import { processNode, renderElement } from './render.js';
 
 async function processAttributesDirective(el, context) {
   if (!el.hasAttribute('data-fly-attributes')) return;
 
-  const attrsExpression = el.getAttribute('data-fly-attributes');
+  const attrsExpression = unwrapExpression(el.getAttribute('data-fly-attributes'));
   const attrsData = await resolveExpression(attrsExpression, context);
 
   el.removeAttribute('data-fly-attributes');
@@ -61,7 +61,7 @@ export async function processTest(el, context) {
   const nameParts = testAttrName.split('.');
   const contextName = nameParts[1] || '';
 
-  const testExpression = el.getAttribute(testAttrName);
+  const testExpression = unwrapExpression(el.getAttribute(testAttrName));
   const testData = await resolveExpression(testExpression, context);
 
   el.removeAttribute(testAttrName);
@@ -87,7 +87,7 @@ export async function processTest(el, context) {
 export async function processContent(el, context) {
   if (!el.hasAttribute('data-fly-content')) return false;
 
-  const contentExpression = el.getAttribute('data-fly-content');
+  const contentExpression = unwrapExpression(el.getAttribute('data-fly-content'));
   const content = await resolveExpression(contentExpression, context);
 
   el.removeAttribute('data-fly-content');
@@ -123,7 +123,7 @@ export async function processRepeat(el, context) {
   const nameParts = repeatAttrName.split('.');
   const contextName = nameParts[1] || 'item';
 
-  const repeatExpression = el.getAttribute(repeatAttrName);
+  const repeatExpression = unwrapExpression(el.getAttribute(repeatAttrName));
   const arr = await resolveExpression(repeatExpression, context);
   if (!arr || Object.keys(arr).length === 0) {
     el.remove();
@@ -211,9 +211,9 @@ export async function processInclude(el, context) {
 export async function resolveUnwrap(el, context) {
   if (!el.hasAttribute('data-fly-unwrap')) return;
 
-  const unwrapExpression = el.getAttribute('data-fly-unwrap');
-  if (unwrapExpression) {
-    const unwrapVal = !!(await resolveExpression(unwrapExpression, context));
+  const unwrapExpr = el.getAttribute('data-fly-unwrap');
+  if (unwrapExpr) {
+    const unwrapVal = !!(await resolveExpression(unwrapExpression(unwrapExpr), context));
 
     if (!unwrapVal) {
       el.removeAttribute('data-fly-unwrap');
diff --git a/src/expressions.js b/src/expressions.js
index 5cb785d..2803a45 100644
--- a/src/expressions.js
+++ b/src/expressions.js
@@ -1,3 +1,16 @@
+/**
+ * Strips ${} wrapper from expression if present for HTL compatibility
+ * @param {string} expression the expression that may be wrapped
+ * @returns {string} the unwrapped expression
+ */
+export function unwrapExpression(expression) {
+  const trimmed = expression.trim();
+  if (trimmed.startsWith('${') && trimmed.endsWith('}')) {
+    return trimmed.slice(2, -1).trim();
+  }
+  return expression;
+}
+
 /**
  * resolves and returns data from the rendering context
  *
diff --git a/test/directives/attributes/processAttributes.test.js b/test/directives/attributes/processAttributes.test.js
index 378cb5f..cb5476b 100644
--- a/test/directives/attributes/processAttributes.test.js
+++ b/test/directives/attributes/processAttributes.test.js
@@ -151,5 +151,23 @@ describe('processAttributes', () => {
 
       expect(el.hasAttribute('href')).to.equal(false);
     });
+
+    it('supports ${} wrapped expressions in data-fly-attributes', async () => {
+      const el = document.createElement('div');
+      // eslint-disable-next-line no-template-curly-in-string
+      el.setAttribute('data-fly-attributes', '${attrsObj}');
+      const context = {
+        attrsObj: {
+          foo: 'bar',
+          id: 'some-id',
+          class: 'some-class',
+        },
+      };
+      context.security = await initializeSecurity(context);
+      await processAttributes(el, context);
+      expect(el.getAttribute('foo')).to.equal('bar');
+      expect(el.getAttribute('id')).to.equal('some-id');
+      expect(el.getAttribute('class')).to.equal('some-class');
+    });
   });
 });
diff --git a/test/directives/content/processContent.test.js b/test/directives/content/processContent.test.js
index 558cea6..08f4d04 100644
--- a/test/directives/content/processContent.test.js
+++ b/test/directives/content/processContent.test.js
@@ -142,4 +142,28 @@ describe('processContent', () => {
     await processContent(el);
     expect(el.hasAttribute('data-fly-content')).to.equal(false);
   });
+
+  it('supports ${} wrapped expressions', async () => {
+    const el = document.createElement('div');
+    el.textContent = 'Some text';
+    // eslint-disable-next-line no-template-curly-in-string
+    el.setAttribute('data-fly-content', '${content}');
+    const result = await processContent(el, {
+      content: 'Some other text',
+    });
+    expect(result).to.equal(true);
+    expect(el.textContent).to.equal('Some other text');
+  });
+
+  it('supports ${} wrapped expressions with dot notation', async () => {
+    const el = document.createElement('div');
+    el.textContent = 'Some text';
+    // eslint-disable-next-line no-template-curly-in-string
+    el.setAttribute('data-fly-content', '${user.name}');
+    const result = await processContent(el, {
+      user: { name: 'Bob' },
+    });
+    expect(result).to.equal(true);
+    expect(el.textContent).to.equal('Bob');
+  });
 });
diff --git a/test/directives/repeat/processRepeat.test.js b/test/directives/repeat/processRepeat.test.js
index cd74eab..46005d3 100644
--- a/test/directives/repeat/processRepeat.test.js
+++ b/test/directives/repeat/processRepeat.test.js
@@ -98,4 +98,39 @@ describe('processRepeat', () => {
       expect(repeatedEl.hasAttribute('data-fly-repeat')).to.equal(false);
     });
   });
+
+  it('supports ${} wrapped expressions', async () => {
+    const el = document.createElement('div');
+    el.setAttribute('data-fly-repeat', '${array}');
+    el.textContent = 'Hello, ${item}!';
+
+    const parent = document.createElement('div');
+    parent.append(el);
+
+    const repeated = await processRepeat(el, {
+      array: ['bob', 'alice', 'charlie'],
+    });
+    expect(repeated).to.be.true;
+    expect(el.parentNode).to.equal(null);
+    expect(parent.children[0].textContent).to.equal('Hello, bob!');
+    expect(parent.children[1].textContent).to.equal('Hello, alice!');
+    expect(parent.children[2].textContent).to.equal('Hello, charlie!');
+  });
+
+  it('supports ${} wrapped expressions with custom context name', async () => {
+    const el = document.createElement('div');
+    el.setAttribute('data-fly-repeat.name', '${array}');
+    el.textContent = 'Hello, ${name}!';
+
+    const parent = document.createElement('div');
+    parent.append(el);
+
+    const repeated = await processRepeat(el, {
+      array: ['bob', 'alice', 'charlie'],
+    });
+    expect(repeated).to.be.true;
+    expect(parent.children[0].textContent).to.equal('Hello, bob!');
+    expect(parent.children[1].textContent).to.equal('Hello, alice!');
+    expect(parent.children[2].textContent).to.equal('Hello, charlie!');
+  });
 });
diff --git a/test/directives/test/processTest.test.js b/test/directives/test/processTest.test.js
index 73b726a..fb9a97d 100644
--- a/test/directives/test/processTest.test.js
+++ b/test/directives/test/processTest.test.js
@@ -66,6 +66,37 @@ describe('processTest', () => {
       await processTest(el);
       expect(el.hasAttribute('data-fly-test')).to.equal(false);
     });
+
+    it('supports ${} wrapped expressions', async () => {
+      const parent = document.createElement('div');
+
+      const el = document.createElement('div');
+      parent.appendChild(el);
+      // eslint-disable-next-line no-template-curly-in-string
+      el.setAttribute('data-fly-test', '${includeDiv}');
+      const result = await processTest(el, { includeDiv: true });
+      expect(result).to.equal(true);
+      expect(el.parentNode).to.equal(parent);
+
+      const el2 = document.createElement('div');
+      parent.appendChild(el2);
+      // eslint-disable-next-line no-template-curly-in-string
+      el2.setAttribute('data-fly-test', '${includeDiv}');
+      const result2 = await processTest(el2, { includeDiv: false });
+      expect(result2).to.equal(false);
+      expect(el2.parentNode).to.equal(null);
+    });
+
+    it('supports ${} wrapped expressions with dot notation', async () => {
+      const parent = document.createElement('div');
+      const el = document.createElement('div');
+      parent.appendChild(el);
+      // eslint-disable-next-line no-template-curly-in-string
+      el.setAttribute('data-fly-test', '${user.isAdmin}');
+      const result = await processTest(el, { user: { isAdmin: true } });
+      expect(result).to.equal(true);
+      expect(el.parentNode).to.equal(parent);
+    });
   });
 
   describe('data-fly-not', () => {
@@ -129,5 +160,25 @@ describe('processTest', () => {
       await processTest(el);
       expect(el.hasAttribute('data-fly-not')).to.equal(false);
     });
+
+    it('supports ${} wrapped expressions', async () => {
+      const parent = document.createElement('div');
+
+      const el = document.createElement('div');
+      parent.appendChild(el);
+      // eslint-disable-next-line no-template-curly-in-string
+      el.setAttribute('data-fly-not', '${includeDiv}');
+      const result = await processTest(el, { includeDiv: true });
+      expect(result).to.equal(false);
+      expect(el.parentNode).to.equal(null);
+
+      const el2 = document.createElement('div');
+      parent.appendChild(el2);
+      // eslint-disable-next-line no-template-curly-in-string
+      el2.setAttribute('data-fly-not', '${includeDiv}');
+      const result2 = await processTest(el2, { includeDiv: false });
+      expect(result2).to.equal(true);
+      expect(el2.parentNode).to.equal(parent);
+    });
   });
 });
diff --git a/test/directives/unwrap/processUnwrap.test.js b/test/directives/unwrap/processUnwrap.test.js
index 98a87ec..63361cd 100644
--- a/test/directives/unwrap/processUnwrap.test.js
+++ b/test/directives/unwrap/processUnwrap.test.js
@@ -82,4 +82,26 @@ describe('resolveUnwrap', () => {
     await resolveUnwrap(numEl, { includeDiv: 0 });
     expect(numEl.hasAttribute('data-fly-unwrap')).to.equal(false);
   });
+
+  it('supports ${} wrapped expressions', async () => {
+    const el = document.createElement('div');
+    // eslint-disable-next-line no-template-curly-in-string
+    el.setAttribute('data-fly-unwrap', '${includeDiv}');
+    await resolveUnwrap(el, { includeDiv: true });
+    expect(el.hasAttribute('data-fly-unwrap')).to.equal(true);
+
+    const el2 = document.createElement('div');
+    // eslint-disable-next-line no-template-curly-in-string
+    el2.setAttribute('data-fly-unwrap', '${includeDiv}');
+    await resolveUnwrap(el2, { includeDiv: false });
+    expect(el2.hasAttribute('data-fly-unwrap')).to.equal(false);
+  });
+
+  it('supports ${} wrapped expressions with dot notation', async () => {
+    const el = document.createElement('div');
+    // eslint-disable-next-line no-template-curly-in-string
+    el.setAttribute('data-fly-unwrap', '${user.isAdmin}');
+    await resolveUnwrap(el, { user: { isAdmin: true } });
+    expect(el.hasAttribute('data-fly-unwrap')).to.equal(true);
+  });
 });
diff --git a/test/expressions/unwrapExpression.test.js b/test/expressions/unwrapExpression.test.js
new file mode 100644
index 0000000..52a88b9
--- /dev/null
+++ b/test/expressions/unwrapExpression.test.js
@@ -0,0 +1,91 @@
+/* eslint-env mocha */
+/* eslint-disable no-unused-expressions */
+/* eslint-disable no-template-curly-in-string */
+
+import { expect } from '@esm-bundle/chai';
+import { unwrapExpression } from '../../src/expressions.js';
+
+describe('unwrapExpression', () => {
+  it('unwraps ${} wrapped expressions', () => {
+    const result = unwrapExpression('${foo.bar}');
+    expect(result).to.equal('foo.bar');
+  });
+
+  it('returns bare expressions unchanged', () => {
+    const result = unwrapExpression('foo.bar');
+    expect(result).to.equal('foo.bar');
+  });
+
+  it('handles whitespace inside ${} wrapper', () => {
+    const result = unwrapExpression('${  foo.bar  }');
+    expect(result).to.equal('foo.bar');
+  });
+
+  it('handles whitespace outside ${} wrapper', () => {
+    const result = unwrapExpression('  ${foo.bar}  ');
+    expect(result).to.equal('foo.bar');
+  });
+
+  it('handles whitespace both inside and outside', () => {
+    const result = unwrapExpression('  ${  foo.bar  }  ');
+    expect(result).to.equal('foo.bar');
+  });
+
+  it('returns empty string for empty ${} wrapper', () => {
+    const result = unwrapExpression('${}');
+    expect(result).to.equal('');
+  });
+
+  it('returns empty string for whitespace-only ${} wrapper', () => {
+    const result = unwrapExpression('${   }');
+    expect(result).to.equal('');
+  });
+
+  it('does not unwrap partial ${} patterns', () => {
+    // Missing closing brace
+    const result1 = unwrapExpression('${foo.bar');
+    expect(result1).to.equal('${foo.bar');
+
+    // Missing opening brace
+    const result2 = unwrapExpression('foo.bar}');
+    expect(result2).to.equal('foo.bar}');
+
+    // Wrong order
+    const result3 = unwrapExpression('}foo.bar${');
+    expect(result3).to.equal('}foo.bar${');
+  });
+
+  it('does not unwrap if ${} is not at start and end', () => {
+    // Has content before
+    const result1 = unwrapExpression('prefix${foo.bar}');
+    expect(result1).to.equal('prefix${foo.bar}');
+
+    // Has content after
+    const result2 = unwrapExpression('${foo.bar}suffix');
+    expect(result2).to.equal('${foo.bar}suffix');
+
+    // Has content both sides
+    const result3 = unwrapExpression('prefix${foo.bar}suffix');
+    expect(result3).to.equal('prefix${foo.bar}suffix');
+  });
+
+  it('handles simple property names', () => {
+    const result = unwrapExpression('${foo}');
+    expect(result).to.equal('foo');
+  });
+
+  it('handles deeply nested properties', () => {
+    const result = unwrapExpression('${foo.bar.baz.qux}');
+    expect(result).to.equal('foo.bar.baz.qux');
+  });
+
+  it('returns empty string unchanged', () => {
+    const result = unwrapExpression('');
+    expect(result).to.equal('');
+  });
+
+  it('returns whitespace-only string unchanged', () => {
+    const result = unwrapExpression('   ');
+    expect(result).to.equal('   ');
+  });
+});

From ca2f9ad98853ca213699b5cbb78a360f5d66a77a Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Wed, 29 Oct 2025 13:38:38 -0700
Subject: [PATCH 03/13] Mark standardized expression syntax as completed in
 plan

---
 HTL_COMPATIBILITY_PLAN.md | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/HTL_COMPATIBILITY_PLAN.md b/HTL_COMPATIBILITY_PLAN.md
index ab31cfb..edc0755 100644
--- a/HTL_COMPATIBILITY_PLAN.md
+++ b/HTL_COMPATIBILITY_PLAN.md
@@ -4,9 +4,9 @@ This document outlines planned improvements to make Faintly easier to use for de
 
 ## Implementation Priority
 
-### ✅ To Implement
+### ✅ Completed
 
-#### 1. Standardize Expression Syntax (Refined)
+#### 1. Standardize Expression Syntax (Refined) - ✅ IMPLEMENTED
 Make `${}` optional in `data-fly-*` directives for consistency with HTL.
 
 **Current behavior:**
@@ -44,8 +44,21 @@ Make `${}` optional in `data-fly-*` directives for consistency with HTL.
 - Update tests to cover both syntaxes in directives
 - Update README.md to document both syntaxes are supported in directives
 
+**Implementation Results:**
+- ✅ Added `unwrapExpression()` function in `src/expressions.js`
+- ✅ Applied unwrapping to all directive processors: `processTest`, `processRepeat`, `processContent`, `processAttributes`, `resolveUnwrap`
+- ✅ Added 13 comprehensive tests for `unwrapExpression()`
+- ✅ Added 9 integration tests for `${}` syntax across all directive types
+- ✅ Updated README Expressions section with clear documentation
+- ✅ 117 tests passing with 100% coverage maintained
+- ✅ Bundle size: 2729 bytes core (actually 1 byte smaller!)
+- ✅ All directives now support both syntaxes: `data-fly-test="condition"` and `data-fly-test="${condition}"`
+- ✅ Committed in commit `1a21b8f`
+
 ---
 
+### 🚧 To Implement
+
 #### 2. Add HTL Migration Documentation
 Create a dedicated doc linked from README.md with side-by-side comparisons.
 
@@ -232,7 +245,7 @@ await renderBlock(block, {
 
 ## Implementation Order
 
-1. **Standardize expression syntax** (#1) - Foundational change, affects everything
+1. ✅ **Standardize expression syntax** (#1) - COMPLETED
 2. **Add migration documentation** (#2) - Document completed features
 
 ## Testing Strategy
@@ -266,7 +279,7 @@ await renderBlock(block, {
 - **Directive prefix**: `data-sly-*` vs `data-fly-*`
 - **Backend integration**: HTL uses `data-sly-use`, Faintly uses context object
 - **Iteration**: `data-sly-list` vs `data-fly-repeat`
-- **Expression syntax**: HTL always uses `${}`, Faintly varies by context (for now)
+- **Expression syntax**: HTL always uses `${}`, Faintly now supports both `${}` and bare expressions in directives
 
 ### Target Outcome
 Make Faintly feel natural to HTL developers while maintaining its lightweight, client-side focus.

From c704f590164300350c02c4a90e155db36a7dcbce Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Wed, 29 Oct 2025 14:27:42 -0700
Subject: [PATCH 04/13] feat: add utils:eval() for JavaScript expression
 evaluation

- Add evaluate() function in src/expressions.js using Function constructor
- Detect and handle utils:eval() syntax in resolveExpression()
- Update regex to [^}]+] for consistent escaping behavior
- Add 70 comprehensive tests for utils:eval() covering:
  - Comparisons, logical operators, ternary
  - String/array methods, arithmetic, object access
  - Custom helper functions, error handling
  - Whitespace handling, edge cases
- Add 15 tests documenting operator-without-eval behavior
- Update README with:
  - Prominent CAUTION warning about eval and CSP requirements
  - Clear examples of what requires vs doesn't require utils:eval()
  - Guidance on when to use utils:eval() vs context functions
- Update HTL_COMPATIBILITY_PLAN with implementation results
- 187 tests passing with 100% coverage maintained
- Bundle: 2811 bytes core (+82 bytes), 3457 bytes combined
- All under size limits (4KB core, 6KB combined)
---
 HTL_COMPATIBILITY_PLAN.md                     | 188 ++-------
 README.md                                     |  67 ++-
 dist/faintly.js                               |  13 +-
 src/expressions.js                            |  24 +-
 .../expressions/operator-without-eval.test.js | 139 +++++++
 test/expressions/utils-eval.test.js           | 386 ++++++++++++++++++
 6 files changed, 658 insertions(+), 159 deletions(-)
 create mode 100644 test/expressions/operator-without-eval.test.js
 create mode 100644 test/expressions/utils-eval.test.js

diff --git a/HTL_COMPATIBILITY_PLAN.md b/HTL_COMPATIBILITY_PLAN.md
index edc0755..8db91db 100644
--- a/HTL_COMPATIBILITY_PLAN.md
+++ b/HTL_COMPATIBILITY_PLAN.md
@@ -57,6 +57,39 @@ Make `${}` optional in `data-fly-*` directives for consistency with HTL.
 
 ---
 
+#### 3. JavaScript Expression Evaluation with `utils:eval()` - ✅ IMPLEMENTED
+Add JavaScript expression evaluation using `utils:eval()` syntax for complex logic and operations.
+
+**Implementation Results:**
+- ✅ Added `evaluate()` function directly in `src/expressions.js` (kept internal, no separate bundle needed)
+- ✅ Modified `resolveExpression()` to detect and handle `utils:eval()` syntax
+- ✅ Updated regex pattern in `resolveExpressions()` to support complex expressions (`/(\\)?\${([^}]+)}/gi`)
+- ✅ Added 70 comprehensive tests covering:
+  - Comparisons (`>`, `<`, `>=`, `<=`, `===`, `!==`)
+  - Logical operators (`&&`, `||`, `!`)
+  - Ternary operator
+  - String methods (`.toUpperCase()`, `.toLowerCase()`, `.substring()`, `.trim()`, concatenation)
+  - Array methods (`.join()`, `.map()`, `.filter()`, `.length`, index access)
+  - Object access (nested properties, bracket notation, dynamic properties)
+  - Arithmetic operations (`+`, `-`, `*`, `/`, `%`)
+  - Global functions (`encodeURIComponent()`, `parseInt()`, `parseFloat()`)
+  - Custom helper functions from context
+  - Error handling (undefined variables, syntax errors)
+  - Edge cases (empty expression, whitespace, null, undefined, booleans)
+  - Real-world scenarios (admin checks, plural formatting, conditional CSS classes, status badges)
+- ✅ Updated README with comprehensive documentation including:
+  - Usage examples for all primary use cases
+  - List of supported operators and methods
+  - Custom helper function examples
+  - **Prominent CAUTION warning** about eval and CSP requirements
+  - Guidance on when to use `utils:eval()` vs context functions
+- ✅ 165 tests passing (70 new tests added) with 100% coverage maintained
+- ✅ Bundle size: 2804 bytes core (only 75 bytes increase!), 3450 bytes combined
+- ✅ All constraints met: under 4KB core limit, under 6KB combined limit
+- ✅ Lint passed, build passed
+
+---
+
 ### 🚧 To Implement
 
 #### 2. Add HTL Migration Documentation
@@ -89,164 +122,11 @@ Create a dedicated doc linked from README.md with side-by-side comparisons.
 
 ---
 
-### 🤔 Future Consideration
-
-#### 3. JavaScript Expression Evaluation with `utils:eval()`
-Add JavaScript expression evaluation using `utils:eval()` syntax for complex logic and operations.
-
-**Two Primary Use Cases:**
-
-1. **Comparisons** - For `data-fly-test` and `data-fly-not` directives
-2. **Formatting** - For text content and attribute values
-
-**Syntax Examples:**
-
-```html
-<!-- Comparisons in test directives -->
-<div data-fly-test="utils:eval(count > 5)">More than 5</div>
-<div data-fly-test="utils:eval(user.isAdmin || user.isModerator)">Admin or mod</div>
-<div data-fly-test="utils:eval(isValid && isActive)">Valid and active</div>
-<div data-fly-not="utils:eval(status === 'disabled')">Not disabled</div>
-<div data-fly-test="utils:eval((count > 5 && !isDisabled) || isAdmin)">Complex logic</div>
-
-<!-- Ternary operator -->
-<div>${utils:eval(showCount ? count : 'N/A')}</div>
-<div class="${utils:eval(isActive ? 'active' : 'inactive')}">Status</div>
-
-<!-- String/array methods (native JavaScript) -->
-<div>${utils:eval(items.join(', '))}</div>
-<div>${utils:eval(user.name.toUpperCase())}</div>
-<a href="${utils:eval(encodeURIComponent(userUrl))}">Link</a>
-<p>${utils:eval('Hello ' + user.name)}</p>
-
-<!-- Array/object access -->
-<div>${utils:eval(items[0])}</div>
-<div>${utils:eval(user.profile.name)}</div>
-```
-
-**Implementation Approach: JavaScript Evaluation with `new Function()`**
-
-**Architecture:**
-- Separate bundle: `dist/faintly.utils.js` (like security module)
-- Dynamically imported on first `utils:eval()` usage
-- Cached after first load (no reload on subsequent use)
-- Uses `new Function()` to evaluate JavaScript expressions in context scope
-
-**Expression Evaluation:**
-```javascript
-// In src/expressions.js - detect utils:eval(...)
-if (expression.startsWith('utils:eval(') && expression.endsWith(')')) {
-  if (!utilsModule) {
-    utilsModule = await import('./faintly.utils.js');
-  }
-  const expr = expression.slice(11, -1); // Extract expression from utils:eval(...)
-  return utilsModule.evaluate(expr, context);
-}
-
-// In src/faintly.utils.js
-export function evaluate(expr, context) {
-  const fn = new Function('ctx', `with(ctx) { return ${expr}; }`);
-  return fn(context);
-}
-```
-
-**Supports Full JavaScript Syntax:**
-- **Comparisons**: `count > 5`, `status === 'active'`
-- **Logical operators**: `isAdmin || isModerator`, `isValid && isActive`
-- **Ternary**: `condition ? 'yes' : 'no'`
-- **Method calls**: `items.join(', ')`, `name.toUpperCase()`
-- **Array/object access**: `items[0]`, `user.profile.name`
-- **Complex expressions**: `(count > 5 && !isDisabled) || isAdmin`
-
-**Why this approach:**
-- ✅ **Appropriately scary** - `eval` in the name warns developers about what's happening
-- ✅ **Explicit and clear** - `utils:eval(expression)` is self-documenting
-- ✅ Minimal bundle impact (~100-150 bytes)
-- ✅ Full JavaScript expressiveness
-- ✅ Simple implementation, easy to maintain
-- ✅ Error handling - throws on invalid syntax
-- ✅ Supports all use cases without parser limitations
-- ✅ Future-proof - leaves room for `utils:safe()` or other utils later
-
-**Security & CSP Considerations:**
-- ⚠️ Uses `new Function()` which requires `unsafe-eval` CSP policy
-- ⚠️ Context is fully trusted - expressions have access to entire context
-- ⚠️ **Do not put untrusted user input in context** (already documented)
-- ⚠️ Templates are authored by developers (not user-generated)
-- ⚠️ If CSP blocks `unsafe-eval`, this feature cannot be used
-
-**Trade-offs:**
-- **Accepted**: CSP limitation, security responsibility on developer
-- **Benefit**: 400-500 byte savings vs custom parser
-- **Benefit**: No parser complexity or maintenance burden
-- **Benefit**: Full JavaScript power without artificial limitations
-
-**What You Can Use:**
-
-Since expressions are evaluated as JavaScript, you have access to:
-
-*Native JavaScript Operators:*
-- Comparison: `>`, `<`, `>=`, `<=`, `===`, `!==`
-- Logical: `&&`, `||`, `!`
-- Ternary: `condition ? ifTrue : ifFalse`
-- Arithmetic: `+`, `-`, `*`, `/`, `%`
-
-*Native JavaScript Methods:*
-- String: `.toUpperCase()`, `.toLowerCase()`, `.substring()`, `.trim()`, etc.
-- Array: `.join()`, `.map()`, `.filter()`, `.length`, `[index]`, etc.
-- Object: property access with `.` or `[]`
-- Global: `encodeURIComponent()`, `encodeURI()`, `parseInt()`, etc.
-
-*Optional Helper Functions:*
-You can add custom helpers to the context if needed:
-```javascript
-await renderBlock(block, {
-  items,
-  formatMessage: (name, count) => `Hello ${name}, you have ${count} messages`,
-  truncate: (str, len) => str.length > len ? str.slice(0, len) + '...' : str,
-});
-```
-```html
-<div>${utils:eval(formatMessage(user.name, messageCount))}</div>
-<p>${utils:eval(truncate(longText, 100))}</p>
-```
-
-**Implementation Steps:**
-1. Create `src/faintly.utils.js` with JavaScript evaluation function
-2. Modify `src/expressions.js` to detect `utils:eval()` syntax and dynamic import
-3. Add comprehensive tests for:
-   - Comparisons, logical operators, ternary
-   - String/array methods
-   - Complex nested expressions
-   - Error cases (syntax errors, undefined variables)
-   - Context helper functions being called
-4. Build separate `dist/faintly.utils.js` bundle
-5. Document in README with:
-   - Examples of common patterns with `utils:eval()`
-   - **Prominent warning**: Uses `eval` - understand the implications
-   - Security warnings (no untrusted input in context)
-   - CSP requirements (`unsafe-eval` policy required)
-   - When to use `utils:eval()` vs context functions
-6. Ensure bundle stays under 150 bytes (gzipped)
-
-**Error Handling:**
-- Throws JavaScript syntax errors with stack trace
-- Undefined variable errors bubble up naturally
-- Consider wrapping errors with more context (which template/directive)
-
-**Future Extensions:**
-- Optional `utils:safe()` with custom parser if users need CSP compatibility
-  - Example: `utils:safe(gt(count, 5))` - uses safe parser, no eval
-  - Would be a larger bundle but CSP-compatible
-- Additional built-in helper functions based on user feedback
-- Allow passing custom helper functions via context `utils` property
-
----
-
 ## Implementation Order
 
 1. ✅ **Standardize expression syntax** (#1) - COMPLETED
 2. **Add migration documentation** (#2) - Document completed features
+3. ✅ **JavaScript expression evaluation with `utils:eval()`** (#3) - COMPLETED
 
 ## Testing Strategy
 
diff --git a/README.md b/README.md
index 1b0f4f8..edb9997 100644
--- a/README.md
+++ b/README.md
@@ -200,7 +200,6 @@ Faintly supports a simple expression syntax for resolving data from the renderin
 **In `data-fly-*` directive attributes:**
 - Both bare expressions and `${}` wrapped expressions are supported
 - `data-fly-test="condition"` and `data-fly-test="${condition}"` both work
-- The `${}` syntax is supported for familiarity with HTL/Sightly
 
 **In `data-fly-include`, HTML text, and normal attributes:**
 - You must wrap your expression in `${}`
@@ -209,3 +208,69 @@ Faintly supports a simple expression syntax for resolving data from the renderin
 **Escaping:**
 - Use a leading backslash to prevent evaluation of an expression in text/attributes
 - Example: `\${some.value}` will remain literal `${some.value}`
+
+### JavaScript Expression Evaluation with `utils:eval()`
+
+> [!CAUTION]
+> **⚠️ This feature uses JavaScript's `Function` constructor (similar to `eval`)**
+>
+> - Requires Content Security Policy with `'unsafe-eval'` directive
+> - The entire context is accessible to evaluated expressions
+> - **Never put untrusted user input in the context** (this applies to all Faintly features)
+> - If your CSP blocks `unsafe-eval`, this feature won't work
+>
+> Use `utils:eval()` thoughtfully. For complex logic, consider context functions instead.
+
+When a bit more logic is required, you canuse `utils:eval()` to evaluate JavaScript expressions. Some examples:
+
+```html
+<!-- Comparisons -->
+<div data-fly-test="utils:eval(count > 5)">More than 5</div>
+<div data-fly-test="utils:eval(status === 'active')">Active</div>
+
+<!-- Logical operators -->
+<div data-fly-test="utils:eval(isAdmin || isModerator)">Admin or mod</div>
+<div data-fly-test="utils:eval(isValid && isActive)">Valid and active</div>
+
+<!-- Ternary operator -->
+<div>${utils:eval(showCount ? count : 'N/A')}</div>
+<div class="${utils:eval(isActive ? 'active' : 'inactive')}">Status</div>
+
+<!-- Method calls with arguments -->
+<div>${utils:eval(items.join(', '))}</div>
+<div>${utils:eval(name.substring(0, 10))}</div>
+
+<!-- String concatenation -->
+<div>${utils:eval('Hello, ' + user.name)}</div>
+
+<!-- Arithmetic -->
+<div>${utils:eval(price * quantity)}</div>
+
+<!-- Complex expressions -->
+<div data-fly-test="utils:eval((count > 5 && !isDisabled) || isAdmin)">Complex logic</div>
+```
+
+**What works WITHOUT `utils:eval()`:**
+
+```html
+<!-- Simple property paths -->
+<div>${user.name}</div>
+<div>${user.profile.email}</div>
+
+<!-- Array length -->
+<div>${items.length}</div>
+
+<!-- Array access by numeric index using dot notation -->
+<div>${items.0}</div>
+<div>${items.1}</div>
+
+<!-- Function calls without arguments (auto-called by Faintly) -->
+<div>${user.getName}</div>
+<div>${text.trim}</div>
+```
+
+**When to Use `utils:eval()` vs Context Functions:**
+
+- **Use context functions** for complex logic, API calls, or data transformations
+- **Use `utils:eval()`** for simple comparisons, formatting, or inline expressions
+- Context functions are generally safer and more maintainable for complex operations
diff --git a/dist/faintly.js b/dist/faintly.js
index 1443507..3f7f080 100644
--- a/dist/faintly.js
+++ b/dist/faintly.js
@@ -28,6 +28,10 @@ async function resolveTemplate(context) {
 }
 
 // src/expressions.js
+function evaluate(expr, context) {
+  const fn = new Function("ctx", `with(ctx) { return ${expr}; }`);
+  return fn(context);
+}
 function unwrapExpression(expression) {
   const trimmed = expression.trim();
   if (trimmed.startsWith("${") && trimmed.endsWith("}")) {
@@ -36,9 +40,14 @@ function unwrapExpression(expression) {
   return expression;
 }
 async function resolveExpression(expression, context) {
+  const trimmedExpression = expression.trim();
+  if (trimmedExpression.startsWith("utils:eval(") && trimmedExpression.endsWith(")")) {
+    const expr = trimmedExpression.slice(11, -1);
+    return evaluate(expr, context);
+  }
   let resolved = context;
   let previousResolvedValue;
-  const parts = expression.split(".");
+  const parts = trimmedExpression.split(".");
   for (let i = 0; i < parts.length; i += 1) {
     if (typeof resolved === "undefined") break;
     const part = parts[i];
@@ -52,7 +61,7 @@ async function resolveExpression(expression, context) {
   return resolved;
 }
 async function resolveExpressions(str, context) {
-  const regexp = /(\\)?\${([a-z0-9\\.\s]+)}/gi;
+  const regexp = /(\\)?\${([^}]+)}/gi;
   const promises = [];
   str.replaceAll(regexp, (match, escapeChar, expression) => {
     const replacementPromise = escapeChar ? Promise.resolve(match.slice(1)) : resolveExpression(expression.trim(), context);
diff --git a/src/expressions.js b/src/expressions.js
index 2803a45..3938ecf 100644
--- a/src/expressions.js
+++ b/src/expressions.js
@@ -1,3 +1,16 @@
+/**
+ * Evaluates a JavaScript expression in the given context.
+ * Uses Function constructor - requires 'unsafe-eval' CSP policy.
+ * @param {string} expr - The JavaScript expression to evaluate
+ * @param {object} context - The context object providing variables
+ * @returns {*} The result of evaluating the expression
+ */
+function evaluate(expr, context) {
+  // eslint-disable-next-line no-new-func
+  const fn = new Function('ctx', `with(ctx) { return ${expr}; }`);
+  return fn(context);
+}
+
 /**
  * Strips ${} wrapper from expression if present for HTL compatibility
  * @param {string} expression the expression that may be wrapped
@@ -19,10 +32,17 @@ export function unwrapExpression(expression) {
  * @returns {Promise<any>} the data that was resolved
  */
 export async function resolveExpression(expression, context) {
+  // Handle utils:eval() syntax
+  const trimmedExpression = expression.trim();
+  if (trimmedExpression.startsWith('utils:eval(') && trimmedExpression.endsWith(')')) {
+    const expr = trimmedExpression.slice(11, -1); // Extract expression from utils:eval(...)
+    return evaluate(expr, context);
+  }
+
   let resolved = context;
   let previousResolvedValue;
 
-  const parts = expression.split('.');
+  const parts = trimmedExpression.split('.');
   for (let i = 0; i < parts.length; i += 1) {
     if (typeof resolved === 'undefined') break;
 
@@ -47,7 +67,7 @@ export async function resolveExpression(expression, context) {
  * @param {Object} context the rendering context
  */
 export async function resolveExpressions(str, context) {
-  const regexp = /(\\)?\${([a-z0-9\\.\s]+)}/gi;
+  const regexp = /(\\)?\${([^}]+)}/gi;
 
   const promises = [];
   str.replaceAll(regexp, (match, escapeChar, expression) => {
diff --git a/test/expressions/operator-without-eval.test.js b/test/expressions/operator-without-eval.test.js
new file mode 100644
index 0000000..8824a14
--- /dev/null
+++ b/test/expressions/operator-without-eval.test.js
@@ -0,0 +1,139 @@
+/* eslint-env mocha */
+/* eslint-disable no-unused-expressions */
+/* eslint-disable no-template-curly-in-string */
+
+import { expect } from '@esm-bundle/chai';
+import { resolveExpression, resolveExpressions } from '../../src/expressions.js';
+
+describe('expressions with operators but without utils:eval()', () => {
+  describe('resolveExpression - property path resolution', () => {
+    it('should return undefined for comparison operator', async () => {
+      const context = { count: 10 };
+      const result = await resolveExpression('count > 5', context);
+      expect(result).to.be.undefined;
+    });
+
+    it('should return undefined for equality operator', async () => {
+      const context = { status: 'active' };
+      const result = await resolveExpression('status === "active"', context);
+      expect(result).to.be.undefined;
+    });
+
+    it('should return undefined for logical AND', async () => {
+      const context = { isValid: true, isActive: true };
+      const result = await resolveExpression('isValid && isActive', context);
+      expect(result).to.be.undefined;
+    });
+
+    it('should return undefined for logical OR', async () => {
+      const context = { isAdmin: false, isModerator: true };
+      const result = await resolveExpression('isAdmin || isModerator', context);
+      expect(result).to.be.undefined;
+    });
+
+    it('should return undefined for ternary operator', async () => {
+      const context = { showCount: true, count: 5 };
+      const result = await resolveExpression('showCount ? count : "N/A"', context);
+      expect(result).to.be.undefined;
+    });
+
+    it('should return undefined for array bracket access', async () => {
+      const context = { items: ['first', 'second'] };
+      const result = await resolveExpression('items[0]', context);
+      expect(result).to.be.undefined;
+    });
+
+    it('should return undefined for method call with parens', async () => {
+      const context = { name: 'john' };
+      const result = await resolveExpression('name.toUpperCase()', context);
+      expect(result).to.be.undefined;
+    });
+  });
+
+  describe('resolveExpressions - text content replacement', () => {
+    it('comparison without utils:eval returns undefined', async () => {
+      const context = { count: 10 };
+      const { updated, updatedText } = await resolveExpressions(
+        'Result: ${count > 5}',
+        context,
+      );
+      expect(updated).to.be.true;
+      expect(updatedText).to.equal('Result: undefined');
+    });
+
+    it('ternary without utils:eval returns undefined', async () => {
+      const context = { isActive: true };
+      const { updated, updatedText } = await resolveExpressions(
+        'Status: ${isActive ? "active" : "inactive"}',
+        context,
+      );
+      expect(updated).to.be.true;
+      expect(updatedText).to.equal('Status: undefined');
+    });
+
+    it('array access without utils:eval returns undefined', async () => {
+      const context = { items: ['apple', 'banana'] };
+      const { updated, updatedText } = await resolveExpressions(
+        'First: ${items[0]}',
+        context,
+      );
+      expect(updated).to.be.true;
+      expect(updatedText).to.equal('First: undefined');
+    });
+
+    it('method call without utils:eval returns undefined', async () => {
+      const context = { name: 'john' };
+      const { updated, updatedText } = await resolveExpressions(
+        'Name: ${name.toUpperCase()}',
+        context,
+      );
+      expect(updated).to.be.true;
+      expect(updatedText).to.equal('Name: undefined');
+    });
+
+    it('should handle mixed expressions with undefined for operators', async () => {
+      const context = { a: 5, b: 3, result: 8 };
+      const { updated, updatedText } = await resolveExpressions(
+        'Calc: ${a + b} = ${result}',
+        context,
+      );
+      expect(updated).to.be.true;
+      // First expression (a + b) returns undefined, second (result) resolves to 8
+      expect(updatedText).to.equal('Calc: undefined = 8');
+    });
+
+    it('should work correctly WITH utils:eval wrapper', async () => {
+      const context = { count: 10 };
+      const { updated, updatedText } = await resolveExpressions(
+        'Result: ${utils:eval(count > 5)}',
+        context,
+      );
+      expect(updated).to.be.true;
+      expect(updatedText).to.equal('Result: true');
+    });
+  });
+
+  describe('escaped expressions - consistent behavior', () => {
+    it('escaped expression with operators removes backslash consistently', async () => {
+      const context = { count: 10 };
+      const { updated, updatedText } = await resolveExpressions(
+        'Literal: \\${count > 5}',
+        context,
+      );
+      // Matches and escapes consistently - backslash removed
+      expect(updated).to.be.true;
+      expect(updatedText).to.equal('Literal: ${count > 5}');
+    });
+
+    it('escaped simple expression removes backslash', async () => {
+      const context = { count: 10 };
+      const { updated, updatedText } = await resolveExpressions(
+        'Literal: \\${count}',
+        context,
+      );
+      // Escape handling removes backslash
+      expect(updated).to.be.true;
+      expect(updatedText).to.equal('Literal: ${count}');
+    });
+  });
+});
diff --git a/test/expressions/utils-eval.test.js b/test/expressions/utils-eval.test.js
new file mode 100644
index 0000000..87aeb17
--- /dev/null
+++ b/test/expressions/utils-eval.test.js
@@ -0,0 +1,386 @@
+/* eslint-env mocha */
+/* eslint-disable no-unused-expressions */
+
+import { expect } from '@esm-bundle/chai';
+import { resolveExpression } from '../../src/expressions.js';
+
+describe('utils:eval() expression evaluation', () => {
+  describe('comparisons', () => {
+    it('should evaluate greater than', async () => {
+      const context = { count: 10 };
+      const result = await resolveExpression('utils:eval(count > 5)', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should evaluate less than', async () => {
+      const context = { count: 3 };
+      const result = await resolveExpression('utils:eval(count < 5)', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should evaluate greater than or equal', async () => {
+      const context = { count: 5 };
+      const result = await resolveExpression('utils:eval(count >= 5)', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should evaluate less than or equal', async () => {
+      const context = { count: 5 };
+      const result = await resolveExpression('utils:eval(count <= 5)', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should evaluate strict equality', async () => {
+      const context = { status: 'active' };
+      const result = await resolveExpression('utils:eval(status === "active")', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should evaluate strict inequality', async () => {
+      const context = { status: 'active' };
+      const result = await resolveExpression('utils:eval(status !== "disabled")', context);
+      expect(result).to.equal(true);
+    });
+  });
+
+  describe('logical operators', () => {
+    it('should evaluate AND operator', async () => {
+      const context = { isValid: true, isActive: true };
+      const result = await resolveExpression('utils:eval(isValid && isActive)', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should evaluate OR operator', async () => {
+      const context = { isAdmin: false, isModerator: true };
+      const result = await resolveExpression('utils:eval(isAdmin || isModerator)', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should evaluate NOT operator', async () => {
+      const context = { isDisabled: false };
+      const result = await resolveExpression('utils:eval(!isDisabled)', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should evaluate complex logical expression', async () => {
+      const context = { count: 10, isDisabled: false, isAdmin: true };
+      const result = await resolveExpression('utils:eval((count > 5 && !isDisabled) || isAdmin)', context);
+      expect(result).to.equal(true);
+    });
+  });
+
+  describe('ternary operator', () => {
+    it('should evaluate ternary with true condition', async () => {
+      const context = { showCount: true, count: 5 };
+      const result = await resolveExpression('utils:eval(showCount ? count : "N/A")', context);
+      expect(result).to.equal(5);
+    });
+
+    it('should evaluate ternary with false condition', async () => {
+      const context = { showCount: false, count: 5 };
+      const result = await resolveExpression('utils:eval(showCount ? count : "N/A")', context);
+      expect(result).to.equal('N/A');
+    });
+
+    it('should evaluate nested ternary', async () => {
+      const context = { status: 'active' };
+      const result = await resolveExpression('utils:eval(status === "active" ? "green" : status === "pending" ? "yellow" : "red")', context);
+      expect(result).to.equal('green');
+    });
+  });
+
+  describe('string methods', () => {
+    it('should call toUpperCase', async () => {
+      const context = { name: 'john' };
+      const result = await resolveExpression('utils:eval(name.toUpperCase())', context);
+      expect(result).to.equal('JOHN');
+    });
+
+    it('should call toLowerCase', async () => {
+      const context = { name: 'JOHN' };
+      const result = await resolveExpression('utils:eval(name.toLowerCase())', context);
+      expect(result).to.equal('john');
+    });
+
+    it('should call substring', async () => {
+      const context = { text: 'hello world' };
+      const result = await resolveExpression('utils:eval(text.substring(0, 5))', context);
+      expect(result).to.equal('hello');
+    });
+
+    it('should call trim', async () => {
+      const context = { text: '  hello  ' };
+      const result = await resolveExpression('utils:eval(text.trim())', context);
+      expect(result).to.equal('hello');
+    });
+
+    it('should concatenate strings', async () => {
+      const context = { firstName: 'John', lastName: 'Doe' };
+      const result = await resolveExpression('utils:eval(firstName + " " + lastName)', context);
+      expect(result).to.equal('John Doe');
+    });
+  });
+
+  describe('array methods', () => {
+    it('should call join', async () => {
+      const context = { items: ['apple', 'banana', 'cherry'] };
+      const result = await resolveExpression('utils:eval(items.join(", "))', context);
+      expect(result).to.equal('apple, banana, cherry');
+    });
+
+    it('should access array by index', async () => {
+      const context = { items: ['first', 'second', 'third'] };
+      const result = await resolveExpression('utils:eval(items[0])', context);
+      expect(result).to.equal('first');
+    });
+
+    it('should access array length', async () => {
+      const context = { items: [1, 2, 3, 4, 5] };
+      const result = await resolveExpression('utils:eval(items.length)', context);
+      expect(result).to.equal(5);
+    });
+
+    it('should call map', async () => {
+      const context = { numbers: [1, 2, 3] };
+      const result = await resolveExpression('utils:eval(numbers.map(n => n * 2))', context);
+      expect(result).to.deep.equal([2, 4, 6]);
+    });
+
+    it('should call filter', async () => {
+      const context = { numbers: [1, 2, 3, 4, 5] };
+      const result = await resolveExpression('utils:eval(numbers.filter(n => n > 3))', context);
+      expect(result).to.deep.equal([4, 5]);
+    });
+  });
+
+  describe('object access', () => {
+    it('should access nested property', async () => {
+      const context = { user: { profile: { name: 'John' } } };
+      const result = await resolveExpression('utils:eval(user.profile.name)', context);
+      expect(result).to.equal('John');
+    });
+
+    it('should access property with bracket notation', async () => {
+      const context = { user: { name: 'John' } };
+      const result = await resolveExpression('utils:eval(user["name"])', context);
+      expect(result).to.equal('John');
+    });
+
+    it('should access dynamic property', async () => {
+      const context = { user: { name: 'John' }, key: 'name' };
+      const result = await resolveExpression('utils:eval(user[key])', context);
+      expect(result).to.equal('John');
+    });
+  });
+
+  describe('arithmetic operations', () => {
+    it('should perform addition', async () => {
+      const context = { a: 5, b: 3 };
+      const result = await resolveExpression('utils:eval(a + b)', context);
+      expect(result).to.equal(8);
+    });
+
+    it('should perform subtraction', async () => {
+      const context = { a: 5, b: 3 };
+      const result = await resolveExpression('utils:eval(a - b)', context);
+      expect(result).to.equal(2);
+    });
+
+    it('should perform multiplication', async () => {
+      const context = { a: 5, b: 3 };
+      const result = await resolveExpression('utils:eval(a * b)', context);
+      expect(result).to.equal(15);
+    });
+
+    it('should perform division', async () => {
+      const context = { a: 10, b: 2 };
+      const result = await resolveExpression('utils:eval(a / b)', context);
+      expect(result).to.equal(5);
+    });
+
+    it('should perform modulo', async () => {
+      const context = { a: 10, b: 3 };
+      const result = await resolveExpression('utils:eval(a % b)', context);
+      expect(result).to.equal(1);
+    });
+  });
+
+  describe('global functions', () => {
+    it('should call encodeURIComponent', async () => {
+      const context = { url: 'hello world' };
+      const result = await resolveExpression('utils:eval(encodeURIComponent(url))', context);
+      expect(result).to.equal('hello%20world');
+    });
+
+    it('should call parseInt', async () => {
+      const context = { str: '42' };
+      const result = await resolveExpression('utils:eval(parseInt(str))', context);
+      expect(result).to.equal(42);
+    });
+
+    it('should call parseFloat', async () => {
+      const context = { str: '3.14' };
+      const result = await resolveExpression('utils:eval(parseFloat(str))', context);
+      expect(result).to.equal(3.14);
+    });
+  });
+
+  describe('custom helper functions', () => {
+    it('should call custom helper function', async () => {
+      const context = {
+        name: 'John',
+        count: 5,
+        formatMessage: (n, c) => `Hello ${n}, you have ${c} messages`,
+      };
+      const result = await resolveExpression('utils:eval(formatMessage(name, count))', context);
+      expect(result).to.equal('Hello John, you have 5 messages');
+    });
+
+    it('should call custom truncate function', async () => {
+      const context = {
+        text: 'This is a very long text',
+        truncate: (str, len) => (str.length > len ? `${str.slice(0, len)}...` : str),
+      };
+      const result = await resolveExpression('utils:eval(truncate(text, 10))', context);
+      expect(result).to.equal('This is a ...');
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw error for undefined variable', async () => {
+      const context = {};
+      try {
+        await resolveExpression('utils:eval(undefinedVariable)', context);
+        expect.fail('should have thrown error');
+      } catch (error) {
+        expect(error).to.be.instanceOf(ReferenceError);
+      }
+    });
+
+    it('should throw error for syntax error', async () => {
+      const context = { count: 5 };
+      try {
+        await resolveExpression('utils:eval(count > )', context);
+        expect.fail('should have thrown error');
+      } catch (error) {
+        expect(error).to.be.instanceOf(SyntaxError);
+      }
+    });
+
+    it('should throw error for invalid expression', async () => {
+      const context = { count: 5 };
+      try {
+        await resolveExpression('utils:eval(count..invalid)', context);
+        expect.fail('should have thrown error');
+      } catch (error) {
+        expect(error).to.be.instanceOf(SyntaxError);
+      }
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty expression', async () => {
+      const context = {};
+      const result = await resolveExpression('utils:eval()', context);
+      expect(result).to.be.undefined;
+    });
+
+    it('should handle whitespace in expression', async () => {
+      const context = { count: 10 };
+      const result = await resolveExpression('utils:eval(  count > 5  )', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should handle null values', async () => {
+      const context = { value: null };
+      const result = await resolveExpression('utils:eval(value === null)', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should handle undefined values', async () => {
+      const context = { value: undefined };
+      const result = await resolveExpression('utils:eval(value === undefined)', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should handle boolean values', async () => {
+      const context = { isTrue: true, isFalse: false };
+      const result = await resolveExpression('utils:eval(isTrue && !isFalse)', context);
+      expect(result).to.equal(true);
+    });
+  });
+
+  describe('whitespace handling', () => {
+    it('should handle leading whitespace before utils:eval', async () => {
+      const context = { count: 10 };
+      const result = await resolveExpression('  utils:eval(count > 5)', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should handle trailing whitespace after closing paren', async () => {
+      const context = { count: 10 };
+      const result = await resolveExpression('utils:eval(count > 5)  ', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should handle whitespace on both sides', async () => {
+      const context = { count: 10 };
+      const result = await resolveExpression('  utils:eval(count > 5)  ', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should handle tabs and spaces', async () => {
+      const context = { count: 10 };
+      const result = await resolveExpression('\t  utils:eval(count > 5)  \t', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should handle expression with many spaces', async () => {
+      const context = { a: 5, b: 3, c: 2 };
+      const result = await resolveExpression('utils:eval(  a   +   b   *   c  )', context);
+      expect(result).to.equal(11); // 5 + (3 * 2) = 11
+    });
+
+    it('should handle complex expression with internal whitespace', async () => {
+      const context = { count: 10, isDisabled: false, isAdmin: true };
+      const result = await resolveExpression('utils:eval( ( count > 5 && ! isDisabled ) || isAdmin )', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should NOT match if space between utils:eval and opening paren', async () => {
+      const context = { count: 10 };
+      // Should not match utils:eval() syntax, tries to resolve as property path
+      const result = await resolveExpression('utils:eval (count > 5)', context);
+      expect(result).to.be.undefined; // Tries to resolve as property path, returns undefined
+    });
+  });
+
+  describe('complex real-world scenarios', () => {
+    it('should handle admin or moderator check', async () => {
+      const context = { user: { isAdmin: false, isModerator: true } };
+      const result = await resolveExpression('utils:eval(user.isAdmin || user.isModerator)', context);
+      expect(result).to.equal(true);
+    });
+
+    it('should handle item count with plural formatting', async () => {
+      const context = {
+        items: [1, 2, 3],
+        formatCount: (arr) => `${arr.length} item${arr.length !== 1 ? 's' : ''}`,
+      };
+      const result = await resolveExpression('utils:eval(formatCount(items))', context);
+      expect(result).to.equal('3 items');
+    });
+
+    it('should handle conditional CSS class', async () => {
+      const context = { isActive: true };
+      const result = await resolveExpression('utils:eval(isActive ? "active" : "inactive")', context);
+      expect(result).to.equal('active');
+    });
+
+    it('should handle status badge logic', async () => {
+      const context = { status: 'pending' };
+      const result = await resolveExpression('utils:eval(status === "active" ? "green" : status === "pending" ? "yellow" : "red")', context);
+      expect(result).to.equal('yellow');
+    });
+  });
+});

From 75354fb6f5789ea0470afd6a3dc67d9907b8881b Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Wed, 29 Oct 2025 17:16:50 -0700
Subject: [PATCH 05/13] docs: add HTL/Sightly migration guide

- Created comprehensive HTL_MIGRATION.md in docs/ folder
- Added quick reference section at top with syntax and directive mappings
- Documented key differences between HTL and Faintly
- Covered expression syntax, backend integration, context options
- Included 6 common migration patterns with examples
- Added link to migration guide in README.md
- Removed HTL_COMPATIBILITY_PLAN.md (implementation complete)
---
 HTL_COMPATIBILITY_PLAN.md | 166 -------------
 README.md                 |   4 +
 docs/HTL_MIGRATION.md     | 485 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 489 insertions(+), 166 deletions(-)
 delete mode 100644 HTL_COMPATIBILITY_PLAN.md
 create mode 100644 docs/HTL_MIGRATION.md

diff --git a/HTL_COMPATIBILITY_PLAN.md b/HTL_COMPATIBILITY_PLAN.md
deleted file mode 100644
index 8db91db..0000000
--- a/HTL_COMPATIBILITY_PLAN.md
+++ /dev/null
@@ -1,166 +0,0 @@
-# HTL/Sightly Compatibility Improvements Plan
-
-This document outlines planned improvements to make Faintly easier to use for developers with HTL/Sightly background.
-
-## Implementation Priority
-
-### ✅ Completed
-
-#### 1. Standardize Expression Syntax (Refined) - ✅ IMPLEMENTED
-Make `${}` optional in `data-fly-*` directives for consistency with HTL.
-
-**Current behavior:**
-- `${}` required in text content and regular attributes (explicit evaluation)
-- Bare expressions in `data-fly-*` directive values
-
-**Proposed behavior:**
-- **In `data-fly-*` directives**: Accept both `${expression}` and bare `expression`
-- **In regular attributes and text**: Keep `${}` required (current behavior - efficient and explicit)
-
-**Why this approach:**
-- Avoids evaluating every attribute value (performance concern)
-- No ambiguity - `${}` explicitly marks what should be evaluated
-- Provides HTL-like feel where it matters (directives)
-- Maintains backward compatibility
-
-**Examples:**
-```html
-<!-- Both should work in directives -->
-<div data-fly-test="user.isAdmin">
-<div data-fly-test="${user.isAdmin}">
-
-<!-- Regular attributes still require ${} (unchanged) -->
-<a href="${link}">Link</a>
-<div class="card-${index}">Content</div>
-
-<!-- Text content still requires ${} (unchanged) -->
-<p>Hello ${user.name}</p>
-```
-
-**Implementation notes:**
-- Modify directive processing functions in `directives.js` to strip `${}` wrapper if present
-- Only affects `data-fly-*` attribute value parsing
-- Ensure backward compatibility with existing code
-- Update tests to cover both syntaxes in directives
-- Update README.md to document both syntaxes are supported in directives
-
-**Implementation Results:**
-- ✅ Added `unwrapExpression()` function in `src/expressions.js`
-- ✅ Applied unwrapping to all directive processors: `processTest`, `processRepeat`, `processContent`, `processAttributes`, `resolveUnwrap`
-- ✅ Added 13 comprehensive tests for `unwrapExpression()`
-- ✅ Added 9 integration tests for `${}` syntax across all directive types
-- ✅ Updated README Expressions section with clear documentation
-- ✅ 117 tests passing with 100% coverage maintained
-- ✅ Bundle size: 2729 bytes core (actually 1 byte smaller!)
-- ✅ All directives now support both syntaxes: `data-fly-test="condition"` and `data-fly-test="${condition}"`
-- ✅ Committed in commit `1a21b8f`
-
----
-
-#### 3. JavaScript Expression Evaluation with `utils:eval()` - ✅ IMPLEMENTED
-Add JavaScript expression evaluation using `utils:eval()` syntax for complex logic and operations.
-
-**Implementation Results:**
-- ✅ Added `evaluate()` function directly in `src/expressions.js` (kept internal, no separate bundle needed)
-- ✅ Modified `resolveExpression()` to detect and handle `utils:eval()` syntax
-- ✅ Updated regex pattern in `resolveExpressions()` to support complex expressions (`/(\\)?\${([^}]+)}/gi`)
-- ✅ Added 70 comprehensive tests covering:
-  - Comparisons (`>`, `<`, `>=`, `<=`, `===`, `!==`)
-  - Logical operators (`&&`, `||`, `!`)
-  - Ternary operator
-  - String methods (`.toUpperCase()`, `.toLowerCase()`, `.substring()`, `.trim()`, concatenation)
-  - Array methods (`.join()`, `.map()`, `.filter()`, `.length`, index access)
-  - Object access (nested properties, bracket notation, dynamic properties)
-  - Arithmetic operations (`+`, `-`, `*`, `/`, `%`)
-  - Global functions (`encodeURIComponent()`, `parseInt()`, `parseFloat()`)
-  - Custom helper functions from context
-  - Error handling (undefined variables, syntax errors)
-  - Edge cases (empty expression, whitespace, null, undefined, booleans)
-  - Real-world scenarios (admin checks, plural formatting, conditional CSS classes, status badges)
-- ✅ Updated README with comprehensive documentation including:
-  - Usage examples for all primary use cases
-  - List of supported operators and methods
-  - Custom helper function examples
-  - **Prominent CAUTION warning** about eval and CSP requirements
-  - Guidance on when to use `utils:eval()` vs context functions
-- ✅ 165 tests passing (70 new tests added) with 100% coverage maintained
-- ✅ Bundle size: 2804 bytes core (only 75 bytes increase!), 3450 bytes combined
-- ✅ All constraints met: under 4KB core limit, under 6KB combined limit
-- ✅ Lint passed, build passed
-
----
-
-### 🚧 To Implement
-
-#### 2. Add HTL Migration Documentation
-Create a dedicated doc linked from README.md with side-by-side comparisons.
-
-**Content to include:**
-- Directive comparison table (HTL vs Faintly)
-- Expression syntax differences
-- Backend integration comparison (`data-sly-use` vs context object)
-  - **Important**: Explain that `data-sly-use` is replaced by context functions
-  - Show how Faintly's automatic function calling provides lazy/conditional loading
-  - Example: `data-fly-content="fetchArticles"` automatically calls the function
-- Context options (`@ context='uri'`) and why they're not needed in Faintly
-  - HTL needs context-aware escaping because it generates HTML strings server-side
-  - Faintly manipulates DOM directly - browser handles escaping automatically
-  - Faintly's security module provides attribute/URL validation without needing context options
-- Common patterns and their equivalents
-- Migration examples from typical HTL components
-
-**Example table:**
-| HTL/Sightly | Faintly | Description |
-|-------------|---------|-------------|
-| `data-sly-test` | `data-fly-test` | Conditional rendering |
-| `data-sly-list` | `data-fly-repeat` | Iteration |
-| `data-sly-use` | context object | Backend integration |
-| `data-sly-template` | `<template data-fly-name>` | Named templates |
-| `data-sly-call` | `data-fly-include` | Template includes |
-| `data-sly-unwrap` | `data-fly-unwrap` | Remove wrapper element |
-| `data-sly-attribute` | `data-fly-attributes` | Set attributes dynamically |
-
----
-
-## Implementation Order
-
-1. ✅ **Standardize expression syntax** (#1) - COMPLETED
-2. **Add migration documentation** (#2) - Document completed features
-3. ✅ **JavaScript expression evaluation with `utils:eval()`** (#3) - COMPLETED
-
-## Testing Strategy
-
-- Maintain 100% code coverage
-- Add tests for both old and new syntax (backward compatibility)
-- Add integration tests showing HTL migration patterns
-- Performance tests to ensure no regression
-
-## Bundle Size Constraints
-
-- Core bundle limit: 4KB / 4096 bytes (gzipped)
-- Combined limit: 6KB / 6144 bytes (gzipped)
-- Each feature must be evaluated for size impact
-- May need to optimize existing code if approaching limits
-
----
-
-## HTL/Sightly Comparison Summary
-
-### Similarities
-- HTML5 data attributes for directives
-- Security-first approach with XSS protection
-- Separation of concerns (logic vs markup)
-- Expression-based templating
-- Conditional rendering and iteration
-- Template reuse and composition
-
-### Key Differences
-- **Execution context**: HTL is server-side (Java/Sling), Faintly is client-side (JavaScript)
-- **Directive prefix**: `data-sly-*` vs `data-fly-*`
-- **Backend integration**: HTL uses `data-sly-use`, Faintly uses context object
-- **Iteration**: `data-sly-list` vs `data-fly-repeat`
-- **Expression syntax**: HTL always uses `${}`, Faintly now supports both `${}` and bare expressions in directives
-
-### Target Outcome
-Make Faintly feel natural to HTL developers while maintaining its lightweight, client-side focus.
-
diff --git a/README.md b/README.md
index edb9997..6a0c76d 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,10 @@ I've always liked the developer ergonomics (autocomplete, etc.) and separation o
 
 I've experimented with other existing libraries (ejs templates, etc.) but wanted something simple and purpose built.
 
+## Migrating from HTL/Sightly?
+
+If you're coming from Adobe Experience Manager's HTL (HTML Template Language), check out **[HTL Migration Guide](./docs/HTL_MIGRATION.md)** for side-by-side comparisons.
+
 ## Getting Started
 
 1. Copy the `/dist/faintly.js` and `/dist/faintly.security.js` files to the scripts directory of your project
diff --git a/docs/HTL_MIGRATION.md b/docs/HTL_MIGRATION.md
new file mode 100644
index 0000000..87f0d40
--- /dev/null
+++ b/docs/HTL_MIGRATION.md
@@ -0,0 +1,485 @@
+# Migrating from HTL/Sightly to Faintly
+
+This guide helps developers familiar with Adobe Experience Manager's HTL (HTML Template Language, formerly Sightly) transition to using Faintly for client-side templating in AEM Edge Delivery Services.
+
+## Table of Contents
+
+- [Quick Reference](#quick-reference)
+- [Overview](#overview)
+- [Key Differences](#key-differences)
+- [Expression Syntax](#expression-syntax)
+- [Backend Integration](#backend-integration)
+- [Context Options](#context-options)
+- [Common Patterns](#common-patterns)
+
+---
+
+## Quick Reference
+
+### Syntax Cheat Sheet
+
+| Feature | HTL | Faintly |
+|---------|-----|---------|
+| **Text expression** | `${variable}` | `${variable}` |
+| **Directive expression** | `${variable}` | `variable` or `${variable}` |
+| **Comparison** | `${a > b}` (Java) | `utils:eval(a > b)` (JavaScript) |
+| **Ternary** | `${condition ? 'yes' : 'no'}` | `${utils:eval(condition ? 'yes' : 'no')}` |
+| **Logical NOT** | `${!condition}` | `data-fly-not="condition"` or `utils:eval(!condition)` |
+
+### Directive Mapping
+
+| HTL/Sightly | Faintly |
+|-------------|---------|
+| `data-sly-test` | `data-fly-test` |
+| `data-sly-test` (negated) | `data-fly-not` |
+| `data-sly-list` / `data-sly-repeat` | `data-fly-repeat` |
+| `data-sly-use` | Functions in context object |
+| `data-sly-text` | `data-fly-content` |
+| `data-sly-attribute` | `data-fly-attributes` |
+| `data-sly-unwrap` | `data-fly-unwrap` |
+| `data-sly-template` | `<template data-fly-name>` |
+| `data-sly-call` | `data-fly-include` |
+| `data-sly-include` | `data-fly-include` |
+| `<sly>` tag | Any element with `data-fly-unwrap` |
+| `data-sly-element` | Not needed |
+| `data-sly-resource` | Not applicable |
+
+### Key Differences
+
+1. ✅ **Directive prefix changes**: `data-sly-*` → `data-fly-*`
+2. ✅ **`${}` optional in directives**: Both `data-fly-test="expr"` and `data-fly-test="${expr}"` work
+3. ✅ **Inverse conditions made easy**: Use `data-fly-not="condition"` instead of negating with `!`
+4. ✅ **Use `utils:eval()` for complex expressions**: Comparisons, ternary, logical operators
+5. ✅ **Template logic via context**: Replace `data-sly-use` with JavaScript functions in context object
+6. ✅ **Functions auto-called**: Faintly automatically calls functions in expressions for lazy/conditional loading
+7. ✅ **No context options needed**: DOM manipulation handles escaping automatically
+8. ✅ **Client-side execution**: Templates render in browser, not server
+
+---
+
+## Overview
+
+### Similarities
+
+Both HTL and Faintly share core philosophies:
+
+- ✅ **HTML5 data attributes** for directives
+- ✅ **Security-first** approach with XSS protection
+- ✅ **Separation of concerns** (logic vs markup)
+- ✅ **Expression-based** templating
+- ✅ **Conditional rendering** and iteration
+- ✅ **Template reuse** and composition
+
+### Key Differences
+
+| Aspect | HTL/Sightly | Faintly |
+|--------|-------------|---------|
+| **Execution** | Server-side (Java/Sling) | Client-side (JavaScript) |
+| **Expression Context** | Server-side Java objects | Client-side JavaScript objects |
+| **Dynamic Loading** | Server renders complete HTML | Client renders from templates |
+
+---
+
+## Expression Syntax
+
+### HTL Expression Syntax
+
+HTL always requires `${}` wrapper:
+
+```html
+<!-- HTL -->
+<div data-sly-test="${user.isAdmin}">Admin Panel</div>
+<p>${user.name}</p>
+<a href="${user.profileUrl}">Profile</a>
+```
+
+### Faintly Expression Syntax
+
+Faintly supports **two syntaxes** depending on context:
+
+#### In Directives (Optional `${}`)
+
+Both syntaxes work in `data-fly-*` directives:
+
+```html
+<!-- Both work in Faintly directives -->
+<div data-fly-test="user.isAdmin">Admin Panel</div>
+<div data-fly-test="${user.isAdmin}">Admin Panel</div>
+
+<ul data-fly-repeat="items">
+<ul data-fly-repeat="${items}">
+```
+
+#### In Text Content and Regular Attributes (Required `${}`)
+
+```html
+<!-- Faintly requires ${} in regular attributes and text -->
+<p>Hello ${user.name}</p>
+<a href="${user.profileUrl}">Profile</a>
+<div class="card-${index}">Content</div>
+```
+
+### JavaScript Expressions with `utils:eval()`
+
+Faintly supports complex JavaScript expressions using `utils:eval()`:
+
+```html
+<!-- HTL uses Java expressions -->
+<div data-sly-test="${user.age >= 18}">Adult Content</div>
+
+<!-- Faintly uses JavaScript expressions -->
+<div data-fly-test="utils:eval(user.age >= 18)">Adult Content</div>
+<p>Status: ${utils:eval(count === 1 ? 'item' : 'items')}</p>
+<span class="${utils:eval(user.role === 'admin' ? 'badge-red' : 'badge-blue')}"></span>
+```
+
+**Supported operations:**
+- Comparisons: `>`, `<`, `>=`, `<=`, `===`, `!==`
+- Logical: `&&`, `||`, `!`
+- Ternary: `condition ? true : false`
+- Arithmetic: `+`, `-`, `*`, `/`, `%`
+- String methods: `.toUpperCase()`, `.toLowerCase()`, `.substring()`, `.trim()`
+- Array methods: `.join()`, `.map()`, `.filter()`, `.length`, index access
+- Object access: nested properties, bracket notation
+
+⚠️ **CAUTION**: `utils:eval()` uses JavaScript `eval()`. Only use with trusted data. Requires CSP to allow `'unsafe-eval'`. For untrusted data, use context functions instead.
+
+---
+
+## Backend Integration
+
+### HTL: `data-sly-use`
+
+In HTL, backend integration uses `data-sly-use` to load Java classes or Sling Models:
+
+```html
+<!-- HTL backend integration -->
+<div data-sly-use.model="com.example.models.ArticleModel">
+  <h1>${model.title}</h1>
+  <p>${model.description}</p>
+</div>
+
+<!-- HTL with JavaScript use-API -->
+<div data-sly-use.articles="articles.js">
+  <ul data-sly-list="${articles.list}">
+    <li>${item.title}</li>
+  </ul>
+</div>
+```
+
+### Faintly: Context Object
+
+Faintly uses a JavaScript context object passed to `renderBlock()`:
+
+```javascript
+// Faintly backend integration
+import { renderBlock } from './faintly.js';
+
+// Context object with data and functions
+const context = {
+  title: 'Article Title',
+  description: 'Article description',
+  articles: fetchArticles(), // Can be sync data
+  loadMore: () => fetchMoreArticles(), // Or async functions
+};
+
+const block = document.querySelector('.article-block');
+renderBlock(block, context);
+```
+
+```html
+<!-- Faintly template using context -->
+<div class="article-block">
+  <h1>${title}</h1>
+  <p>${description}</p>
+  
+  <ul data-fly-repeat="articles">
+    <li>${item.title}</li>
+  </ul>
+</div>
+```
+
+### Automatic Function Calling
+
+Faintly automatically calls functions in expressions, enabling **lazy/conditional loading**:
+
+```html
+<!-- Function called only if condition is true -->
+<div data-fly-test="user.isAdmin">
+  <ul data-fly-repeat="fetchAdminData">
+    <li>${item.name}</li>
+  </ul>
+</div>
+```
+
+```javascript
+const context = {
+  user: { isAdmin: true },
+  // This function only executes if user.isAdmin is true
+  fetchAdminData: () => fetch('/api/admin-data').then(r => r.json()),
+};
+```
+
+### Migration Strategy
+
+**HTL pattern:**
+```html
+<div data-sly-use.userService="com.example.UserService">
+  <p>${userService.userName}</p>
+</div>
+```
+
+**Faintly equivalent:**
+```javascript
+// In your block's JavaScript
+import { renderBlock } from './faintly.js';
+
+const context = {
+  userName: getUserName(), // Direct function call
+  // or
+  user: { name: getUserName() },
+};
+
+renderBlock(block, context);
+```
+
+```html
+<!-- In your block's HTML -->
+<div class="user-block">
+  <p>${userName}</p>
+</div>
+```
+
+---
+
+## Context Options
+
+### HTL Context Options
+
+HTL uses context options (`@ context`) for context-aware escaping:
+
+```html
+<!-- HTL context-aware escaping -->
+<a href="${link.url @ context='uri'}">Link</a>
+<div class="${cssClass @ context='styleToken'}">Content</div>
+<script>var data = ${jsonData @ context='unsafe'};</script>
+```
+
+**Available contexts in HTL:**
+- `text` (default) - Plain text
+- `html` - HTML content
+- `attribute` - HTML attribute
+- `uri` - URL/URI
+- `number` - Numeric value
+- `elementName` - HTML element name
+- `attributeName` - HTML attribute name
+- `scriptToken` - JavaScript token
+- `styleToken` - CSS token
+- `unsafe` - No escaping (dangerous)
+
+### Why Faintly Doesn't Need Context Options
+
+Faintly doesn't require context options because:
+
+1. **DOM Manipulation vs String Generation**
+   - HTL generates HTML strings server-side → needs context-aware string escaping
+   - Faintly manipulates DOM directly → browser handles escaping automatically
+
+2. **Built-in Browser Security**
+   - Setting `.textContent` automatically escapes HTML
+   - Setting `.setAttribute()` handles attribute escaping
+   - DOM APIs provide built-in XSS protection
+
+3. **Security Module**
+   - Faintly's security module validates attributes and URLs
+   - Same-origin enforcement for URLs
+   - Dangerous attribute blocking
+   - No string-based escaping needed
+
+### Migration Examples
+
+**HTL:**
+```html
+<a href="${article.url @ context='uri'}" 
+   title="${article.title @ context='attribute'}">
+  ${article.name @ context='text'}
+</a>
+```
+
+**Faintly (no context needed):**
+```html
+<a href="${article.url}" title="${article.title}">
+  ${article.name}
+</a>
+```
+
+The browser automatically handles proper escaping for each context (URL, attribute, text).
+
+---
+
+## Common Patterns
+
+### Pattern 1: Conditional Rendering
+
+**HTL:**
+```html
+<div data-sly-test="${user.isLoggedIn}">
+  <p>Welcome, ${user.name}</p>
+</div>
+<div data-sly-test="${!user.isLoggedIn}">
+  <p>Please log in</p>
+</div>
+```
+
+**Faintly:**
+```html
+<div data-fly-test="user.isLoggedIn">
+  <p>Welcome, ${user.name}</p>
+</div>
+
+<!-- Option 1: Using data-fly-not (cleaner) -->
+<div data-fly-not="user.isLoggedIn">
+  <p>Please log in</p>
+</div>
+
+<!-- Option 2: Using utils:eval for negation -->
+<div data-fly-test="utils:eval(!user.isLoggedIn)">
+  <p>Please log in</p>
+</div>
+```
+
+### Pattern 2: List Iteration
+
+**HTL:**
+```html
+<ul data-sly-list.article="${articles}">
+  <li>
+    <h3>${article.title}</h3>
+    <p>${article.description}</p>
+  </li>
+</ul>
+```
+
+**Faintly:**
+```html
+<!-- Using default 'item' name -->
+<ul data-fly-repeat="articles">
+  <li>
+    <h3>${item.title}</h3>
+    <p>${item.description}</p>
+  </li>
+</ul>
+
+<!-- Or using named repeat (closer to HTL) -->
+<ul data-fly-repeat.article="articles">
+  <li>
+    <h3>${article.title}</h3>
+    <p>${article.description}</p>
+  </li>
+</ul>
+```
+
+### Pattern 3: Conditional CSS Classes
+
+**HTL:**
+```html
+<div class="card ${item.featured ? 'card--featured' : ''}">
+  Content
+</div>
+```
+
+**Faintly:**
+```html
+<div class="card ${utils:eval(item.featured ? 'card--featured' : '')}">
+  Content
+</div>
+
+<!-- Or using data-fly-attributes -->
+<div class="card" 
+     data-fly-attributes="${utils:eval(item.featured ? {class: 'card card--featured'} : {})}">
+  Content
+</div>
+```
+
+### Pattern 4: Dynamic Attributes
+
+**HTL:**
+```html
+<a data-sly-attribute.href="${link.url}" 
+   data-sly-attribute.target="${link.external ? '_blank' : '_self'}">
+  ${link.text}
+</a>
+```
+
+**Faintly:**
+```html
+<a href="${link.url}" 
+   target="${utils:eval(link.external ? '_blank' : '_self')}">
+  ${link.text}
+</a>
+
+<!-- Or using data-fly-attributes for multiple attributes -->
+<a data-fly-attributes="{href: link.url, target: link.target}">
+  ${link.text}
+</a>
+```
+
+### Pattern 5: Template Reuse
+
+**HTL:**
+```html
+<!-- Define template -->
+<template data-sly-template.card="${@ title, description}">
+  <div class="card">
+    <h3>${title}</h3>
+    <p>${description}</p>
+  </div>
+</template>
+
+<!-- Call template -->
+<div data-sly-call="${card @ title=article.title, description=article.desc}"></div>
+```
+
+**Faintly:**
+```html
+<!-- Define template -->
+<template data-fly-name="card">
+  <div class="card">
+    <h3>${title}</h3>
+    <p>${description}</p>
+  </div>
+</template>
+
+<!-- Include template -->
+<div data-fly-include="card" data-fly-attributes="{title: article.title, description: article.desc}"></div>
+```
+
+### Pattern 6: Unwrap Utility Elements
+
+**HTL:**
+```html
+<!-- Using sly tag (auto-unwraps) -->
+<sly data-sly-test="${user.isAdmin}">
+  <p>Admin content 1</p>
+  <p>Admin content 2</p>
+</sly>
+
+<!-- Using unwrap directive -->
+<div data-sly-unwrap="${true}">
+  <p>This paragraph will remain</p>
+</div>
+```
+
+**Faintly:**
+```html
+<!-- Any element with data-fly-unwrap -->
+<div data-fly-test="user.isAdmin" data-fly-unwrap="true">
+  <p>Admin content 1</p>
+  <p>Admin content 2</p>
+</div>
+
+<!-- Or explicit unwrap -->
+<div data-fly-unwrap="true">
+  <p>This paragraph will remain</p>
+</div>
+```

From 59ea5ab58197865c8fa4dc1cbec88f6821c18234 Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Wed, 29 Oct 2025 17:18:24 -0700
Subject: [PATCH 06/13] chore: bump version to 1.2.0

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 4d16147..0c49274 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "faintly",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "HTML Markup Transformation Library for AEM Blocks",
   "main": "src/index.js",
   "scripts": {

From 287260f82a34a076489ddb26b5375978e576327b Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Wed, 29 Oct 2025 17:35:07 -0700
Subject: [PATCH 07/13] Add CSP tests for utils:eval to demonstrate unsafe-eval
 requirement

- Tests use real CSP meta tag that blocks unsafe-eval
- Demonstrates all utils:eval() expressions fail under CSP restrictions
- Shows that non-eval expressions (property paths, context functions) still work
- No mocking needed - uses actual browser CSP enforcement
---
 test/expressions/utils-eval-csp.test.html | 135 ++++++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 test/expressions/utils-eval-csp.test.html

diff --git a/test/expressions/utils-eval-csp.test.html b/test/expressions/utils-eval-csp.test.html
new file mode 100644
index 0000000..613fd75
--- /dev/null
+++ b/test/expressions/utils-eval-csp.test.html
@@ -0,0 +1,135 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="UTF-8">
+  <!-- Real CSP that blocks unsafe-eval but allows everything else needed for testing -->
+  <meta http-equiv="Content-Security-Policy"
+    content="default-src 'self'; script-src 'self' 'unsafe-inline'; connect-src 'self' ws: wss:; style-src 'self' 'unsafe-inline'">
+  <title>utils:eval CSP Tests</title>
+</head>
+
+<body>
+  <script type="module">
+    /* eslint-env mocha */
+    /* eslint-disable no-unused-expressions */
+
+    import { runTests } from '@web/test-runner-mocha';
+    import { expect } from '@esm-bundle/chai';
+    import { resolveExpression } from '../../src/expressions.js';
+
+    /**
+     * These tests use a REAL Content Security Policy that blocks 'unsafe-eval'.
+     * This demonstrates what breaks when utils:eval() is used in a CSP-restricted environment.
+     */
+    runTests(() => {
+      describe('utils:eval() with real CSP blocking unsafe-eval', () => {
+        describe('what breaks when CSP blocks unsafe-eval', () => {
+          it('should throw EvalError for comparison operators', async () => {
+            const context = { count: 10 };
+            try {
+              await resolveExpression('utils:eval(count > 5)', context);
+              expect.fail('should have thrown EvalError when CSP blocks unsafe-eval');
+            } catch (error) {
+              expect(error).to.be.instanceOf(EvalError);
+            }
+          });
+
+          it('should throw EvalError for ternary expressions', async () => {
+            const context = { status: 'active', count: 5 };
+            try {
+              await resolveExpression('utils:eval(status === "active" ? count * 2 : 0)', context);
+              expect.fail('should have thrown EvalError when CSP blocks unsafe-eval');
+            } catch (error) {
+              expect(error).to.be.instanceOf(EvalError);
+            }
+          });
+
+          it('should throw EvalError for string method calls', async () => {
+            const context = { name: 'john' };
+            try {
+              await resolveExpression('utils:eval(name.toUpperCase())', context);
+              expect.fail('should have thrown EvalError when CSP blocks unsafe-eval');
+            } catch (error) {
+              expect(error).to.be.instanceOf(EvalError);
+            }
+          });
+
+          it('should throw EvalError for array methods with arrow functions', async () => {
+            const context = { numbers: [1, 2, 3] };
+            try {
+              await resolveExpression('utils:eval(numbers.map(n => n * 2))', context);
+              expect.fail('should have thrown EvalError when CSP blocks unsafe-eval');
+            } catch (error) {
+              expect(error).to.be.instanceOf(EvalError);
+            }
+          });
+
+          it('should throw EvalError for logical operators', async () => {
+            const context = { isValid: true, isActive: true };
+            try {
+              await resolveExpression('utils:eval(isValid && isActive)', context);
+              expect.fail('should have thrown EvalError when CSP blocks unsafe-eval');
+            } catch (error) {
+              expect(error).to.be.instanceOf(EvalError);
+            }
+          });
+
+          it('should throw EvalError for arithmetic operations', async () => {
+            const context = { a: 10, b: 5 };
+            try {
+              await resolveExpression('utils:eval(a + b * 2)', context);
+              expect.fail('should have thrown EvalError when CSP blocks unsafe-eval');
+            } catch (error) {
+              expect(error).to.be.instanceOf(EvalError);
+            }
+          });
+
+          it('should throw EvalError for custom helper functions', async () => {
+            const context = {
+              name: 'John',
+              count: 5,
+              formatMessage: (n, c) => `Hello ${n}, you have ${c} messages`,
+            };
+            try {
+              await resolveExpression('utils:eval(formatMessage(name, count))', context);
+              expect.fail('should have thrown EvalError when CSP blocks unsafe-eval');
+            } catch (error) {
+              expect(error).to.be.instanceOf(EvalError);
+            }
+          });
+        });
+
+        describe('what still works without unsafe-eval (non-utils:eval expressions)', () => {
+          it('should resolve simple property paths without utils:eval', async () => {
+            const context = { count: 10 };
+            const result = await resolveExpression('count', context);
+            expect(result).to.equal(10);
+          });
+
+          it('should resolve nested property paths without utils:eval', async () => {
+            const context = { user: { profile: { name: 'John' } } };
+            const result = await resolveExpression('user.profile.name', context);
+            expect(result).to.equal('John');
+          });
+
+          it('should call context functions without utils:eval', async () => {
+            const context = {
+              greeting: () => 'Hello',
+            };
+            const result = await resolveExpression('greeting', context);
+            expect(result).to.equal('Hello');
+          });
+
+          it('should access array length without utils:eval', async () => {
+            const context = { items: ['a', 'b', 'c'] };
+            const result = await resolveExpression('items.length', context);
+            expect(result).to.equal(3);
+          });
+        });
+      });
+    });
+  </script>
+</body>
+
+</html>
\ No newline at end of file

From 06669c99cf78e42da95c44f54b16002f29d0457b Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Wed, 29 Oct 2025 17:37:46 -0700
Subject: [PATCH 08/13] Add verify script to run full validation pipeline

Runs clean, build:strict, lint, and test in sequence
---
 package.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 0c49274..bb6fc58 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,8 @@
     "build:watch": "node scripts/build.mjs --watch",
     "check:size": "node scripts/build.mjs --check-size",
     "check:size:strict": "node scripts/build.mjs --check-size --strict",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "verify": "npm run clean && npm run build:strict && npm run lint && npm test"
   },
   "author": "Sean Steimer",
   "license": "Apache-2.0",

From a7f9060b875df2210e847b9a071c463c6e7a09ce Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Thu, 30 Oct 2025 08:19:15 -0700
Subject: [PATCH 09/13] Update GitHub workflow to use verify command

Simplifies CI pipeline by using single verify command instead of separate lint, test, build:strict steps
---
 .github/workflows/main.yaml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
index f38edf0..fd55790 100644
--- a/.github/workflows/main.yaml
+++ b/.github/workflows/main.yaml
@@ -20,9 +20,7 @@ jobs:
       with:
         node-version: 20
     - run: npm ci
-    - run: npm run lint
-    - run: npm run test
-    - run: npm run build:strict
+    - run: npm run verify
     - name: Commit dist if changed
       run: |
         git config user.name "github-actions[bot]"

From fd3bc23d12488b7077a7ea16f82fda0a47726c71 Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Thu, 30 Oct 2025 08:35:41 -0700
Subject: [PATCH 10/13] test: reorganize processAttributes tests and remove
 redundant test

- Move expression syntax test out of security integration section
- Remove redundant security initialization test
- Clean up test structure for better organization
---
 .../attributes/processAttributes.test.js      | 61 +++++++------------
 1 file changed, 22 insertions(+), 39 deletions(-)

diff --git a/test/directives/attributes/processAttributes.test.js b/test/directives/attributes/processAttributes.test.js
index cb5476b..80e25b1 100644
--- a/test/directives/attributes/processAttributes.test.js
+++ b/test/directives/attributes/processAttributes.test.js
@@ -57,6 +57,24 @@ describe('processAttributes', () => {
     expect(el.hasAttribute('data-fly-attributes')).to.equal(false);
   });
 
+  it('supports ${} wrapped expressions in data-fly-attributes', async () => {
+    const el = document.createElement('div');
+    // eslint-disable-next-line no-template-curly-in-string
+    el.setAttribute('data-fly-attributes', '${attrsObj}');
+    const context = {
+      attrsObj: {
+        foo: 'bar',
+        id: 'some-id',
+        class: 'some-class',
+      },
+    };
+    context.security = await initializeSecurity(context);
+    await processAttributes(el, context);
+    expect(el.getAttribute('foo')).to.equal('bar');
+    expect(el.getAttribute('id')).to.equal('some-id');
+    expect(el.getAttribute('class')).to.equal('some-class');
+  });
+
   describe('security integration', () => {
     it('calls security hooks when context.security is provided with custom hooks', async () => {
       const el = document.createElement('div');
@@ -117,57 +135,22 @@ describe('processAttributes', () => {
       expect(el.getAttribute('href')).to.equal('javascript:void(0)');
     });
 
-    it('loads default security module when no security context provided', async () => {
-      const el = document.createElement('div');
-      el.setAttribute('data-fly-attributes', 'attrs');
-
-      const context = {
-        attrs: { onclick: 'alert(1)', class: 'safe' },
-      };
-      context.security = await initializeSecurity(context);
-      // Default security should block event handlers
-      await processAttributes(el, context);
-
-      expect(el.hasAttribute('onclick')).to.equal(false); // Blocked by default security
-      expect(el.getAttribute('class')).to.equal('safe'); // Safe attribute allowed
-    });
-
     it('applies security checks to expression-resolved attributes', async () => {
       const el = document.createElement('a');
       // eslint-disable-next-line no-template-curly-in-string
       el.setAttribute('href', '${ link }');
 
-      const customSecurity = {
-        shouldAllowAttribute: (name, value) => value !== 'blocked-value',
-        allowIncludePath: () => true,
-      };
-
       const context = {
         link: 'blocked-value',
-        security: customSecurity,
+        security: {
+          shouldAllowAttribute: (name, value) => value !== 'blocked-value',
+          allowIncludePath: () => true,
+        },
       };
       context.security = await initializeSecurity(context);
       await processAttributes(el, context);
 
       expect(el.hasAttribute('href')).to.equal(false);
     });
-
-    it('supports ${} wrapped expressions in data-fly-attributes', async () => {
-      const el = document.createElement('div');
-      // eslint-disable-next-line no-template-curly-in-string
-      el.setAttribute('data-fly-attributes', '${attrsObj}');
-      const context = {
-        attrsObj: {
-          foo: 'bar',
-          id: 'some-id',
-          class: 'some-class',
-        },
-      };
-      context.security = await initializeSecurity(context);
-      await processAttributes(el, context);
-      expect(el.getAttribute('foo')).to.equal('bar');
-      expect(el.getAttribute('id')).to.equal('some-id');
-      expect(el.getAttribute('class')).to.equal('some-class');
-    });
   });
 });

From 3aeb5ad6480034562d625e9a06d3f17719fc5be8 Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Thu, 30 Oct 2025 08:45:22 -0700
Subject: [PATCH 11/13] Add npm script for running individual test files

- Create wtr-single.config.mjs for running specific test files
- Add 'npm run test:file' script that accepts file paths or globs
- Update AGENTS.md with instructions on how to run individual tests
- Document that npm test -- --files doesn't work with group configs
---
 AGENTS.md             | 13 ++++++++++---
 package.json          |  1 +
 wtr-single.config.mjs |  3 +++
 3 files changed, 14 insertions(+), 3 deletions(-)
 create mode 100644 wtr-single.config.mjs

diff --git a/AGENTS.md b/AGENTS.md
index 95ecb49..97fd8a1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,13 +14,13 @@ Authoritative guide for AI/code agents contributing to this repository.
 
 ### Scripts (run from repo root)
 - **Install**: `npm ci`
-- **Lint**: `npm run lint`
-- **Lint (auto-fix)**: `npm run lint:fix`
+- **Lint**: `npm run lint` and `npm run lint:fix` (autofix)
 - **Unit tests + coverage**: `npm test`
-- **Performance tests**: `npm run test:perf`
+- **Run individual test file(s)**: `npm run test:file 'path/to/test.js'` (supports glob patterns like `'test/security/*.test.js'`)
 - **Build bundle**: `npm run build` → outputs `dist/faintly.js` and prints gzipped size (warns if over limit)
 - **Build (strict)**: `npm run build:strict` → fails if gzipped size exceeds 5120 bytes
 - **Clean**: `npm run clean`
+- **Verify all**: `npm run verify` → runs clean, build:strict, lint, and test in sequence (comprehensive check)
 
 ### Tests and coverage
 - Test runner: `@web/test-runner` with Mocha.
@@ -30,6 +30,11 @@ Authoritative guide for AI/code agents contributing to this repository.
 - Coverage thresholds (enforced in CI): 100% for statements, branches, functions, and lines.
 - Coverage reports: written to `coverage/`. Excludes `test/fixtures/**`, `test/snapshots/**`, `test/test-utils.js`, and `node_modules/**`.
 - When adding features, add or update tests to maintain 100% coverage in the `unit` group.
+- **Running individual test files**:
+  - Use `npm run test:file 'path/to/test.js'` to run a specific test file.
+  - Supports glob patterns: `npm run test:file 'test/security/*.test.js'`
+  - Note: This uses a separate config (`wtr-single.config.mjs`) because the main config's group-based file patterns take precedence over the `--files` flag.
+  - Do NOT use `npm test -- --files 'path/to/test.js'` as it will not work correctly with the group-based configuration.
 
 ### Linting and code style
 - ESLint config: `airbnb-base` via `.eslintrc.js` with `@babel/eslint-parser`.
@@ -64,6 +69,8 @@ Authoritative guide for AI/code agents contributing to this repository.
 - `test/`: unit/perf tests, fixtures, snapshots, and utilities
   - `test/security/`: tests for security module
 - `coverage/`: coverage output when tests are run with coverage
+- `web-test-runner.config.mjs`: main test runner config with group-based patterns
+- `wtr-single.config.mjs`: minimal config for running individual test files (bypasses groups)
 
 ### Contribution checklist for agents
 1. Install deps with `npm ci`.
diff --git a/package.json b/package.json
index bb6fc58..eb030c7 100644
--- a/package.json
+++ b/package.json
@@ -6,6 +6,7 @@
   "scripts": {
     "test": "web-test-runner --node-resolve --coverage --group unit",
     "test:watch": "web-test-runner --node-resolve --coverage --watch --group unit",
+    "test:file": "web-test-runner --node-resolve --config wtr-single.config.mjs --files",
     "test:perf": "web-test-runner --node-resolve --group perf",
     "test:perf:watch": "web-test-runner --node-resolve --watch --group perf",
     "lint": "eslint . --ext .js,.mjs",
diff --git a/wtr-single.config.mjs b/wtr-single.config.mjs
new file mode 100644
index 0000000..af74e8c
--- /dev/null
+++ b/wtr-single.config.mjs
@@ -0,0 +1,3 @@
+export default {
+  // Minimal config for running individual test files
+};

From 187d911f313f1be3027efa049b7f7fea239b0d2a Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Thu, 30 Oct 2025 09:37:16 -0700
Subject: [PATCH 12/13] Add comprehensive XSS security tests and documentation

- Add test/security/xss-vectors.test.js with 29 XSS attack vector tests
  - Event handler injection (onclick, onerror, etc.)
  - JavaScript/VBScript/file: URL schemes
  - Data URI injection
  - srcdoc attributes
  - Content injection via strings
  - Expression injection
  - SVG-based XSS, form actions, edge cases
  - All tests pass, 100% coverage maintained

- Add docs/SECURITY.md with comprehensive security guide
  - Security modes table (Default, Custom, Unsafe)
  - Configuration options table
  - Security model and trust boundaries
  - Best practices with utils:eval() warning
  - Custom security hooks
  - Clear, concise, scannable format (220 lines)

- Update README.md security section
  - Add 'What's NOT protected' list
  - Add utils:eval() security warning
  - Link to detailed SECURITY.md documentation
  - Keep high-level and concise

All 226 tests pass with 100% coverage. Build: 3457 bytes (under 6KB limit).
---
 README.md                         | 100 +-----
 docs/SECURITY.md                  | 219 +++++++++++++
 test/security/xss-vectors.test.js | 514 ++++++++++++++++++++++++++++++
 3 files changed, 744 insertions(+), 89 deletions(-)
 create mode 100644 docs/SECURITY.md
 create mode 100644 test/security/xss-vectors.test.js

diff --git a/README.md b/README.md
index 6a0c76d..86a2214 100644
--- a/README.md
+++ b/README.md
@@ -77,102 +77,24 @@ When in a repeat loop, it will also include:
 
 ## Security
 
-Faintly includes built-in security features to help protect against XSS (Cross-Site Scripting) attacks. By default, security is **enabled** and provides:
-
-* **Attribute sanitization** - Blocks dangerous attributes like event handlers (`onclick`, `onerror`, etc.) and `srcdoc`
-* **URL scheme validation** - Restricts URLs in attributes like `href` and `src` to safe schemes (`http:`, `https:`, `mailto:`, `tel:`)
-* **Same-origin enforcement** - Template includes are restricted to same-origin URLs only
-
-### Default Security
-
-When you call `renderBlock()` without a security context, default security is automatically applied:
-
-```javascript
-await renderBlock(block); // Default security enabled
-```
-
-The default security module (`dist/faintly.security.js`) is dynamically loaded on first use.
-
-### Custom Security
-
-For more control, you can provide a custom security object with `shouldAllowAttribute` and `allowIncludePath` hooks:
-
-```javascript
-await renderBlock(block, {
-  security: {
-    shouldAllowAttribute(attrName, value) {
-      // Return true to allow the attribute, false to block it
-      // Your custom logic here
-      return true;
-    },
-    allowIncludePath(templatePath) {
-      // Return true to allow the template include, false to block it
-      // Your custom logic here
-      return true;
-    },
-  },
-});
-```
-
-You can also use the default security module and override specific configuration:
+Faintly includes built-in XSS protection that is **enabled by default**.
 
 ```javascript
-import createSecurity from './scripts/faintly.security.js';
-
-await renderBlock(block, {
-  security: createSecurity({
-    // Add 'data:' URLs to allowed schemes
-    allowedUrlSchemes: ['http:', 'https:', 'mailto:', 'tel:', 'data:'],
-    // Block additional attributes
-    blockedAttributes: ['srcdoc', 'sandbox'],
-  }),
-});
+await renderBlock(block); // Security automatically enabled
 ```
 
-### Security Configuration Options
-
-The default security module accepts the following configuration:
-
-* `blockedAttributePatterns` (Array<RegExp>) - Regex patterns for blocked attribute names (default: `/^on/i` blocks all event handlers)
-* `blockedAttributes` (Array<string>) - Specific attribute names to block (default: `['srcdoc']`)
-* `urlAttributes` (Array<string>) - Attributes that contain URLs to validate (default: `['href', 'src', 'action', 'formaction', 'xlink:href']`)
-* `allowedUrlSchemes` (Array<string>) - Allowed URL schemes; relative URLs are always allowed (default: `['http:', 'https:', 'mailto:', 'tel:']`)
-
-
-### Disabling Security (Unsafe Mode)
-
-You can disable security if needed. **THIS IS NOT RECOMMENDED**
-
-
-> [!CAUTION]  
-> **THIS IS NOT RECOMMENDED**  and bypasses all XSS protection.
-
-```javascript
-await renderBlock(block, {
-  security: false, // or 'unsafe'
-});
-```
-
-
-### Trust Boundaries
-
-It's important to understand what Faintly's security does and doesn't protect:
-
-**Protected:**
-- ✅ Dangerous attributes (event handlers, `srcdoc`)
-- ✅ Malicious URL schemes (`javascript:`, `data:` by default)
+**What's protected:**
+- ✅ Dangerous attributes (event handlers like `onclick`, `onerror`, etc.)
+- ✅ Malicious URL schemes (`javascript:`, `data:`, `vbscript:`, `file:`)
 - ✅ Cross-origin template includes
+- ✅ HTML strings treated as plain text (not parsed as HTML)
 
-**Trusted (by design):**
-- The rendering context you provide is fully trusted
-- Templates fetched from your same-origin are trusted
-- DOM Node objects provided in context are inserted directly
-
-> [!WARNING]  
-> **Be extremely careful when adding user-supplied data to the rendering context.** URL parameters, form inputs, cookies, and other user-controlled data should be validated and sanitized before adding to the context. The context is fully trusted, so untrusted data placed in it can bypass security protections.
+**What's NOT protected (by design):**
+- ⚠️ **Context data** - The rendering context is fully trusted
+- ⚠️ **Pre-built DOM elements** - Elements passed through context are inserted as-is
+- ⚠️ **`utils:eval()` expressions** - JavaScript evaluation requires `unsafe-eval` CSP and trusts context data
 
-> [!TIP]  
-> Security works best in layers. Faintly's security helps prevent common XSS vectors, but you should also: validate and sanitize user input before adding it to context, use Content Security Policy headers, and follow secure coding practices.
+For detailed information about the security model, configuration options, custom security hooks, and best practices, see **[Security Documentation](./docs/SECURITY.md)**.
 
 ## Directives
 
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
new file mode 100644
index 0000000..b38a90f
--- /dev/null
+++ b/docs/SECURITY.md
@@ -0,0 +1,219 @@
+# Security
+
+Faintly includes built-in security features to help protect against XSS (Cross-Site Scripting) attacks. This document provides detailed information about the security model, configuration options, and best practices.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Security Model](#security-model)
+- [Default Security](#default-security)
+- [Configuration](#configuration)
+- [Custom Security Hooks](#custom-security-hooks)
+- [Best Practices](#best-practices)
+- [Disabling Security (Not Recommended)](#disabling-security-not-recommended)
+
+## Quick Start
+
+Default security is **enabled by default**, without any configuration:
+
+```javascript
+import { renderBlock } from './scripts/faintly.js';
+
+export default async function decorate(block) {
+  await renderBlock(block); // Security automatically enabled
+}
+```
+
+The default security module (`dist/faintly.security.js`) is dynamically loaded on first use. Keep reading for what is and is not protected.
+
+### Security Modes
+
+Faintly supports three security modes:
+
+| Mode | Description | Use Case | Documentation |
+|------|-------------|----------|---------------|
+| **Default** (Recommended) | Built-in XSS protection with sensible defaults | Most applications | [Default Security](#default-security) |
+| **Custom** | Override defaults or provide custom security hooks | Fine-grained control or specific requirements | [Configuration](#configuration), [Custom Security Hooks](#custom-security-hooks) |
+| **Unsafe** (Not Recommended) | Security disabled | Fully trusted environments only | [Disabling Security](#disabling-security-not-recommended) |
+
+## Security Model
+
+Faintly's security model is built on clear **trust boundaries**:
+
+### What Gets Sanitized ✅
+
+Security checks are applied to:
+- **Attribute names and values** set via `data-fly-attributes`
+- **URL schemes** in href, src, action, formaction, and xlink:href attributes
+- **Expression values** after resolution (e.g., `${userInput}`)
+- **Template include paths** (same-origin enforcement)
+
+### What Is Trusted (By Design) ⚠️
+
+The following are considered **trusted** and NOT sanitized:
+- **Context objects** you provide to `renderBlock()`
+- **DOM elements** passed through context
+- **Templates** from your same-origin server
+- **JavaScript functions** in your context
+
+> [!WARNING]
+> **The rendering context is fully trusted.** If you add user-supplied data (URL parameters, form inputs, cookies, etc.) to the context, you must validate and sanitize it first. Untrusted data in the context can bypass security protections.
+
+### String Content Handling
+
+HTML strings are always treated as plain text and set via `textContent`, not `innerHTML`. This prevents XSS from string injection.
+
+```javascript
+// Strings via data-fly-content are treated as PLAIN TEXT (safe)
+context.content = '<script>alert("XSS")</script>';
+// Result: displays the literal text, script does NOT execute
+
+// DOM elements via data-fly-content are inserted AS-IS (trusted)
+const script = document.createElement('script');
+script.textContent = 'alert("XSS")';
+context.content = script;
+// Result: script element is inserted (though inline scripts won't execute via DOM manipulation)
+```
+
+## Default Security
+
+The default security configuration provides:
+
+### 1. Blocked Attributes
+
+**Event Handlers** - All attributes matching `/^on/i` pattern:
+- `onclick`, `onerror`, `onload`, `onmouseover`, `onmouseout`
+- `onkeydown`, `onkeyup`, `onkeypress`, `onfocus`, `onblur`
+- `onsubmit`, `onchange`, `onresize`, `onscroll`
+- And all other `on*` event handlers (case-insensitive)
+
+**Dangerous Attributes**:
+- `srcdoc` - Can execute arbitrary HTML/scripts in iframes
+
+### 2. URL Scheme Validation
+
+URLs in the following attributes are validated:
+- `href`, `src`, `action`, `formaction`, `xlink:href`
+
+**Allowed schemes by default**:
+- `http:`
+- `https:`
+- `mailto:`
+- `tel:`
+- Relative URLs (always allowed: `/path`, `./path`, `../path`, `#hash`, `?query`)
+
+**Blocked schemes**:
+- `javascript:` - Direct code execution
+- `data:` - Can contain executable content (blocked by default)
+- `vbscript:` - VBScript execution
+- `file:` - Local file access
+- Any other non-allowlisted scheme
+
+### 3. Template Include Restrictions
+
+Template includes via `data-fly-include` are restricted to:
+- Same-origin URLs only
+- Relative paths (e.g., `/blocks/card/card.html`)
+- Full URLs matching `window.location.origin`
+
+Cross-origin template loading is blocked by default.
+
+## Configuration
+
+You can customize the default security by passing configuration options:
+
+```javascript
+import createSecurity from './scripts/faintly.security.js';
+
+await renderBlock(block, {
+  security: createSecurity({
+    // Customize one or more options
+  }),
+});
+```
+
+### Configuration Options
+
+| Option | Description | Default | Example |
+|--------|-------------|---------|---------|
+| `blockedAttributePatterns`<br/>(Array&lt;RegExp&gt;) | Regex patterns for attribute names to block | `[/^on/i]`<br/>(blocks all event handlers) | `[/^data-/i]`<br/>(block data- attributes) |
+| `blockedAttributes`<br/>(Array&lt;string&gt;) | Specific attribute names to block (case-insensitive) | `['srcdoc']` | `['srcdoc', 'sandbox', 'allow']`<br/>(block additional attributes) |
+| `urlAttributes`<br/>(Array&lt;string&gt;) | Attributes that should have URL scheme validation applied | `['href', 'src', 'action', 'formaction', 'xlink:href']` | `['href']`<br/>(only validate href) |
+| `allowedUrlSchemes`<br/>(Array&lt;string&gt;) | URL schemes that are allowed. Relative URLs are always allowed. | `['http:', 'https:', 'mailto:', 'tel:']` | `['http:', 'https:', 'mailto:', 'tel:', 'data:']`<br/>(allow data URIs) |
+
+## Custom Security Hooks
+
+For complete control, provide your own security implementation with `shouldAllowAttribute` and `allowIncludePath` hooks:
+
+```javascript
+await renderBlock(block, {
+  security: {
+    shouldAllowAttribute(attrName, value) {
+      // Return true to allow, false to block
+      // Your custom logic here
+      
+      // Example: Block all data- attributes
+      if (attrName.toLowerCase().startsWith('data-')) {
+        return false;
+      }
+      
+      // Example: Block specific values
+      if (value && value.includes('unsafe-content')) {
+        return false;
+      }
+      
+      return true;
+    },
+    
+    allowIncludePath(templatePath) {
+      // Return true to allow, false to block
+      // Your custom logic here
+      
+      // Example: Only allow specific directories
+      return templatePath.startsWith('/blocks/') 
+          || templatePath.startsWith('/templates/');
+    },
+  },
+});
+```
+
+## Best Practices
+
+Always sanitize user input before adding it to the context. **Adding any user-input to context to be used by faintly without first validating and sanitizing is inherently UNSAFE.**
+
+**Guidelines:**
+- **Validate all user input** - URL parameters, form data, cookies, localStorage
+- **Use strings for user content** - Not DOM elements (strings are treated as plain text)
+- **Avoid `utils:eval()` with untrusted data** - It uses JavaScript's `Function` constructor, requires `unsafe-eval` CSP, and has full access to context. Prefer context functions for complex logic.
+- **Layer your defenses** - Use CSP headers, input validation, and Faintly's security
+- **Audit context sources** - Know what data goes into your context and where it comes from
+- **Be careful with data URIs** - If enabling them, validate thoroughly or restrict to known-safe values
+
+## Disabling Security (Not Recommended)
+
+> [!CAUTION]
+> **Disabling security bypasses all XSS protection and is strongly discouraged.**
+
+If you absolutely must disable security:
+
+```javascript
+await renderBlock(block, {
+  security: false, // or 'unsafe'
+});
+```
+
+This allows:
+- All event handler attributes
+- All URL schemes (including `javascript:`, `data:`, `file:`)
+- Cross-origin template includes
+- Any attribute to be set
+
+**Only disable security if:**
+- You are absolutely certain all context data is safe
+- Your application has other layers of XSS protection
+- You understand and accept the security risks
+
+---
+
+For questions or security concerns, please open an issue on the [GitHub repository](https://github.com/adobe/faintly).
+
diff --git a/test/security/xss-vectors.test.js b/test/security/xss-vectors.test.js
new file mode 100644
index 0000000..18cd5b0
--- /dev/null
+++ b/test/security/xss-vectors.test.js
@@ -0,0 +1,514 @@
+/* eslint-env mocha */
+/* eslint-disable no-unused-expressions, no-script-url */
+
+import { expect } from '@esm-bundle/chai';
+import { processAttributes, processContent } from '../../src/directives.js';
+import { initializeSecurity } from '../../src/render.js';
+
+/**
+ * XSS Attack Vector Tests
+ *
+ * These tests attempt various XSS injection techniques to verify that:
+ * 1. The security layer properly blocks malicious content
+ * 2. The DOM remains safe after rendering
+ * 3. No executable code is present in the final output
+ *
+ * Tests are organized by attack vector type.
+ */
+
+describe('XSS Attack Vectors', () => {
+  describe('Event Handler Injection via Attributes', () => {
+    it('blocks onclick via data-fly-attributes', async () => {
+      const el = document.createElement('div');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { onclick: 'alert("XSS")' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('onclick')).to.equal(false);
+      expect(el.onclick).to.equal(null);
+    });
+
+    it('blocks onerror via data-fly-attributes', async () => {
+      const el = document.createElement('img');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { src: 'x', onerror: 'alert("XSS")' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('onerror')).to.equal(false);
+      expect(el.onerror).to.equal(null);
+    });
+
+    it('blocks onload via data-fly-attributes', async () => {
+      const el = document.createElement('body');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { onload: 'alert("XSS")' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('onload')).to.equal(false);
+      expect(el.onload).to.equal(null);
+    });
+
+    it('blocks onmouseover via data-fly-attributes', async () => {
+      const el = document.createElement('div');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { onmouseover: 'alert("XSS")' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('onmouseover')).to.equal(false);
+      expect(el.onmouseover).to.equal(null);
+    });
+
+    it('blocks multiple common event handlers in one element', async () => {
+      const el = document.createElement('div');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: {
+          onclick: 'alert("XSS")',
+          ondblclick: 'alert("XSS")',
+          onmousedown: 'alert("XSS")',
+          onmouseup: 'alert("XSS")',
+          onkeydown: 'alert("XSS")',
+          onkeyup: 'alert("XSS")',
+          onfocus: 'alert("XSS")',
+          onblur: 'alert("XSS")',
+          onchange: 'alert("XSS")',
+          onsubmit: 'alert("XSS")',
+          onabort: 'alert("XSS")',
+          onresize: 'alert("XSS")',
+          onscroll: 'alert("XSS")',
+          oncontextmenu: 'alert("XSS")',
+          // Also include some safe attributes
+          class: 'safe',
+          id: 'test',
+        },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      // All event handlers should be blocked
+      expect(el.hasAttribute('onclick')).to.equal(false);
+      expect(el.hasAttribute('ondblclick')).to.equal(false);
+      expect(el.hasAttribute('onmousedown')).to.equal(false);
+      expect(el.hasAttribute('onmouseup')).to.equal(false);
+      expect(el.hasAttribute('onkeydown')).to.equal(false);
+      expect(el.hasAttribute('onkeyup')).to.equal(false);
+      expect(el.hasAttribute('onfocus')).to.equal(false);
+      expect(el.hasAttribute('onblur')).to.equal(false);
+      expect(el.hasAttribute('onchange')).to.equal(false);
+      expect(el.hasAttribute('onsubmit')).to.equal(false);
+      expect(el.hasAttribute('onabort')).to.equal(false);
+      expect(el.hasAttribute('onresize')).to.equal(false);
+      expect(el.hasAttribute('onscroll')).to.equal(false);
+      expect(el.hasAttribute('oncontextmenu')).to.equal(false);
+
+      // Safe attributes should be allowed
+      expect(el.getAttribute('class')).to.equal('safe');
+      expect(el.getAttribute('id')).to.equal('test');
+    });
+  });
+
+  describe('JavaScript URL Injection', () => {
+    it('blocks javascript: URLs in href attributes', async () => {
+      const el = document.createElement('a');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { href: 'javascript:alert("XSS")' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('href')).to.equal(false);
+    });
+
+    it('blocks javascript: URLs in src attributes', async () => {
+      const el = document.createElement('iframe');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { src: 'javascript:alert("XSS")' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('src')).to.equal(false);
+    });
+
+    it('blocks javascript: URLs with mixed case', async () => {
+      const el = document.createElement('a');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { href: 'JaVaScRiPt:alert("XSS")' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('href')).to.equal(false);
+    });
+
+    it('blocks javascript: URLs with whitespace', async () => {
+      const el = document.createElement('a');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { href: '  javascript:alert("XSS")  ' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('href')).to.equal(false);
+    });
+  });
+
+  describe('Data URI Injection', () => {
+    it('blocks data: URLs with text/html in href', async () => {
+      const el = document.createElement('a');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { href: 'data:text/html,<script>alert("XSS")</script>' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('href')).to.equal(false);
+    });
+
+    it('blocks data: URLs in iframe src', async () => {
+      const el = document.createElement('iframe');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { src: 'data:text/html,<script>alert("XSS")</script>' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('src')).to.equal(false);
+    });
+
+    it('blocks data: URLs with base64 encoding', async () => {
+      const el = document.createElement('a');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      // Base64 encoded: <script>alert("XSS")</script>
+      const context = {
+        attrs: { href: 'data:text/html;base64,PHNjcmlwdD5hbGVydCgiWFNTIik8L3NjcmlwdD4=' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('href')).to.equal(false);
+    });
+  });
+
+  describe('srcdoc Attribute Injection', () => {
+    it('blocks srcdoc attribute on iframe', async () => {
+      const el = document.createElement('iframe');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { srcdoc: '<script>alert("XSS")</script>' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('srcdoc')).to.equal(false);
+    });
+
+    it('blocks srcdoc with HTML content', async () => {
+      const el = document.createElement('iframe');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { srcdoc: '<img src=x onerror=alert("XSS")>' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('srcdoc')).to.equal(false);
+    });
+  });
+
+  describe('Content Injection via data-fly-content', () => {
+    it('safely handles HTML strings with script tags (treats as text)', async () => {
+      const el = document.createElement('div');
+      el.setAttribute('data-fly-content', 'content');
+
+      const context = {
+        content: '<script>alert("XSS")</script>',
+      };
+      context.security = await initializeSecurity(context);
+
+      await processContent(el, context);
+
+      // Content should be treated as text, not HTML
+      expect(el.textContent).to.equal('<script>alert("XSS")</script>');
+      expect(el.querySelector('script')).to.equal(null);
+    });
+
+    it('safely handles HTML strings with img onerror (treats as text)', async () => {
+      const el = document.createElement('div');
+      el.setAttribute('data-fly-content', 'content');
+
+      const context = {
+        content: '<img src=x onerror=alert("XSS")>',
+      };
+      context.security = await initializeSecurity(context);
+
+      await processContent(el, context);
+
+      // Content should be treated as text, not HTML
+      expect(el.textContent).to.equal('<img src=x onerror=alert("XSS")>');
+      expect(el.querySelector('img')).to.equal(null);
+    });
+
+    it('safely handles HTML strings with iframe (treats as text)', async () => {
+      const el = document.createElement('div');
+      el.setAttribute('data-fly-content', 'content');
+
+      const context = {
+        content: '<iframe src="javascript:alert(\'XSS\')"></iframe>',
+      };
+      context.security = await initializeSecurity(context);
+
+      await processContent(el, context);
+
+      // Content should be treated as text, not HTML
+      expect(el.querySelector('iframe')).to.equal(null);
+    });
+
+    it('safely handles HTML strings with anchor javascript: URL (treats as text)', async () => {
+      const el = document.createElement('div');
+      el.setAttribute('data-fly-content', 'content');
+
+      const context = {
+        content: '<a href="javascript:alert(\'XSS\')">Click me</a>',
+      };
+      context.security = await initializeSecurity(context);
+
+      await processContent(el, context);
+
+      // Content should be treated as text, not HTML
+      expect(el.querySelector('a')).to.equal(null);
+    });
+  });
+
+  describe('Expression Injection', () => {
+    it('safely handles script tags in expression values', async () => {
+      const el = document.createElement('div');
+      // eslint-disable-next-line no-template-curly-in-string
+      el.setAttribute('title', '${userInput}');
+
+      const context = {
+        userInput: '<script>alert("XSS")</script>',
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      // Expression value should be set as text, not parsed as HTML
+      expect(el.getAttribute('title')).to.equal('<script>alert("XSS")</script>');
+    });
+
+    it('blocks javascript: URLs via expressions', async () => {
+      const el = document.createElement('a');
+      // eslint-disable-next-line no-template-curly-in-string
+      el.setAttribute('href', '${url}');
+
+      const context = {
+        url: 'javascript:alert("XSS")',
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('href')).to.equal(false);
+    });
+
+    it('blocks event handlers via expressions', async () => {
+      const el = document.createElement('div');
+      // eslint-disable-next-line no-template-curly-in-string
+      el.setAttribute('onclick', '${handler}');
+
+      const context = {
+        handler: 'alert("XSS")',
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      // onclick attribute should be blocked
+      expect(el.hasAttribute('onclick')).to.equal(false);
+    });
+  });
+
+  describe('DOM-based XSS via Element Injection', () => {
+    it('documents that pre-built DOM elements from context are trusted (not sanitized)', async () => {
+      const el = document.createElement('div');
+      el.setAttribute('data-fly-content', 'content');
+
+      // Create a simple element (avoid script/img that might cause browser issues in tests)
+      const spanEl = document.createElement('span');
+      spanEl.textContent = 'Content from DOM element';
+      spanEl.setAttribute('data-test', 'value');
+
+      const context = {
+        content: spanEl,
+      };
+      context.security = await initializeSecurity(context);
+
+      await processContent(el, context);
+
+      // Pre-constructed DOM elements are inserted as-is (context is trusted)
+      const span = el.querySelector('span');
+      expect(span).to.not.equal(null);
+      if (span) {
+        expect(span.textContent).to.equal('Content from DOM element');
+        expect(span.getAttribute('data-test')).to.equal('value');
+      }
+    });
+  });
+
+  describe('Edge Cases and Additional URL Schemes', () => {
+    it('blocks vbscript: URLs', async () => {
+      const el = document.createElement('a');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { href: 'vbscript:msgbox("XSS")' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('href')).to.equal(false);
+    });
+
+    it('blocks file: URLs', async () => {
+      const el = document.createElement('a');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { href: 'file:///etc/passwd' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('href')).to.equal(false);
+    });
+
+    it('handles empty string event handler values (still blocks)', async () => {
+      const el = document.createElement('div');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: {
+          onclick: '',
+          class: '',
+        },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      // Even empty onclick should be blocked
+      expect(el.hasAttribute('onclick')).to.equal(false);
+      // Empty safe attributes should be allowed
+      expect(el.getAttribute('class')).to.equal('');
+    });
+  });
+
+  describe('Form Action XSS Vectors', () => {
+    it('blocks javascript: URLs in formaction', async () => {
+      const el = document.createElement('button');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { formaction: 'javascript:alert("XSS")' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('formaction')).to.equal(false);
+    });
+
+    it('blocks data: URLs in action attribute', async () => {
+      const el = document.createElement('form');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { action: 'data:text/html,<script>alert("XSS")</script>' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('action')).to.equal(false);
+    });
+  });
+
+  describe('SVG-based XSS Vectors', () => {
+    it('blocks event handlers on SVG elements', async () => {
+      const el = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { onload: 'alert("XSS")' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('onload')).to.equal(false);
+    });
+
+    it('blocks javascript: in xlink:href', async () => {
+      const el = document.createElementNS('http://www.w3.org/2000/svg', 'use');
+      el.setAttribute('data-fly-attributes', 'attrs');
+
+      const context = {
+        attrs: { 'xlink:href': 'javascript:alert("XSS")' },
+      };
+      context.security = await initializeSecurity(context);
+
+      await processAttributes(el, context);
+
+      expect(el.hasAttribute('xlink:href')).to.equal(false);
+    });
+  });
+});

From ea012cc71c1f351475c28d71be78110082ea90fe Mon Sep 17 00:00:00 2001
From: Sean Steimer <ssteimer@adobe.com>
Date: Thu, 30 Oct 2025 09:47:31 -0700
Subject: [PATCH 13/13] Document expression injection risk and utils:eval()
 global access

Critical security documentation improvements:

1. Add expression-injection.test.js (6 tests)
   - Documents that expressions CAN be injected if user controls HTML
   - Tests innerHTML, setAttribute, and text node injection vectors
   - Shows context-only usage is safe
   - Demonstrates attack scenarios

2. Document utils:eval() has full global access
   - Update README.md and SECURITY.md to clarify it uses Function + with()
   - State explicitly it accesses window, document, and all browser globals
   - Provide concrete attack examples (window.location, document.cookie)
   - Emphasize never use with untrusted data

3. Add critical DANGER warnings
   - README.md: Never allow user input in templates/HTML
   - SECURITY.md: User input must ONLY go in context, never templates
   - Clear guidance: no innerHTML, setAttribute, or template files with user content

Security Model Summary:
- Templates/HTML are TRUSTED (expressions are evaluated)
- Context data is TRUSTED (but sanitized when used in attributes)
- User input must be validated before context AND never in templates

All 232 tests pass with 100% coverage.
---
 README.md                                  |  11 +-
 docs/SECURITY.md                           |   6 +-
 src/expressions.js                         |   1 -
 test/security/expression-injection.test.js | 128 +++++++++++++++++++++
 4 files changed, 141 insertions(+), 5 deletions(-)
 create mode 100644 test/security/expression-injection.test.js

diff --git a/README.md b/README.md
index 86a2214..220738e 100644
--- a/README.md
+++ b/README.md
@@ -93,6 +93,10 @@ await renderBlock(block); // Security automatically enabled
 - ⚠️ **Context data** - The rendering context is fully trusted
 - ⚠️ **Pre-built DOM elements** - Elements passed through context are inserted as-is
 - ⚠️ **`utils:eval()` expressions** - JavaScript evaluation requires `unsafe-eval` CSP and trusts context data
+- ⚠️ **Templates/HTML** - Templates are trusted. Never allow user input in templates, innerHTML, or setAttribute - expressions like `${...}` will be evaluated
+
+> [!DANGER]
+> **Never allow user input to become part of templates or HTML.** User input must ONLY go into the context. If users can control template content, they can inject `${utils:eval(...)}` to execute arbitrary code.
 
 For detailed information about the security model, configuration options, custom security hooks, and best practices, see **[Security Documentation](./docs/SECURITY.md)**.
 
@@ -141,11 +145,12 @@ Faintly supports a simple expression syntax for resolving data from the renderin
 > **⚠️ This feature uses JavaScript's `Function` constructor (similar to `eval`)**
 >
 > - Requires Content Security Policy with `'unsafe-eval'` directive
-> - The entire context is accessible to evaluated expressions
-> - **Never put untrusted user input in the context** (this applies to all Faintly features)
+> - **Has full access to context AND browser globals** (`window`, `document`, etc.)
+> - An attacker with control over context data could craft expressions like `utils:eval(window.location='https://evil.com')` or `utils:eval(document.cookie)`
+> - **Never put untrusted user input in the context** when using `utils:eval()`
 > - If your CSP blocks `unsafe-eval`, this feature won't work
 >
-> Use `utils:eval()` thoughtfully. For complex logic, consider context functions instead.
+> Use `utils:eval()` thoughtfully. For complex logic, context functions are safer and more maintainable.
 
 When a bit more logic is required, you canuse `utils:eval()` to evaluate JavaScript expressions. Some examples:
 
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index b38a90f..7e451a5 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -181,10 +181,14 @@ await renderBlock(block, {
 
 Always sanitize user input before adding it to the context. **Adding any user-input to context to be used by faintly without first validating and sanitizing is inherently UNSAFE.**
 
+> [!DANGER]
+> **Never allow user input to become part of templates/HTML.** User input must ONLY go into the context, never into template strings, innerHTML, or attribute values that will be rendered. If users can control template content, they can inject expressions like `${utils:eval(...)}` to execute arbitrary code.
+
 **Guidelines:**
 - **Validate all user input** - URL parameters, form data, cookies, localStorage
+- **NEVER put user input in templates/HTML** - User input goes in context only. Never: `innerHTML = userInput`, `setAttribute('title', userInput)`, or template files with user content
 - **Use strings for user content** - Not DOM elements (strings are treated as plain text)
-- **Avoid `utils:eval()` with untrusted data** - It uses JavaScript's `Function` constructor, requires `unsafe-eval` CSP, and has full access to context. Prefer context functions for complex logic.
+- **Avoid `utils:eval()` with untrusted data** - It uses JavaScript's `Function` constructor with `with()` statement, requires `unsafe-eval` CSP, and **has full access to context AND browser globals** (`window`, `document`, etc.). An attacker could craft expressions like `utils:eval(window.location='https://evil.com')` or `utils:eval(document.cookie)`. Prefer context functions for complex logic.
 - **Layer your defenses** - Use CSP headers, input validation, and Faintly's security
 - **Audit context sources** - Know what data goes into your context and where it comes from
 - **Be careful with data URIs** - If enabling them, validate thoroughly or restrict to known-safe values
diff --git a/src/expressions.js b/src/expressions.js
index 3938ecf..88d4c62 100644
--- a/src/expressions.js
+++ b/src/expressions.js
@@ -32,7 +32,6 @@ export function unwrapExpression(expression) {
  * @returns {Promise<any>} the data that was resolved
  */
 export async function resolveExpression(expression, context) {
-  // Handle utils:eval() syntax
   const trimmedExpression = expression.trim();
   if (trimmedExpression.startsWith('utils:eval(') && trimmedExpression.endsWith(')')) {
     const expr = trimmedExpression.slice(11, -1); // Extract expression from utils:eval(...)
diff --git a/test/security/expression-injection.test.js b/test/security/expression-injection.test.js
new file mode 100644
index 0000000..fb62245
--- /dev/null
+++ b/test/security/expression-injection.test.js
@@ -0,0 +1,128 @@
+/* eslint-env mocha */
+/* eslint-disable no-unused-expressions, no-template-curly-in-string */
+
+import { expect } from '@esm-bundle/chai';
+import { processNode, initializeSecurity } from '../../src/render.js';
+
+/**
+ * Expression Injection Tests
+ *
+ * These tests document the risk of user input controlling template/HTML content.
+ * If user input becomes part of the HTML (not just context), they can inject
+ * expressions including utils:eval() to execute arbitrary code.
+ *
+ * SECURITY MODEL: Templates/HTML are trusted, context data is sanitized.
+ * Developers must NEVER allow user input to become part of templates.
+ */
+
+describe('Expression Injection via Template Control', () => {
+  describe('Risk: User input in HTML/template strings', () => {
+    it('UNSAFE: User input in innerHTML can inject expressions', async () => {
+      const el = document.createElement('div');
+
+      // DANGEROUS: User input becomes part of HTML
+      const maliciousUserInput = '${utils:eval(typeof window)}';
+      el.innerHTML = `<span title="${maliciousUserInput}">Test</span>`;
+
+      const context = {};
+      context.security = await initializeSecurity(context);
+
+      await processNode(el, context);
+
+      // Expression was evaluated!
+      const span = el.querySelector('span');
+      expect(span.getAttribute('title')).to.equal('object');
+    });
+
+    it('UNSAFE: User input in text nodes can inject expressions', async () => {
+      const el = document.createElement('div');
+
+      // DANGEROUS: User input becomes text content with expression
+      const maliciousUserInput = 'Hello ${utils:eval(typeof document)}';
+      el.textContent = maliciousUserInput;
+
+      const context = {};
+      context.security = await initializeSecurity(context);
+
+      await processNode(el, context);
+
+      // Expression was evaluated in text!
+      expect(el.textContent).to.equal('Hello object');
+    });
+
+    it('UNSAFE: User input via setAttribute can inject expressions', async () => {
+      const el = document.createElement('div');
+
+      // DANGEROUS: User controls attribute value with expression
+      const maliciousUserInput = '${utils:eval(2+2)}';
+      el.setAttribute('data-value', maliciousUserInput);
+
+      const context = {};
+      context.security = await initializeSecurity(context);
+
+      await processNode(el, context);
+
+      // Expression was evaluated!
+      expect(el.getAttribute('data-value')).to.equal('4');
+    });
+  });
+
+  describe('SAFE: User input in context only', () => {
+    it('SAFE: User input in context does not create expressions', async () => {
+      const el = document.createElement('div');
+      // Template controls the expression syntax
+      // eslint-disable-next-line no-template-curly-in-string
+      el.setAttribute('title', '${userInput}');
+
+      // User input contains what looks like an expression, but it's just data
+      const context = {
+        userInput: '${utils:eval(typeof window)}',
+      };
+      context.security = await initializeSecurity(context);
+
+      await processNode(el, context);
+
+      // NOT evaluated - treated as literal string from context
+      expect(el.getAttribute('title')).to.equal('${utils:eval(typeof window)}');
+    });
+  });
+
+  describe('Attack vector documentation', () => {
+    it('documents that utils:eval can be injected via template control', async () => {
+      // This test documents the attack - DO NOT allow user input in templates!
+      const el = document.createElement('div');
+
+      // Simulate attacker controlling part of template
+      const attackPayload = '${utils:eval(window.location.href)}';
+      el.innerHTML = `<div data-url="${attackPayload}"></div>`;
+
+      const context = {};
+      context.security = await initializeSecurity(context);
+
+      await processNode(el, context);
+
+      // Attack succeeded - utils:eval was executed
+      const innerDiv = el.querySelector('div');
+      expect(innerDiv.getAttribute('data-url')).to.include('http');
+    });
+
+    it('documents that regular expressions can also be injected', async () => {
+      const el = document.createElement('div');
+
+      // Attacker injects expression to access context
+      const attackPayload = '${secretData}';
+      el.innerHTML = `<div title="${attackPayload}">Leaked</div>`;
+
+      const context = {
+        secretData: 'API_KEY_12345',
+      };
+      context.security = await initializeSecurity(context);
+
+      await processNode(el, context);
+
+      // Attacker successfully read secret from context
+      const innerDiv = el.querySelector('div');
+      expect(innerDiv.getAttribute('title')).to.equal('API_KEY_12345');
+    });
+  });
+});