orb_template 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98fc53086cd1c46931fe172054e9d07303854ce48d5ea2b2667345c72e0daa45
-  data.tar.gz: 3d1d62b625fa306e999e0b0d9579973344909131e4e2b6b42338622518117ae8
+  metadata.gz: 9cef68c21c57f074ee08bb76aacb4d88df41ff5726ca65cf3ef1c579e5d56e8d
+  data.tar.gz: 3fb10347aada2d9fcd845e8590aaea771c2260b907cdc55f87927ff2afde44de
 SHA512:
-  metadata.gz: 6e5f3a157abd9c9969dbe3db559c5c1127024b4b206ae67395040758f265cfea20c16830c5b63b209b645aedc061437afb16fc9a1b3dc6f42d56f9a2c0d9a8ab
-  data.tar.gz: e1b09da4e72c9296c85c306a990ce120a53fdcdbea05148c89398ceaa3fb90e208df837e3041eaa7a95a8a4886d97ac2e4057d65cbcb4ebd1825a31ceea3f31f
+  metadata.gz: 05debe94445dee051e126bf574ba1ed3d2ea93030fe86225261da50ae33af39c7d77b75d9b7f2607e98b655c8076c83a4dc5c111ef8810292353d1f2104fdb65
+  data.tar.gz: 9a2469f3a8a7379f84cbcf3bd78644b15f7bc89e5da2c350d73e9b82c60cbf8f97dff305bee834a470b4021c2a685aee672a1a6fb1097e0fdf9c7eef53eee0f2

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-11-04
+
+### Changed
+
+- **Breaking:** Require Ruby 3.4 or newer.
+- `ORB.html_escape` now delegates to `Temple::Utils.escape_html`. (`lib/orb.rb`)
+- `make test` now also runs the benchmark suite, and `make trivy` lists lower-severity findings without failing on them.
+
+### Fixed
+
+- Stop loading `cgi/util`, which removes the load warning on Ruby 4.0. `ORB.html_escape` still handles non-ASCII-compatible strings such as UTF-16 and returns them in their original encoding. (`lib/orb.rb`)
+- `ORB::VERSION` is now defined after `require "orb"`. Previously it raised `NameError` when the gem was loaded outside bundler. (`lib/orb.rb`)
+
 ## [0.2.5] - 2026-04-28
 
 ### Added

data/lib/orb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ORB
-  VERSION = "0.2.5"
+  VERSION = "0.3.0"
 end

data/lib/orb.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 require 'temple'
-require 'cgi/util'
 
+require_relative "orb/version"
 require_relative "orb/errors"
 require_relative "orb/token"
 require_relative "orb/tokenizer"
@@ -34,7 +34,11 @@ module ORB
   end
 
   def self.html_escape(str)
-    CGI.escapeHTML(str.to_s)
+    str = str.to_s
+    return ::Temple::Utils.escape_html(str) if str.encoding.ascii_compatible?
+
+    # The native escaper can't handle encodings such as UTF-16 on Ruby 3.4.
+    ::Temple::Utils.escape_html(str.encode(Encoding::UTF_8)).encode(str.encoding)
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: orb_template
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - KUY.io Inc.
@@ -34,13 +34,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
 - LICENSE.txt
-- Makefile
 - README.md
-- Rakefile
-- docs/2026-03-12-security-analysis.md
-- docs/2026-04-27-unwrap-poposal.md
 - lib/orb.rb
 - lib/orb/ast.rb
 - lib/orb/ast/abstract_node.rb
@@ -93,14 +88,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.23
 specification_version: 4
 summary: The ORB template language for Ruby.
 test_files: []

data/CODE_OF_CONDUCT.md

@@ -1,132 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
-  community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of
-  any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
-  without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official email address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-[INSERT CONTACT METHOD].
-All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of
-actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the
-community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
-
-Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
-
-For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
-[https://www.contributor-covenant.org/translations][translations].
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations

data/Makefile

@@ -1,57 +0,0 @@
-# Makefile for ORB Ruby Gem
-
-.PHONY: all test build clean install lint spec benchmark security help
-
-# Default target
-all: test build
-
-# Run test suite (excludes benchmarks)
-spec:
-	bundle exec rake test
-
-# Run benchmark suite
-benchmark:
-	bundle exec rake benchmark
-
-# Build the gem
-build:
-	gem build orb_template.gemspec
-
-# Deploy to RubyGems (requires authentication)
-deploy: build
-	gem push orb_template-*.gem
-
-# Clean build artifacts
-clean:
-	rm -f *.gem
-
-# Install the gem locally
-install: build
-	gem install orb_template-*.gem
-
-# Run linting
-lint:
-	bundle exec rubocop
-
-# Security scanning (dependency audit, static analysis, filesystem scan)
-security:
-	bundle exec bundle-audit check --update
-	bundle exec brakeman --no-pager -q -p test/dummy
-	trivy fs --scanners vuln,secret,misconfig .
-
-# Run specs, linting, security, and benchmarks
-test: spec lint security benchmark
-
-# Show help
-help:
-	@echo "Available targets:"
-	@echo "  all     - Run tests and build the gem (default)"
-	@echo "  test    - Run both specs and linting"
-	@echo "  build   - Build the gem package"
-	@echo "  install - Build and install the gem locally"
-	@echo "  clean   - Remove built gem files"
-	@echo "  spec      - Run the test suite (excludes benchmarks)"
-	@echo "  benchmark - Run the benchmark suite"
-	@echo "  lint      - Run RuboCop linting"
-	@echo "  security  - Run security scans (bundler-audit, brakeman, trivy)"
-	@echo "  help      - Show this help message"

data/Rakefile

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rubocop/rake_task"
-require "rake/testtask"
-
-RuboCop::RakeTask.new
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList['test/**/*_test.rb'].exclude('test/benchmark_test.rb')
-end
-
-Rake::TestTask.new(:benchmark) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList['test/benchmark_test.rb']
-end
-
-task default: %i[rubocop test]

data/docs/2026-03-12-security-analysis.md

@@ -1,715 +0,0 @@
-# ORB Template Engine -- Security Analysis
-
-**Date:** 2026-03-12
-**Version Reviewed:** 0.1.3
-**Scope:** Tokenizer2, Parser, AST Builder, Temple Compiler, Filters, Attributes Compiler, Rails Template Handler
-
----
-
-## Executive Summary
-
-ORB is a JSX-inspired template engine for Ruby/Rails that compiles templates to Ruby code via the Temple pipeline. The overall architecture is sound -- it uses Temple's `:escape` mechanism for auto-escaping `{{...}}` output and avoids direct `eval()` of raw user strings. However, this review identified several vulnerabilities ranging from **critical** to **low** severity, many of which mirror historical CVEs in ERB, HAML, and SLIM template engines.
-
-The primary risk areas are:
-
-- Code injection through directive values and expressions interpolated into generated Ruby code
-- Missing HTML escaping on dynamic attribute values
-- Insufficient validation of tag names, attribute names, and `:for` expressions
-
-Note: Like ERB, HAML, and SLIM, ORB executes arbitrary Ruby in template expressions (`{{...}}` and `{%...%}`). This is by design and follows the same trust model -- templates are developer-authored and loaded from the filesystem. This is documented as informational, not as a vulnerability.
-
----
-
-## Data Flow Overview
-
-```
-ORB Template Source (text)
-        |
-        v
-  [Tokenizer2]          lib/orb/tokenizer2.rb    -- Lexical analysis via StringScanner
-        |
-        v
-  Token Stream
-        |
-        v
-  [Parser]               lib/orb/parser.rb        -- Token-to-AST conversion
-        |
-        v
-  AST (Abstract Syntax Tree)
-        |
-        v
-  [Temple::Compiler]     lib/orb/temple/compiler.rb   -- AST to Temple IR
-        |
-        v
-  [Temple::Filters]      lib/orb/temple/filters.rb    -- Component/block handling
-        |
-        v
-  [Temple Pipeline]      lib/orb/temple/engine.rb     -- Escaping, static analysis, optimization
-        |
-        v
-  Generated Ruby Code
-        |
-        v
-  [Rails ActionView]     lib/orb/rails_template.rb    -- Template handler execution
-        |
-        v
-  HTML Output
-```
-
-Security-sensitive boundaries exist at every stage. The most critical are:
-
-1. **Tokenizer -> Parser**: What syntax is accepted and how expressions are delimited
-2. **Compiler -> Filters**: How expressions, directives, and attributes are interpolated into Ruby code
-3. **Filters -> Temple Pipeline**: Whether dynamic values are wrapped in escape directives
-4. **Generated Code -> Rails**: What code executes in the view binding
-
----
-
-## INFORMATIONAL Findings
-
-### INFO-1: Server-Side Template Injection via `{%...%}` Control Expressions
-
-**Location:** `lib/orb/temple/compiler.rb:120-123`
-
-Control expressions compile directly to `:code` Temple expressions, allowing arbitrary Ruby execution. This is equivalent to ERB's `<% %>`, HAML's `- code`, and SLIM's `- code` -- it is a fundamental feature of any code-executing template language, not a vulnerability in ORB specifically.
-
-Templates are authored by developers and loaded from the filesystem via Rails' template resolver, which restricts to the application's view paths. The same trust model applies as with ERB.
-
-**Mitigation:** Document that ORB templates must not be constructed from user input (same guidance as ERB). Long-term, consider Brakeman integration to flag unsafe patterns like `ORB::Template.parse(user_string)`.
-
----
-
-### INFO-2: Server-Side Template Injection via `{{...}}` Printing Expressions
-
-**Location:** `lib/orb/temple/compiler.rb:109`
-
-Printing expressions execute arbitrary Ruby in the template binding (output is HTML-escaped). This is equivalent to ERB's `<%= %>`. Same trust model as INFO-1 applies.
-
-**Mitigation:** Documentation only. Same as ERB.
-
----
-
-### INFO-3: Error Messages Expose Internal Tokenizer State
-
-**Location:** `lib/orb/tokenizer2.rb:617`
-
-Error messages include internal tokenizer state names (`:printing_expression`, `:control_expression`, etc.). In development mode, this is intentional and helpful for debugging -- the same behavior as ERB, HAML, and SLIM. In production, Rails rescues exceptions and shows a generic error page, so these details are only visible in server logs (which are already privileged).
-
-**Mitigation:** Standard Rails error handling. Only a concern if the application is misconfigured to expose exception details in production responses.
-
----
-
-## CRITICAL Findings
-
-### CRITICAL-1: Code Injection via `:for` Directive Expression Splitting
-
-**Location:** `lib/orb/temple/filters.rb:109-116`
-
-The `:for` block handler uses a naive `split(' in ')` to separate the iterator variable from the collection:
-
-```ruby
-# lib/orb/temple/filters.rb:110-111
-def on_orb_for(expression, content)
-  enumerator, collection = expression.split(' in ')
-  code = "#{collection}.each do |#{enumerator}|"
-```
-
-Both `enumerator` and `collection` are interpolated into a Ruby code string without validation. A crafted `:for` expression can inject arbitrary code:
-
-```orb
-{#for x in [1]; system("pwned"); [2]}
-  ...
-{/for}
-```
-
-This generates: `[1]; system("pwned"); [2].each do |x|`
-
-The `enumerator` side is also injectable:
-
-```orb
-{#for x| ; system("pwned") ; |y in items}
-```
-
-**Impact:** Arbitrary code execution via crafted template source.
-
-**Recommendation:** Parse and validate the `:for` expression with a strict regex that only allows `variable_name in expression` patterns, where `variable_name` must be a valid Ruby identifier. Additionally, reject semicolons in the collection expression to prevent statement injection.
-
-**Mitigation (applied):** In `lib/orb/temple/filters.rb:109-121`, the `on_orb_for` method now uses a strict regex to parse the `:for` expression and rejects semicolons in the collection:
-
-```ruby
-# Before
-def on_orb_for(expression, content)
-  enumerator, collection = expression.split(' in ')
-  code = "#{collection}.each do |#{enumerator}|"
-
-# After
-def on_orb_for(expression, content)
-  match = expression.match(/\A\s*([a-z_]\w*)\s+in\s+(.+)\z/m)
-  raise ORB::SyntaxError.new("Invalid :for expression: enumerator must be a valid Ruby identifier", 0) unless match
-
-  enumerator, collection = match[1], match[2]
-
-  if collection.include?(';')
-    raise ORB::SyntaxError.new("Invalid :for collection expression: semicolons are not allowed", 0)
-  end
-
-  code = "#{collection}.each do |#{enumerator}|"
-```
-
-The enumerator is now validated as a Ruby identifier (`[a-z_]\w*`), preventing pipe-delimiter injection. The collection is checked for semicolons, preventing statement injection. Both attack vectors now raise `ORB::SyntaxError` at compile time. Normal `:for` usage (`{#for item in items}`) is unaffected.
-
-**Evidence:** All 4 CRITICAL-1 tests now pass. Full test suite (123 runs) shows 14 expected failures for unmitigated findings, 0 errors, 0 regressions.
-
----
-
-## HIGH Findings
-
-### HIGH-1: XSS via Unescaped Dynamic Attribute Values
-
-**Location:** `lib/orb/temple/attributes_compiler.rb:91-93`
-**Analogous CVEs:** CVE-2017-1002201 (HAML attribute XSS), CVE-2016-6316 (Rails Action View attribute XSS)
-
-Dynamic attribute expressions are emitted as `[:dynamic, ...]` without an explicit `[:escape, true, ...]` wrapper:
-
-```ruby
-# lib/orb/temple/attributes_compiler.rb:91-93
-elsif attribute.expression?
-  [:html, :attr, attribute.name, [:dynamic, attribute.value]]
-end
-```
-
-Compare with printing expressions which always use `[:escape, true, [:dynamic, ...]]` (compiler.rb:109).
-
-Whether this is safe depends on Temple's downstream `Escapable` filter configuration and how `[:html, :attr, ...]` is processed. If the value is not escaped by the pipeline, an attacker could inject through attribute context:
-
-```orb
-<div class={user_input}>
-<!-- if user_input = '"><script>alert(1)</script><div class="' -->
-<!-- renders: <div class=""><script>alert(1)</script><div class=""> -->
-```
-
-**Impact:** Cross-site scripting (XSS) if dynamic attribute values are not escaped by the Temple pipeline. Unlike the template-authoring-only findings, this is exploitable at **runtime** through malicious data in any variable used in a dynamic attribute -- no template source compromise required.
-
-**Recommendation:** Explicitly wrap dynamic attribute values: `[:html, :attr, attribute.name, [:escape, true, [:dynamic, attribute.value]]]`
-
-**Mitigation (applied):** In `lib/orb/temple/attributes_compiler.rb:92`, the `compile_attribute` method now wraps expression attributes with `[:escape, true, ...]`:
-
-```ruby
-# Before
-[:html, :attr, attribute.name, [:dynamic, attribute.value]]
-
-# After
-[:html, :attr, attribute.name, [:escape, true, [:dynamic, attribute.value]]]
-```
-
-This causes Temple's `Escapable` filter to emit `::Temple::Utils.escape_html(...)` around dynamic attribute values, matching the escaping behavior already applied to printing expressions (`{{...}}`). Static and boolean attributes are unaffected. Existing assertions in `test/temple_compiler_test.rb` were updated to expect the new escaped IR.
-
-**Evidence:** `test_dynamic_attribute_value_is_escaped` now passes. Full test suite (123 runs) shows no regressions beyond the 18 expected security test failures for unmitigated findings.
-
----
-
-### HIGH-2: Code Injection via `:with` Directive in Block Parameters
-
-**Location:** `lib/orb/temple/filters.rb:37, 46, 80, 83`
-
-The `:with` directive value is used directly as a Ruby block parameter name without validation:
-
-```ruby
-# lib/orb/temple/filters.rb:37
-block_name = node.directives.fetch(:with, block_name)
-# ...
-# lib/orb/temple/filters.rb:46
-code = "render #{komponent_name}.new(#{args}) do |#{block_name}|"
-```
-
-A crafted `:with` directive can inject code into the block parameter position:
-
-```orb
-<MyComponent :with="x| ; system('pwned') ; |y">
-```
-
-Generates: `render MyComponent.new() do |x| ; system('pwned') ; |y|`
-
-The same vulnerability exists in slot rendering (filters.rb:80-83).
-
-**Impact:** Arbitrary code execution via crafted template source.
-
-**Recommendation:** Validate that `:with` values match `/\A[a-z_][a-zA-Z0-9_]*\z/` (valid Ruby identifier).
-
-**Mitigation (applied):** In `lib/orb/temple/filters.rb`, both `on_orb_component` and `on_orb_slot` now validate the block name after resolving the `:with` directive:
-
-```ruby
-block_name = node.directives.fetch(:with, block_name)
-unless block_name.match?(/\A[a-z_]\w*\z/)
-  raise ORB::SyntaxError.new("Invalid :with directive value: must be a valid Ruby identifier", 0)
-end
-```
-
-This validation applies to both explicit `:with` values and the auto-generated default block names, providing defense-in-depth against malicious tag/slot names that produce invalid default identifiers (also catches HIGH-4 and HIGH-5 attack vectors as a side effect).
-
-**Evidence:** `test_with_directive_component_injection_is_rejected` and `test_with_directive_slot_injection_is_rejected` now pass. Full test suite (86 non-security runs) shows no regressions.
-
----
-
-### HIGH-3: Unsafe Tag Name Interpolation in Dynamic Tags
-
-**Location:** `lib/orb/temple/filters.rb:130`
-
-```ruby
-code = "content_tag('#{node.tag}', #{splats}) do"
-```
-
-The tag name is interpolated into a single-quoted Ruby string. The `TAG_NAME` pattern (`[^\s>/=$]+` in patterns.rb:6) allows single quotes, semicolons, and parentheses. Since spaces are not allowed in tag names, the injection must be crafted without spaces:
-
-```orb
-<div');system(:pwned);content_tag('x **{attrs}>content</div');system(:pwned);content_tag('x>
-```
-
-This generates:
-
-```ruby
-content_tag('div');system(:pwned);content_tag('x', **attrs) do
-```
-
-**Impact:** Arbitrary code execution via crafted tag name in templates using splat attributes.
-
-**Recommendation:** Validate tag names against a strict pattern (alphanumeric, hyphens, dots, colons only) before interpolating into generated code.
-
-**Mitigation (applied):** In `lib/orb/temple/filters.rb`, a `VALID_HTML_TAG_NAME` constant (`/\A[a-zA-Z][a-zA-Z0-9-]*\z/`) is declared and checked in `on_orb_dynamic` before the tag name is interpolated:
-
-```ruby
-VALID_HTML_TAG_NAME = /\A[a-zA-Z][a-zA-Z0-9-]*\z/
-
-# In on_orb_dynamic, HTML tag branch:
-unless node.tag.match?(VALID_HTML_TAG_NAME)
-  raise ORB::SyntaxError.new("Invalid tag name: #{node.tag.inspect}", 0)
-end
-```
-
-This allows standard HTML tags (`div`, `h1`, `my-element`) but rejects quotes, semicolons, parentheses, and other characters that could break out of the generated string literal. Components and slots are dispatched before this branch and are not affected.
-
-**Evidence:** `test_dynamic_tag_name_injection_is_rejected` and `test_dynamic_tag_name_with_quote_is_rejected` now pass. Full test suite (86 non-security runs) shows no regressions.
-
----
-
-### HIGH-4: Unvalidated Component Name Used as Ruby Constant
-
-**Location:** `lib/orb/temple/filters.rb:32-34`
-
-```ruby
-name = node.tag.gsub('.', '::')
-komponent = ORB.lookup_component(name)
-komponent_name = komponent || name  # Falls back to raw tag name
-```
-
-If a component is not found via `lookup_component`, the raw tag name (with `.` replaced by `::`) is used directly in a `render` call:
-
-```ruby
-code = "render #{komponent_name}.new(#{args}) do |#{block_name}|"
-```
-
-This can be exploited to call arbitrary methods by leveraging the `.new()` chain. The `TAG_NAME` pattern allows parentheses, so a component name like `Kernel.exit(1)` generates:
-
-```ruby
-render Kernel::exit(1).new() do |...|
-```
-
-`Kernel::exit(1)` executes immediately (terminating the process) before `.new()` is ever reached.
-
-**Impact:** Arbitrary method calls on any Ruby constant reachable in the namespace. Process termination, code execution, or other side effects depending on the target class/method.
-
-**Recommendation:** Validate that resolved component names only contain expected characters (`A-Z`, `a-z`, `0-9`, `::`) and optionally maintain an allowlist of component namespaces.
-
-**Mitigation (applied):** In `lib/orb/temple/filters.rb`, a `VALID_COMPONENT_NAME` constant (`/\A[A-Z]\w*(::[A-Z]\w*)*\z/`) is declared and checked in `on_orb_component` after name resolution:
-
-```ruby
-VALID_COMPONENT_NAME = /\A[A-Z]\w*(::[A-Z]\w*)*\z/
-
-# In on_orb_component:
-komponent_name = komponent || name
-unless komponent_name.match?(VALID_COMPONENT_NAME)
-  raise ORB::SyntaxError.new("Invalid component name: #{komponent_name.inspect}", 0)
-end
-```
-
-This allows `Card`, `Demo::Card`, `UI::Forms::Input` but rejects names containing parentheses, semicolons, or lowercase-starting segments. The validation runs on the *resolved* name (after `lookup_component`), covering both the lookup result and the raw fallback.
-
-**Breaking change:** Templates using `<Foo::bar>` style slot syntax will now raise a `SyntaxError`. The canonical slot syntax `<Foo:Bar>` should be used instead.
-
-**Evidence:** `test_component_name_method_call_injection_is_rejected` and `test_component_name_semicolon_injection_is_rejected` pass (now with proper validation, not just the HIGH-2 side effect). The `:with` bypass is also blocked. Full test suite (86 non-security runs) shows no regressions.
-
----
-
-### HIGH-5: Code Injection via Unvalidated Slot Names
-
-**Location:** `lib/orb/temple/filters.rb:78-83`
-
-Slot names are derived from the tag name portion after `:` (e.g. `Card:Header` -> slot `header`) and interpolated into a method call without validation:
-
-```ruby
-# lib/orb/temple/filters.rb:78-83
-slot_name = node.slot  # tag.split(':').last.underscore
-code = "#{parent_name}.with_#{slot_name}(#{args}) do |#{block_name}|"
-```
-
-The `TAG_NAME` pattern (`[^\s>/=$]+`) allows semicolons, parentheses, and other characters that are not valid in Ruby method names. A crafted slot name can inject arbitrary code:
-
-```orb
-<Card><Card:Foo();system(1);x>content</Card:Foo();system(1);x></Card>
-```
-
-This generates:
-
-```ruby
-__orb__card.with_foo();system(1);x() do |__orb__foo();system(1);x|
-```
-
-The `with_foo()` call closes normally, then `system(1)` executes, then `x()` begins a new expression that absorbs the rest of the generated code.
-
-**Impact:** Arbitrary code execution via crafted template source.
-
-**Recommendation:** Validate slot names against a strict pattern (valid Ruby identifier: `/\A[a-z_][a-zA-Z0-9_]*\z/`) after extraction from the tag name.
-
-**Mitigation (applied):** In `lib/orb/temple/filters.rb`, a `VALID_SLOT_NAME` constant (`/\A[a-z_]\w*\z/`) is declared and checked in `on_orb_slot` after extracting the slot name:
-
-```ruby
-VALID_SLOT_NAME = /\A[a-z_]\w*\z/
-
-# In on_orb_slot:
-slot_name = node.slot
-unless slot_name.match?(VALID_SLOT_NAME)
-  raise ORB::SyntaxError.new("Invalid slot name: #{slot_name.inspect}", 0)
-end
-```
-
-This allows `header`, `side_bar`, `footer_content` but rejects parentheses, semicolons, and anything that isn't a plain Ruby identifier. The validation is independent of the HIGH-2 `:with` check, so it cannot be bypassed by supplying a valid `:with` directive.
-
-**Evidence:** `test_slot_name_semicolon_injection_is_rejected` and `test_slot_name_with_parens_is_rejected` pass. The `:with` bypass is also blocked. Full test suite (86 non-security runs) shows no regressions.
-
----
-
-## MEDIUM Findings
-
-### MEDIUM-1: Denial of Service via Unbounded Brace Nesting
-
-**Location:** `lib/orb/tokenizer2.rb:260-284`
-
-The brace-tracking mechanism (`@braces` array) has no depth limit. A malicious template with deeply nested braces consumes unbounded memory:
-
-```
-{{ {{{{{{{{{{{...millions of opening braces...}}}}}}}}}}} }}
-```
-
-**Impact:** Memory exhaustion, denial of service.
-
-**Recommendation:** Enforce a maximum nesting depth (e.g., 100 levels) and raise a `SyntaxError` when exceeded.
-
-**Mitigation (applied):** In `lib/orb/tokenizer2.rb`, a `MAX_BRACE_DEPTH` constant (100) is declared and enforced via a `push_brace` helper that replaces all direct `@braces << "{"` calls:
-
-```ruby
-MAX_BRACE_DEPTH = 100
-
-def push_brace
-  if @braces.length >= MAX_BRACE_DEPTH
-    raise ORB::SyntaxError.new("Maximum brace nesting depth (#{MAX_BRACE_DEPTH}) exceeded", @line)
-  end
-  @braces << "{"
-end
-```
-
-All 5 brace-push sites in the tokenizer (`next_in_attribute_value_expression`, `next_in_splat_attribute_expression`, `next_in_block_open_content`, `next_in_printing_expression`, `next_in_control_expression`) now call `push_brace` instead of pushing directly. Moderate nesting (e.g., nested hashes) works fine; only pathological depths are rejected.
-
-**Evidence:** `test_deeply_nested_braces_in_expression_raises_error` and `test_deeply_nested_braces_in_attribute_raises_error` now pass. `test_moderate_brace_nesting_works` remains green. Full test suite (86 non-security runs) shows no regressions.
-
----
-
-### MEDIUM-2: OpenStruct-based RenderContext Exposes Introspection
-
-**Location:** `lib/orb/render_context.rb:26`
-
-```ruby
-OpenStruct.new(@assigns).instance_eval { binding }
-```
-
-`OpenStruct` inherits from `Object`, exposing all `Object` methods to template expressions:
-
-```
-{{ self.class }}                          # => OpenStruct
-{{ self.class.ancestors }}                # => full class hierarchy
-{{ instance_variable_get(:@table) }}      # => all assigns as hash
-{{ self.methods.sort }}                   # => available methods
-{{ self.send(:system, "id") }}            # => command execution via send
-```
-
-**Impact:** Template expressions (in the standalone `Template` class path) can introspect and exploit the full Ruby object model.
-
-**Recommendation:** Use a `BasicObject` subclass instead of `OpenStruct` to minimize the available attack surface. Only expose explicitly allowed methods.
-
----
-
-### MEDIUM-3: `runtime_error` String Delimiter Breakout
-
-**Location:** `lib/orb/temple/compiler.rb:199`
-
-```ruby
-temple << [:code, %[raise ORB::Error.new(%q[#{error.message}], #{error.line.inspect})]]
-```
-
-Error messages are interpolated into a `%q[...]` string literal. The `%q[]` delimiter uses square brackets, meaning an error message containing `]` would prematurely close the string, potentially allowing code injection via crafted error messages.
-
-**Impact:** If an attacker can trigger a specific error message containing `]`, the generated code could be malformed or injectable.
-
-**Recommendation:** Use a delimiter that cannot appear in error messages (e.g., `%q{...}` with brace counting, or properly escape the content), or use `String#inspect` to safely serialize the message.
-
-**Mitigation (applied):** In `lib/orb/temple/compiler.rb:199`, replaced `%q[#{error.message}]` with `#{error.message.inspect}`:
-
-```ruby
-# Before
-temple << [:code, %[raise ORB::Error.new(%q[#{error.message}], #{error.line.inspect})]]
-
-# After
-temple << [:code, "raise ORB::Error.new(#{error.message.inspect}, #{error.line.inspect})"]
-```
-
-`String#inspect` produces a properly escaped double-quoted Ruby string literal. Any `]`, `"`, `\`, or other special characters are escaped, making delimiter breakout impossible. The generated code is always a single valid `raise` statement.
-
-**Evidence:** `test_runtime_error_with_bracket_produces_valid_ruby` and `test_runtime_error_code_injection_is_rejected` now pass. Full test suite (86 non-security runs) shows no regressions.
-
----
-
-### MEDIUM-4: Attribute Name Injection
-
-**Location:** `lib/orb/patterns.rb:7`
-
-```ruby
-ATTRIBUTE_NAME = %r{[^\s>/=]+}
-```
-
-This pattern allows nearly any character in attribute names, including:
-
-- Event handlers: `onclick`, `onmouseover`, `onfocus`
-- Quote characters: `"`, `'` (could break attribute context)
-- Backticks, semicolons, and other special characters
-
-**Analogous CVE:** CVE-2017-1002201 (HAML attribute injection via unescaped characters)
-
-While ORB templates are typically authored by developers (not end users), the permissive pattern means:
-
-1. No compile-time validation catches typos that could be security-relevant
-2. If attribute names ever come from dynamic sources (e.g., splat attributes), injection is possible
-
-**Recommendation:** Restrict `ATTRIBUTE_NAME` to valid HTML attribute characters: `/[a-zA-Z_:][-a-zA-Z0-9_:.]*` per the HTML spec, or at minimum disallow quotes and backticks.
-
-**Mitigation (applied):** In `lib/orb/patterns.rb:7`, replaced the permissive pattern with a strict HTML-spec-compliant one:
-
-```ruby
-# Before
-ATTRIBUTE_NAME = %r{[^\s>/=]+}
-
-# After
-ATTRIBUTE_NAME = %r{[a-zA-Z_:][-a-zA-Z0-9_:.]*}
-```
-
-This allows standard attribute names (`class`, `data-value`, `aria-label`, `xml:lang`) and ORB directives (`:for`, `:with`) while rejecting quotes, backticks, semicolons, and other characters that could break HTML attribute context. Invalid characters in attribute position are now silently ignored by the tokenizer (the scanner won't match them as attribute names).
-
-**Evidence:** `test_attribute_name_with_single_quote_is_rejected`, `test_attribute_name_with_backtick_is_rejected`, and `test_attribute_name_with_double_quote_is_rejected` all pass. `test_valid_attribute_names_compile_correctly` remains green. Full test suite (86 non-security runs) shows no regressions.
-
----
-
-## LOW Findings
-
-### LOW-1: Verbatim Mode Bypasses All Processing
-
-**Location:** `lib/orb/tokenizer2.rb:146-152`
-
-The `$>` closing syntax enables verbatim mode, where content passes through without any processing or escaping:
-
-```orb
-<script$>
-  var x = "user controlled data here passes through raw";
-</script>
-```
-
-This is intentional behavior for `<script>` and `<style>` tags, but developers unfamiliar with ORB may not realize that verbatim content is never escaped.
-
-**Recommendation:** Document this behavior clearly. Consider requiring an explicit opt-in rather than a syntactic marker.
-
----
-
-### LOW-2: Public Comments Pass Content as Static (Unescaped)
-
-**Location:** `lib/orb/temple/compiler.rb:155`
-
-```ruby
-def transform_public_comment_node(node, _context)
-  [:html, :comment, [:static, node.text]]
-end
-```
-
-Comment text is emitted as `[:static, ...]`. If comment content somehow contains `-->`, it could break out of the HTML comment context. However, since the tokenizer terminates comment parsing at `-->`, the text content would not contain this sequence under normal operation.
-
-**Impact:** Minimal under current tokenizer behavior. Only relevant if the tokenizer is bypassed or modified.
-
----
-
-### LOW-3: No Template Size Limit
-
-**Location:** `lib/orb/tokenizer2.rb:26-27`
-
-```ruby
-def initialize(source, options = {})
-  @source = StringScanner.new(source)
-```
-
-There is no limit on template source size. An extremely large template could cause excessive memory usage and CPU consumption during tokenization.
-
-**Recommendation:** Consider enforcing a configurable maximum template size.
-
-**Mitigation (applied):** In `lib/orb/tokenizer2.rb`, a `MAX_TEMPLATE_SIZE` constant (2MB) is declared and checked at the start of `tokenize`:
-
-```ruby
-MAX_TEMPLATE_SIZE = 2 * 1024 * 1024  # 2MB
-
-def tokenize
-  if @source.string.bytesize > MAX_TEMPLATE_SIZE
-    raise ORB::SyntaxError.new("Template exceeds maximum size (#{MAX_TEMPLATE_SIZE} bytes)", 0)
-  end
-  # ...
-```
-
-2MB is generous for any real template while preventing abuse. Templates exceeding this limit are rejected before any scanning begins.
-
-**Evidence:** `test_large_template_has_size_limit` now passes. `test_normal_sized_template_works` remains green. Full test suite (86 non-security runs) shows no regressions.
-
----
-
-### LOW-4: Potential ReDoS in Block Detection Regex
-
-**Location:** `lib/orb/ast/printing_expression_node.rb:7`
-
-```ruby
-BLOCK_RE = /\A(if|unless)\b|\bdo\s*(\|[^|]*\|)?\s*$/
-```
-
-The `\s*` quantifiers combined with `$` could cause quadratic backtracking on inputs with many trailing whitespace characters followed by a non-matching character. The practical impact is limited because expression values are typically short.
-
-**Recommendation:** Use possessive quantifiers or atomic groups if available: `\s*+` or `(?>\\s*)`.
-
----
-
-## Comparison with Historical CVEs
-
-| CVE | Engine | Vulnerability | ORB Applicability |
-|-----|--------|--------------|-------------------|
-| **CVE-2016-0752** | ERB/Rails | SSTI via dynamic `render` with user input | **Informational** -- `{%...%}` and `{{...}}` allow arbitrary Ruby execution, same as ERB (INFO-1, INFO-2) |
-| **CVE-2017-1002201** | HAML | XSS via unescaped apostrophes in attributes | **Applicable** -- dynamic attribute values may lack escaping (HIGH-1); attribute names allow quotes (MEDIUM-4) |
-| **CVE-2016-6316** | Rails/HAML | XSS in `html_safe` attribute values in tag helpers | **Partially applicable** -- interaction with `use_html_safe: true` option and Temple escaping pipeline needs verification (HIGH-1) |
-| **CVE-2019-5418** | Rails | Path traversal via `render file:` with user input | **Not applicable** -- ORB does not support file includes or partial rendering by path |
-| **CVE-2021-32818** | haml-coffee | RCE via configuration parameter pollution | **Not applicable** -- different architecture, no user-accessible configuration |
-| SLIM XSS (Sqreen) | SLIM | XSS through `==` unescaped output and attribute injection | **Partially applicable** -- ORB's `{%...%}` is analogous to SLIM's `==` (no output escaping for control expressions) |
-
----
-
-## Recommendations (Priority Order)
-
-### Immediate (Before Public Release)
-
-1. **Document SSTI risk** -- Add a Security section to README warning that ORB templates must never be constructed from user input. This is the single most important action.
-
-2. **Escape dynamic attribute values** -- In `attributes_compiler.rb:91-93`, wrap dynamic attribute values:
-   ```ruby
-   [:html, :attr, attribute.name, [:escape, true, [:dynamic, attribute.value]]]
-   ```
-
-3. **Validate `:for` expression syntax** -- Replace `split(' in ')` with a strict parser:
-   ```ruby
-   match = expression.match(/\A\s*([a-z_]\w*)\s+in\s+(.+)\z/m)
-   raise CompilerError, "Invalid :for expression" unless match
-   enumerator, collection = match[1], match[2]
-   ```
-
-4. **Validate `:with` directive values** -- Ensure block parameter names are valid Ruby identifiers:
-   ```ruby
-   unless block_name.match?(/\A[a-z_]\w*\z/)
-     raise CompilerError, "Invalid :with value: must be a valid identifier"
-   end
-   ```
-
-5. **Validate tag names before code interpolation** -- In `filters.rb`, validate before string interpolation:
-   ```ruby
-   unless node.tag.match?(/\A[a-zA-Z][a-zA-Z0-9._:-]*\z/)
-     raise CompilerError, "Invalid tag name: #{node.tag}"
-   end
-   ```
-
-6. **Validate slot names** -- After extracting the slot name from the tag, validate it is a valid Ruby identifier:
-   ```ruby
-   unless slot_name.match?(/\A[a-z_][a-zA-Z0-9_]*\z/)
-     raise CompilerError, "Invalid slot name: #{slot_name}"
-   end
-   ```
-
-### Short Term
-
-7. **Fix `runtime_error` string delimiter** -- Use `String#inspect` for safe serialization of error messages.
-
-8. **Add brace nesting depth limit** -- Cap at a reasonable depth (e.g., 100) in the tokenizer.
-
-9. **Restrict `ATTRIBUTE_NAME` pattern** -- Use `/[a-zA-Z_:][-a-zA-Z0-9_:.]*` or similar.
-
-### Long Term
-
-10. **Consider a restricted execution mode** -- A "safe mode" that limits available methods in template expressions, similar to Liquid's approach.
-
-11. **Integrate with Brakeman** -- Add ORB-specific checks for common vulnerability patterns.
-
-12. **Replace `OpenStruct` in `RenderContext`** -- Use a `BasicObject` subclass to minimize attack surface for standalone template rendering.
-
-13. **Add template size and complexity limits** -- Configurable maximums for source size, nesting depth, and expression count.
-
----
-
-## Test Coverage
-
-All findings are covered by regression tests in `test/security_test.rb`. Tests are written to **fail** until the corresponding fix is applied, then pass once mitigated.
-
-| Finding | Test(s) | Status |
-|---------|---------|--------|
-| **CRITICAL-1** (:for injection) | `test_for_collection_injection_is_rejected`, `test_for_collection_injection_absent_from_temple_ir`, `test_for_enumerator_injection_is_rejected`, `test_for_directive_attribute_injection_is_rejected` | PASSING (4) -- mitigated |
-| **HIGH-1** (attribute XSS) | `test_dynamic_attribute_value_is_escaped` | PASSING (1) -- mitigated |
-| **HIGH-2** (:with injection) | `test_with_directive_component_injection_is_rejected`, `test_with_directive_slot_injection_is_rejected` | PASSING (2) -- mitigated |
-| **HIGH-3** (tag name injection) | `test_dynamic_tag_name_injection_is_rejected`, `test_dynamic_tag_name_with_quote_is_rejected` | PASSING (2) -- mitigated |
-| **HIGH-4** (component name injection) | `test_component_name_method_call_injection_is_rejected`, `test_component_name_semicolon_injection_is_rejected` | PASSING (2) -- mitigated |
-| **HIGH-5** (slot name injection) | `test_slot_name_semicolon_injection_is_rejected`, `test_slot_name_with_parens_is_rejected` | PASSING (2) -- mitigated |
-| **MEDIUM-1** (brace nesting DoS) | `test_deeply_nested_braces_in_expression_raises_error`, `test_deeply_nested_braces_in_attribute_raises_error` | PASSING (2) -- mitigated |
-| **MEDIUM-3** (runtime_error breakout) | `test_runtime_error_with_bracket_produces_valid_ruby`, `test_runtime_error_code_injection_is_rejected` | PASSING (2) -- mitigated |
-| **MEDIUM-4** (attribute name injection) | `test_attribute_name_with_single_quote_is_rejected`, `test_attribute_name_with_backtick_is_rejected` | PASSING (2) -- mitigated |
-| **LOW-1** (verbatim bypass) | `test_verbatim_mode_does_not_process_expressions`, `test_verbatim_mode_passes_html_through_raw` | PASSING (2) |
-| **LOW-2** (comment delimiter) | `test_comment_content_terminates_at_closing_delimiter` | PASSING (1) |
-| **LOW-3** (no size limit) | `test_large_template_has_size_limit` | PASSING (1) -- mitigated |
-| **LOW-4** (ReDoS) | `test_block_regex_handles_pathological_input` | PASSING (1) |
-
-Baseline tests (expected to always pass): `test_printing_expression_is_escaped_baseline`, `test_static_attribute_value_needs_no_runtime_escape`, `test_with_directive_normal_usage_compiles_correctly`, `test_dynamic_tag_normal_usage_compiles_correctly`, `test_component_name_dotted_namespace_compiles_correctly`, `test_slot_normal_usage_compiles_correctly`, `test_moderate_brace_nesting_works`, `test_runtime_error_normal_message_compiles_correctly`, `test_valid_attribute_names_compile_correctly`, `test_normal_sized_template_works`, `test_for_block_normal_usage_compiles_correctly`, `test_for_directive_normal_usage_compiles_correctly`.
-
-**Totals: 37 tests, 0 failing, 37 passing (all mitigated).**
-
-When mitigations are applied, each finding's failing tests should turn green while all baseline tests remain passing.
-
----
-
-## Methodology
-
-This review was conducted through manual source code analysis of all files in the compilation pipeline:
-
-- `lib/orb/patterns.rb` -- Regex patterns (attack surface definition)
-- `lib/orb/tokenizer2.rb` -- Lexical analysis (input parsing)
-- `lib/orb/parser.rb` -- Syntax analysis (AST construction)
-- `lib/orb/ast/*.rb` -- AST node definitions (data model)
-- `lib/orb/temple/compiler.rb` -- AST to Temple IR (code generation)
-- `lib/orb/temple/filters.rb` -- Temple filters (component/block handling)
-- `lib/orb/temple/attributes_compiler.rb` -- Attribute compilation
-- `lib/orb/temple/engine.rb` -- Temple pipeline configuration
-- `lib/orb/rails_template.rb` -- Rails integration
-- `lib/orb/render_context.rb` -- Template execution context
-
-Reference CVEs and advisories for ERB, HAML, and SLIM were consulted to identify analogous vulnerability patterns. The review focused on the data flow from template source through tokenization, parsing, AST construction, code generation, and execution.

data/docs/2026-04-27-unwrap-poposal.md

@@ -1,323 +0,0 @@
-# Proposal: `:unwrap` Directive for Orb Templates
-
-## Problem
-
-When a component should conditionally wrap its children, Orb forces you to duplicate the entire child markup:
-
-```html
-<Tooltip
-  :if="{@is_last_method}"
-  description="This is the only active login method."
->
-  <Toggle>
-    <Toggle:option
-      label="On"
-      to="{path(enabled:"
-      true)}
-      active="{@enabled}"
-      method="patch"
-      tone="success"
-    />
-    <Toggle:option
-      label="Off"
-      to="{path(enabled:"
-      false)}
-      active="{!@enabled}"
-      method="patch"
-    />
-  </Toggle>
-</Tooltip>
-{#if !@is_last_method}
-<Toggle>
-  <Toggle:option
-    label="On"
-    to="{path(enabled:"
-    true)}
-    active="{@enabled}"
-    method="patch"
-    tone="success"
-  />
-  <Toggle:option
-    label="Off"
-    to="{path(enabled:"
-    false)}
-    active="{!@enabled}"
-    method="patch"
-  />
-</Toggle>
-{/if}
-```
-
-`:if` controls whether an element **and its children** render. There is no way to say "skip the wrapper but keep the children."
-
-## Proposed Solution
-
-A new `:unwrap` directive. When the condition is true, the element is stripped and only its children are rendered. When false, the element renders normally with its children inside.
-
-```html
-<Tooltip
-  description="This is the only active login method."
-  :unwrap="{!@is_last_method}"
->
-  <Toggle>
-    <Toggle:option
-      label="On"
-      to="{path(enabled:"
-      true)}
-      active="{@enabled}"
-      method="patch"
-      tone="success"
-    />
-    <Toggle:option
-      label="Off"
-      to="{path(enabled:"
-      false)}
-      active="{!@enabled}"
-      method="patch"
-      disabled="{@is_last_method}"
-    />
-  </Toggle>
-</Tooltip>
-```
-
-One child block, zero duplication. The Tooltip renders when `@is_last_method` is true. When false, the Toggle renders directly.
-
-## Semantics
-
-`:unwrap` is a sibling to `:if`, operating on the same element but with different behavior:
-
-| Directive        | When `true`               | When `false`              |
-| ---------------- | ------------------------- | ------------------------- |
-| `:if={cond}`     | Render element + children | Render **nothing**        |
-| `:unwrap={cond}` | Render **children only**  | Render element + children |
-
-The name "unwrap" describes exactly what happens: the wrapper is removed, the children are what's left.
-
-### Interaction with `:if`
-
-Both directives can coexist on the same element. `:if` is evaluated first (it already is in the compiler). If `:if` is false, nothing renders. If `:if` is true, `:unwrap` then decides whether the element itself is included:
-
-```html
-<Tooltip description="..." :if="{@show_section}" :unwrap="{!@needs_tooltip}">
-  <Badge label="Status" />
-</Tooltip>
-```
-
-| `@show_section` | `@needs_tooltip` | Result                         |
-| --------------- | ---------------- | ------------------------------ |
-| `false`         | (any)            | Nothing                        |
-| `true`          | `true`           | `<Tooltip>` wrapping `<Badge>` |
-| `true`          | `false`          | `<Badge>` alone                |
-
-### Works on HTML elements too
-
-`:unwrap` is not component-specific. It works on any element:
-
-```html
-<div class="wrapper" :unwrap="{@minimal}">
-  <span>Always here</span>
-</div>
-```
-
-## Implementation
-
-The change touches three files in the Orb gem. No tokenizer or parser changes are needed — the existing directive parsing infrastructure handles `:unwrap` automatically.
-
-### 1. `lib/orb/ast/tag_node.rb` — Recognize `:unwrap` as a compiler directive
-
-The `compiler_directives?` method gates entry into directive processing. Rather than chaining `||` for each new directive, introduce a constant set that serves as the single source of truth for which directives the compiler handles:
-
-```ruby
-# Current (line 195-197):
-def compiler_directives?
-  directives.any? { |k, _v| k == :if || k == :for }
-end
-
-# Proposed:
-COMPILER_DIRECTIVES = %i[if unwrap for].freeze
-
-def compiler_directives?
-  directives.any? { |k, _v| COMPILER_DIRECTIVES.include?(k) }
-end
-```
-
-The constant's ordering mirrors evaluation priority (`:if` first, `:for` last) and makes it trivial to add future directives without touching the method body.
-
-### 2. `lib/orb/temple/compiler.rb` — Compile `:unwrap` into a Temple expression
-
-Refactor `transform_directives_for_tag_node` into focused handler methods. The entry point becomes a clean pipeline that shows evaluation order at a glance, while each handler encapsulates the fetch-remove-transform logic for its directive:
-
-```ruby
-# Current (lines 157-176):
-def transform_directives_for_tag_node(node)
-  # First, process any :if directives
-  if_directive = node.directives.fetch(:if, false)
-  if if_directive
-    node.remove_directive(:if)
-    return [:if,
-      if_directive,
-      transform(node)]
-  end
-
-  # Second, process any :for directives
-  for_directive = node.directives.fetch(:for, false)
-  if for_directive
-    node.remove_directive(:for)
-    return [:orb, :for, for_directive, transform(node)]
-  end
-
-  # Last, render as a dynamic node expression
-  transform(node)
-end
-
-# Proposed:
-def transform_directives_for_tag_node(node)
-  handle_if(node) || handle_unwrap(node) || handle_for(node) || transform(node)
-end
-
-private
-
-def handle_if(node)
-  directive = node.directives.fetch(:if, false)
-  return unless directive
-
-  node.remove_directive(:if)
-  [:if, directive, transform(node)]
-end
-
-def handle_unwrap(node)
-  directive = node.directives.fetch(:unwrap, false)
-  return unless directive
-
-  node.remove_directive(:unwrap)
-  [:orb, :unwrap, directive, transform(node), transform_children(node)]
-end
-
-def handle_for(node)
-  directive = node.directives.fetch(:for, false)
-  return unless directive
-
-  node.remove_directive(:for)
-  [:orb, :for, directive, transform(node)]
-end
-```
-
-The entry point reads as a priority chain: `:if` is evaluated first (can suppress everything), `:unwrap` second (can strip the wrapper), `:for` last (iterates). Each handler returns `nil` when its directive is absent, letting the chain fall through.
-
-Note: the `:unwrap` handler carries **both** the full element (`transform(node)`) and the bare children (`transform_children(node)`). This gives the filter both branches without re-parsing.
-
-### 3. `lib/orb/temple/filters.rb` — Generate the conditional output
-
-Add a handler for the `:unwrap` expression:
-
-```ruby
-# Add after on_orb_if (around line 128):
-
-# Handle an unwrap directive expression `[:orb, :unwrap, condition, element, children]`
-#
-# When condition is true, renders only the children (unwrapped).
-# When condition is false, renders the full element with children inside.
-#
-# @param [String] condition The condition to be evaluated
-# @param [Array] element The full element Temple expression
-# @param [Array] children The children-only Temple expression
-# @return [Array] compiled Temple expression
-def on_orb_unwrap(condition, element, children)
-  [:if, condition, compile(children), compile(element)]
-end
-```
-
-This generates:
-
-```ruby
-if condition
-  # children only (unwrapped)
-else
-  # full element with children
-end
-```
-
-## Compiled Output Example
-
-Given:
-
-```html
-<Tooltip description="Explanation" :unwrap="{!@is_last_method}">
-  <Badge label="Status" />
-</Tooltip>
-```
-
-The compiler produces:
-
-```ruby
-if !@is_last_method
-  # Children only — Badge renders directly
-  _v1 = render(Sirius2::Badge.new(label: "Status")) { }
-  _v1
-else
-  # Full Tooltip wrapping Badge
-  _v2 = render(Sirius2::Tooltip.new(description: "Explanation")) do |__orb__tooltip|
-    _v1 = render(Sirius2::Badge.new(label: "Status")) { }
-    _v1
-  end
-  _v2
-end
-```
-
-The children markup appears twice in compiled output (one per branch), but only one branch executes at runtime. This is the same strategy `:if`/`else` uses in any compiled template language.
-
-## Security Analysis
-
-`:unwrap` introduces no new input surface, no new interpolation sites, and no new runtime primitives. Here's why, examined from an attacker's perspective.
-
-### Threat: Code injection via the condition expression
-
-The `:unwrap={expression}` value is a Ruby expression embedded in the template, identical to `:if={expression}`. It follows the same code path: the tokenizer extracts the attribute value, the compiler emits it as the condition in an `if` statement, and Temple's `ControlFlow` filter generates the final Ruby code.
-
-**No new risk.** If an attacker can control the `:unwrap` condition, they can equally control any `:if` condition or `{{ }}` expression. The trust boundary is the template source itself, which is developer-authored and not user-supplied.
-
-### Threat: Bypassing security-critical wrappers
-
-A wrapper element might enforce a security invariant — e.g., a `<SanitizedContainer>` that escapes its children, or a CSRF token wrapper. If `:unwrap` is applied to such an element, the children would render without the security boundary.
-
-**Same risk as `:if`.** An `:if={false}` on the same element already removes it and all its children entirely. `:unwrap` is strictly less dangerous — the children still render, they just lose the wrapper. Both are template-author decisions, not runtime user input. If a developer writes `:unwrap` on a security-critical wrapper, that's a logic bug in the template, not a vulnerability in the directive.
-
-### Threat: Double-rendering or state mutation from duplicated children
-
-The compiled output contains the children in both branches of the `if`/`else`. Could an attacker trigger double execution?
-
-**No.** Standard `if`/`else` control flow guarantees mutual exclusion — exactly one branch executes per render. The duplication is in the compiled template source, not in runtime execution. This is the same pattern every compiled template language uses for conditionals.
-
-### Threat: XSS via unwrapped content
-
-When unwrapped, children are emitted directly into the parent context. Could this bypass output escaping?
-
-**No.** Escaping in Orb is applied per-expression at the `{{ }}` or component render boundary, not by wrapper elements. Removing a wrapper doesn't change how child expressions are escaped. A `<Badge label={user_input} />` is escaped identically whether it's inside a `<Tooltip>` or rendered bare.
-
-### Threat: Interaction with `:if` creating unexpected states
-
-When both `:if` and `:unwrap` are present, `:if` is processed first (it's higher in the directive priority chain). The resulting structure is:
-
-```ruby
-if if_condition
-  if unwrap_condition
-    children
-  else
-    element_with_children
-  end
-end
-```
-
-**No edge case.** The nesting is straightforward. When `:if` is false, nothing renders — `:unwrap` is never evaluated. No partial-render or inconsistent-state scenario exists.
-
-### Summary
-
-`:unwrap` reuses the exact same compilation and escaping pipeline as `:if`. It introduces no new interpolation site, no new runtime eval, no new trust boundary. The only novel behavior is _which subtree is selected_ for rendering — and both subtrees were already present in the template, authored by the developer.
-
-## Summary
-
-- **3 files changed**, ~25 lines of code added (including refactoring existing directive handling)
-- **0 tokenizer/parser changes** — existing directive infrastructure handles it
-- Refactors `compiler_directives?` to use a constant set and `transform_directives_for_tag_node` into per-directive handler methods — both existing directives benefit from the cleaner structure
-- Works on HTML elements and components equally
-- Composes cleanly with `:if` (evaluated first) and `:for`