From 5a5e34e5e671f54f31c22dc3c9d7432b10fde18e Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Tue, 25 Nov 2025 23:55:18 -0800
Subject: [PATCH 01/81] Transformer prototype.

---
 tdom/transformer.py      | 446 +++++++++++++++++++++++++++++++++++++++
 tdom/transformer_test.py |  18 ++
 2 files changed, 464 insertions(+)
 create mode 100644 tdom/transformer.py
 create mode 100644 tdom/transformer_test.py

diff --git a/tdom/transformer.py b/tdom/transformer.py
new file mode 100644
index 0000000..b7d8dfc
--- /dev/null
+++ b/tdom/transformer.py
@@ -0,0 +1,446 @@
+from dataclasses import dataclass, field
+from string.templatelib import Interpolation, Template
+from io import StringIO, BufferedWriter
+from typing import Callable
+from collections.abc import Iterable
+import typing as t
+from collections import deque
+
+from .parser import parse_html
+from .nodes import (
+    TNode,
+    TFragment,
+    TElement,
+    TText,
+    DocumentType,
+    TComment,
+    ComponentInfo,
+    VOID_ELEMENTS,
+    CDATA_CONTENT_ELEMENTS,
+    RCDATA_CONTENT_ELEMENTS,
+    )
+from .escaping import (
+    escape_html_content_in_tag as default_escape_html_content_in_tag,
+    escape_html_text as default_escape_html_text,
+    escape_html_script as default_escape_html_script,
+    escape_html_comment as default_escape_html_comment,
+    )
+from .processor import LastUpdatedOrderedDict
+
+
+@t.runtime_checkable
+class HasHTMLDunder(t.Protocol):
+    def __html__(self) -> str: ...  # pragma: no cover
+
+
+@dataclass
+class EndTag:
+    end_tag: str
+
+
+@dataclass
+class TransformService:
+    """
+    Turn a structure node tree into an optimized Template that can be quickly interpolated into a string.
+
+    - Tag attributes with any interpolations are replaced with a single interpolation.
+    - Component invocations are replaced with a single interpolation.
+    - Runs of strings are consolidated around or in between interpolations.
+      If there are no strings provided to build a proper template then empty strings are injected.
+    """
+
+    escape_html_text: Callable = default_escape_html_text
+
+    slash_void: bool = False # Apply a xhtml-style slash to void html elements.
+
+    def transform_template(self, values_template: Template) -> Template:
+        """ Transform the given template into a template for rendering. """
+        struct_node = self.to_struct_node(values_template)
+        return self.to_struct_template(struct_node)
+
+    def to_struct_node(self, values_template: Template) -> Node:
+        return parse_html(values_template)
+
+    def to_struct_template(self, struct_node: Node) -> Template:
+        """ Recombine stream of tokens from node trees into a new template. """
+        return Template(*self.streamer(struct_node))
+
+    def component_streamer(self, component_node: Component, last_container_tag: str|None=None) -> Generator[str|Interpolation, ...]:
+        """ Stream the component contents but not the component itself. """
+        yield from self.streamer(TFragment(component_node.children), last_container_tag=last_container_tag)
+
+    def _stream_comment_interpolation(self, template):
+        return Interpolation(('<!--', text_t), '', None, 'html_comment_template')
+
+    def _stream_attrs_interpolation(self, attrs):
+        return Interpolation(attrs, '', None, 'html_attrs_seq')
+
+    def _stream_component_interpolation(self, last_container_tag, attrs, comp_info):
+        return Interpolation((last_container_tag, attrs, comp_info.starttag_interpolation_index, comp_info.strings_slice_begin, comp_info.strings_slice_end), '', None, 'tdom_component')
+
+    def _stream_raw_text_interpolation(self, last_container_tag, text_t):
+        return Interpolation((last_container_tag, text_t), '', None, 'html_raw_text_template')
+
+    def _stream_escapable_raw_text_interpolation(self, last_container_tag, text_t):
+        return Interpolation((last_container_tag, text_t), '', None, 'html_escapable_raw_text_template')
+
+    def _stream_text_interpolation(self, last_container_tag: str|None, values_index: int):
+        return Interpolation((last_container_tag, values_index), '', None, 'html_normal_interpolation')
+
+    def streamer(self, root: TNode, last_container_tag: str|None=None) -> Generator[str|Interpolation, ...]:
+        """
+        Stream template parts back out so they can be consolidated into a new metadata-aware template.
+        """
+        q = [(last_container_tag, root)]
+        while q:
+            last_container_tag, tnode = q.pop()
+            match tnode:
+                case EndTag(end_tag):
+                    yield end_tag
+                case DocumentType(text):
+                    yield f'<!doctype {text}>'
+                case TComment(text_t):
+                    yield '<!--'
+                    yield self._stream_comment_interpolation(text_t)
+                    yield '-->'
+                case TFragment(children):
+                    q.extend([(last_container_tag, child) for child in reversed(children)])
+                case TElement(tag, attrs, children, component_info):
+                    match component_info:
+                        case None:
+                            yield f'<{tag}'
+                            if self.has_dynamic_attrs(attrs):
+                                yield self._stream_attrs_interpolation(attrs)
+                            else:
+                                yield self.static_attrs_to_str(attrs)
+                            # This is just a want to have.
+                            if self.slash_void and tag in VOID_ELEMENTS:
+                                yield ' />'
+                            else:
+                                yield '>'
+                            if tag not in VOID_ELEMENTS:
+                                q.append((last_container_tag, EndTag(f'</{tag}>')))
+                                q.extend([(tag, child) for child in reversed(children)])
+                        case ComponentInfo() as comp_info:
+                            yield self._stream_component_interpolation(last_container_tag, attrs, comp_info)
+                case TText(text_t):
+                    if last_container_tag in CDATA_CONTENT_ELEMENTS:
+                        # Must be handled all at once.
+                        yield self._stream_raw_text_interpolation(last_container_tag, text_t)
+                    elif last_container_tag in RCDATA_CONTENT_ELEMENTS:
+                        # We can handle all at once because there are no non-text children and everything must be string-ified.
+                        yield self._stream_escapable_raw_text_interpolation(last_container_tag, text_t)
+                    else:
+                        # Flatten the template back out into the stream because each interpolation can
+                        # be escaped as is and structured content can be injected between text anyways.
+                        for part in text_t:
+                            if isinstance(part, str):
+                                yield part
+                            else:
+                                yield self._stream_text_interpolation(last_container_tag, part.value)
+                case _:
+                    raise ValueError(f'Unrecognized tnode: {tnode}')
+
+    def static_attrs_to_str(self, attrs: tuple[tuple[str | int, ...], ...]) -> str:
+        return ''.join(f' {attr[0]}' if len(attr) == 1 else f' {attr[0]}="{self.escape_html_text(attr[1])}"' for attr in attrs)
+
+    def has_dynamic_attrs(self, attrs: tuple[tuple[str|int, ...], ...]) -> bool:
+        for attr in attrs:
+             match attr:
+                 case [str()] | [str(), str()]:
+                     continue
+                 case _:
+                     return True
+        return False
+
+    def extract_embedded_template(self, template: Template, start_index: int, end_index: int):
+        """
+        Extract the template parts exclusively from start tag to end tag.
+
+        @TODO: "There must be a better way."
+        """
+        assert end_index is not None and start_index <= end_index
+        # Copy the parts out of the containing template.
+        index = start_index
+        parts = []
+        while index < end_index:
+            parts.append(template.strings[index])
+            if index < end_index - 1:
+                parts.append(template.interpolations[index])
+            index += 1
+        # Now trim the first part to the end of the opening tag.
+        parts[0] = parts[0][parts[0].find('>')+1:]
+        # Now trim the last part (could also be the first) to the start of the closing tag.
+        parts[-1] = parts[-1][:parts[-1].rfind('<')]
+        return Template(*parts)
+
+
+@dataclass
+class RenderService:
+
+    transform_api: TransformService
+
+    escape_html_text: Callable = default_escape_html_text
+
+    escape_html_comment: Callable = default_escape_html_comment
+
+    escape_html_content_in_tag: Callable = default_escape_html_content_in_tag
+
+    def render_template(self, template, struct_cache=None, last_container_tag=None):
+        """
+        Iterate left to right and pause and push new iterators when descending depth-first.
+
+        Every interpolation becomes an iterator.
+
+        Every iterator could return more iterators.
+
+        The last container tag is used to determine how to handle
+        text processing.  When working with fragments we might not know the
+        container tag until the fragment is included at render-time.
+        """
+        if struct_cache is None:
+            struct_cache = {}
+        
+        bf = StringIO()
+
+        # Each item should contain (container_tag, contents_iterator).
+        dq: Deque[tuple[
+            str|None,
+            Iterator[
+                tuple[
+                    tuple[
+                        str|None,
+                        Template|None],
+                    object]]]] = deque()
+        dq.append((last_container_tag, iter(self.walk_template(template, self.process_template(template, struct_cache)))))
+        while dq:
+            last_container_tag, it = dq.pop()
+            for (chunk_type, template), chunk in it:
+                if chunk_type is None:
+                    bf.write(chunk) # string in t-string
+                    continue
+                match chunk_type:
+                    case 'html_normal_interpolation'|'user_html_content':
+                        if chunk_type == 'html_normal_interpolation':
+                            container_tag, ip_index = chunk
+                            value = template.interpolations[ip_index].value # data provided to a parsed t-string
+                            if not container_tag:
+                                container_tag = last_container_tag
+                        else:
+                            value = chunk # directly from interpolated iterable
+                            container_tag = last_container_tag
+                        match value:
+                            case Template():
+                                dq.append((last_container_tag, it))
+                                # How do we know to process a template this way?
+                                dq.append((container_tag, iter(self.walk_template(value, self.process_template(value, struct_cache)))))
+                                break
+                            case str():
+                                if container_tag not in ('style', 'script', 'title', 'textarea', '<!--'):
+                                    bf.write(self.escape_html_text(value))
+                                else:
+                                    bf.write(self.escape_html_content_in_tag(container_tag, value))
+                            case Iterable():
+                                dq.append((last_container_tag, it))
+                                dq.append((container_tag, ((('user_html_content', template), v) for v in iter(value))))
+                                break
+                            case False | None:
+                                # Do nothing here, we don't even need to yield ''.
+                                pass
+                            case HasHTMLDunder():
+                                res = value.__html__()
+                                match res:
+                                    case Iterable():
+                                        # @NOTE: This is not an tdom aware iterator.
+                                        # @NOTE: We need a way to tie back into the grid here.
+                                        for r in res:
+                                            bf.write(r)
+                                    case str():
+                                        bf.write(res)
+                            case _:
+                                # @TODO: This escape should probably be container tag aware.
+                                bf.write(self.escape_html_text(str(value)))
+                    case 'html_comment_template': # HTML <!-- : no recursion
+                        container_tag, comment_t = chunk
+                        assert container_tag == '<!--'
+                        bf.write(self.escape_html_comment(self.resolve_text_without_recursion(template, container_tag, comment_t)))
+                    case 'html_raw_text_template': # HTML script, style : no recursion
+                        container_tag, content_t = chunk
+                        bf.write(self.escape_html_content_in_tag(container_tag, self.resolve_text_without_recursion(template, container_tag, content_t)))
+                    case 'html_escapable_raw_text_template': # HTML title, textarea : no recursion
+                        container_tag, content_t = chunk
+                        bf.write(self.escape_html_text(self.resolve_text_without_recursion(template, container_tag, content_t)))
+                    case 'html_attrs_seq':
+                        attrs = self.resolve_attrs(self.interpolate_attrs(chunk, template))
+                        attrs_str = ''.join(f' {k}' if v is True else f' {k}="{self.escape_html_text(v)}"' for k, v in attrs.items() if v is not None and v is not False)
+                        bf.write(attrs_str)
+                    case 'tdom_component':
+                        """
+                        - Extract embedded template or use empty template.
+                        - Transform embedded template into struct template.
+                        - Resolve attrs but don't stringify.
+                        - Resolve callable.
+                        - Invoke callable with attrs, embedded template, embedded struct template. (no garbage barge? how can we pass the cache?)
+                        - If callable returns a result template then
+                             * transform it to a struct template
+                             * iteratively recurse into that result template and start outputting it
+                        """
+                        (container_tag, attrs, start_template_interpolation_index, start_template_string_index, end_template_string_index) = chunk
+                        if end_template_string_index is not None:
+                            embedded_template = self.transform_api.extract_embedded_template(template, start_template_string_index, end_template_string_index)
+                        else:
+                            embedded_template = Template('')
+                        embedded_struct_t = self.process_template(embedded_template, struct_cache)
+                        attrs = self.resolve_attrs(self.interpolate_attrs(attrs, template))
+                        component_callable = template.interpolations[start_template_interpolation_index].value
+                        result_template = component_callable(attrs, embedded_template, embedded_struct_t)
+                        if result_template:
+                            dq.append((last_container_tag, it))
+                            dq.append((container_tag, iter(self.walk_template(result_template, self.process_template(result_template, struct_cache)))))
+                            break
+                    case _:
+                        raise ValueError(f'Unknown chunk type {chunk_type}: {chunk}')
+
+        yield bf.getvalue()
+
+    def resolve_text_without_recursion(self, template, container_tag, content_t):
+        parts = list(content_t)
+        exact = len(parts) == 1 and len(content_t.interpolations) == 1
+        if exact:
+            value = template.interpolations[parts[0].value].value
+            match value:
+                case str():
+                    return value
+                case None|False:
+                    return ''
+                case Template()|Iterable():
+                    raise ValueError(f'Recursive includes are not supported within {container_tag}')
+                case HasHTMLDunder():
+                    return Markup(str(value.__html__()))
+        else:
+            text = []
+            for part in content_t:
+                if isinstance(part, str):
+                    text.append(part)
+                    continue
+                value = template.interpolations[part.value].value
+                match value:
+                    case str():
+                        text.append(value)
+                    case None|False:
+                        continue
+                    case Template()|Iterable():
+                        raise ValueError(f'Recursive includes are not supported within {container_tag}')
+                    case HasHTMLDunder():
+                        raise ValueError(f'Non-exact trusted interpolations are not supported within {container_tag}')
+                    case _:
+                        text.append(str(value))
+            return ''.join(text)
+
+    def process_template(self, template, struct_cache):
+        if template.strings not in struct_cache:
+            struct_cache[template.strings] = self.transform_api.transform_template(template)
+        return struct_cache[template.strings]
+
+    def interpolate_attrs(self, attrs, template) -> Generator[tuple[str, object|None]]:
+        """ Plug `template` values into any attribute interpolations. """
+        for attr in attrs:
+            match attr:
+                case [str()]:
+                    yield (attr[0], True)
+                case [str(), str()]:
+                    yield (attr[0], attr[1])
+                case [str(), int()]:
+                    yield (attr[0], template.interpolations[attr[1]].value)
+                case [str(), str()|int(), _, *_]:
+                    v_str = ''.join(part if isinstance(part, str) else str(template.interpolations[part.value].value) for part in attr[1:])
+                    yield (attr[0], v_str)
+                case [int()]:
+                    spread_attrs = template.interpolations[attr[0]].value
+                    yield from spread_attrs.items() if hasattr(spread_attrs, 'items') else spread_attrs
+                case _:
+                    raise ValueError(f'Unrecognized attr format {attr}')
+
+    def resolve_attrs(self, attrs) -> dict[str, object|None|AttrMarker]:
+        new_attrs = LastUpdatedOrderedDict()
+        klass = {}
+        for k, v in attrs:
+            match k:
+                case 'class':
+                    # Special cases to allow unsetting all classes.  Do we really need all over these?
+                    if v is True:
+                        new_attrs['class'] = v
+                        klass.clear()
+                    elif v is None:
+                        new_attrs['class'] = None
+                        klass.clear()
+                    elif v == '':
+                        new_attrs['class'] = ''
+                        klass.clear()
+                    else:
+                        q = [v]
+                        changes = {}
+                        while q:
+                            sub_v = q.pop()
+                            match sub_v:
+                                case str():
+                                    if ' ' not in sub_v:
+                                        changes[sub_v] = True
+                                    else:
+                                        for cn in sub_v.split():
+                                            changes[cn] = True
+                                case dict():
+                                    for cn, enabled in sub_v.items():
+                                        changes[cn] = enabled
+                                case Iterable():
+                                    q.extend(reversed(sub_v))
+                                case None|False:
+                                    pass
+                                case _:
+                                    raise ValueError(f'Unrecognized format for class attribute: {sub_v}')
+                        if changes:
+                            klass.update(changes)
+                            class_str = ' '.join(cn for cn, enabled in klass.items() if enabled)
+                            if class_str != new_attrs.get('class', None):
+                                new_attrs['class'] = class_str
+                case 'style':
+                    match v:
+                        case None:
+                            new_attrs['style'] = None
+                        case str():
+                            new_attrs['style'] = v
+                        case Iterable():
+                            new_attrs['style'] = '; '.join(f'{pn}: {pv}' for pn, pv in (v.items() if hasattr(v, 'items') else v))
+                        case _:
+                            raise ValueError(f'Unrecognized format for style attribute: {v}')
+                case 'aria':
+                    for an, av in (v.items() if hasattr(v, 'items') else v):
+                        full_name = f'aria-{an}'
+                        match av:
+                            case True:
+                                new_attrs[full_name] = 'true'
+                            case False:
+                                new_attrs[full_name] = 'false'
+                            case None:
+                                new_attrs[full_name] = None
+                            case str():
+                                new_attrs[full_name] = av
+                            case _:
+                                new_attrs[full_name] = str(av)
+                case 'data':
+                    for dn, dv in (v.items() if hasattr(v, 'items') else v):
+                        new_attrs[f'data-{dn}'] = dv
+                case _:
+                    new_attrs[k] = v
+        return new_attrs
+
+    def walk_template(self, template, struct_t):
+        for part in struct_t:
+            if isinstance(part, str):
+                yield ((None, None), part)
+            else:
+                yield ((part.format_spec, template), part.value)
+
+
+def render_service_factory():
+    return RenderService(transform_api=TransformService())
diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
new file mode 100644
index 0000000..3001386
--- /dev/null
+++ b/tdom/transformer_test.py
@@ -0,0 +1,18 @@
+from .transformer import render_service_factory
+
+
+def test_render_template():
+    def get_sample_t(idx, spread_attrs, button_text):
+        return t'''<div><button data-key={idx} {spread_attrs}>{button_text}</button></div>'''
+    render_api = render_service_factory()
+    struct_cache = {}
+    for count in (1, 1, 100):
+        for idx in range(count):
+            spread_attrs = {'data-enabled': True}
+            button_text = 'RENDER'
+            sample_t = get_sample_t(idx, spread_attrs, button_text)
+            assert ''.join(render_api.render_template(sample_t, struct_cache)) == f'<div><button data-key="{idx}" data-enabled>RENDER</button></div>'
+
+    new_sample_t = get_sample_t("zebra", {"diff": "yes"}, t"<div>{sample_t}</div>") # You dirty dog! Stay. In. Your. Scope.
+    assert ''.join(render_api.render_template(new_sample_t, struct_cache)) == \
+        f'<div><button data-key="zebra" diff="yes"><div><div><button data-key="99" data-enabled>RENDER</button></div></div></button></div>'

From d1c800a6c70be64b43e29994847490cdccc0acb4 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Tue, 25 Nov 2025 23:55:39 -0800
Subject: [PATCH 02/81] Generic escaping function.

---
 tdom/escaping.py | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/tdom/escaping.py b/tdom/escaping.py
index 2caebba..915e5b8 100644
--- a/tdom/escaping.py
+++ b/tdom/escaping.py
@@ -78,3 +78,21 @@ def escape_html_script(text: str) -> str:
     for match_re, replace_text in SCRIPT_RES:
         text = re.sub(match_re, replace_text, text)
     return text
+
+
+def escape_html_content_in_tag(parent_tag, content):
+    parent_tag = parent_tag.lower()
+    if parent_tag == 'script':
+        return escape_html_script(content)
+    elif parent_tag == '<!--':
+        return escape_html_comment(content)
+    elif parent_tag == 'style':
+        LT = "&lt;"
+        close_str = f"</{parent_tag}>"
+        # @TODO: This whole escaping business is probably be misguided... but we should cache this.
+        close_str_re = re.compile(close_str, re.I | re.A)
+        replace_str = LT + close_str[1:]
+        return re.sub(close_str_re, replace_str, content)
+    else:
+        # Fallback to nuclear solution.
+        return escape_html_text(content)

From 4bfd3e33c057c1ac7cc99858336bf832e6f44f19 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 30 Nov 2025 20:26:46 -0800
Subject: [PATCH 03/81] Remove conditional dispatch at render-time in favor of
 fixed callbacks in structure template interpolations.

---
 tdom/transformer.py | 349 ++++++++++++++++++++++++--------------------
 1 file changed, 193 insertions(+), 156 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index b7d8dfc..6f43a86 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -38,6 +38,116 @@ class EndTag:
     end_tag: str
 
 
+BREAK_ITR = 'break_itr'
+
+
+class Interpolator(t.Protocol):
+
+    def __call__(self, render_api, struct_cache, q, bf, last_container_tag, template, value) -> RenderQueueItem:
+        """
+        Populates an interpolation or returns iterator to decende into.
+
+        If recursion is required then pushes current iterator
+        render_api
+        struct_cache
+        q
+            A list-like queue of iterators paired with the container tag the results are in.
+        bf
+            A list-like output buffer.
+        last_container_tag
+            The last HTML tag known for this interpolation, this cannot always be 100% accurate.
+        template
+            The "values" template that is being used to fulfill interpolations.
+        value
+            The value of the "structure" template interpolation or a standalone value usually
+            from a user supplied iterator.
+
+        """
+        pass
+
+type InterpolationInfo = object | None
+type RenderQueueItem = tuple[str | None, Iteratable[tuple[Interpolator, Template, InterpolationInfo]]]
+
+
+def interpolate_comment(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+    container_tag, comment_t = ip_info
+    assert container_tag == '<!--'
+    bf.append(render_api.escape_html_comment(render_api.resolve_text_without_recursion(template, container_tag, comment_t)))
+
+
+def interpolate_attrs(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+    constainer_tag, attrs = ip_info
+    attrs = render_api.resolve_attrs(render_api.interpolate_attrs(attrs, template))
+    attrs_str = ''.join(f' {k}' if v is True else f' {k}="{render_api.escape_html_text(v)}"' for k, v in attrs.items() if v is not None and v is not False)
+    bf.append(attrs_str)
+
+
+def interpolate_component(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+    """
+    - Extract embedded template or use empty template.
+    - Transform embedded template into struct template.
+    - Resolve attrs but don't stringify.
+    - Resolve callable.
+    - Invoke callable with attrs, embedded template, embedded struct template. (no garbage barge? how can we pass the cache?)
+    - If callable returns a result template then
+         * transform it to a struct template
+         * iteratively recurse into that result template and start outputting it
+    """
+    (container_tag, attrs, start_template_interpolation_index, start_template_string_index, end_template_string_index) = ip_info
+    if end_template_string_index is not None:
+        embedded_template = render_api.transform_api.extract_embedded_template(template, start_template_string_index, end_template_string_index)
+    else:
+        embedded_template = Template('')
+    embedded_struct_t = render_api.process_template(embedded_template, struct_cache)
+    attrs = render_api.resolve_attrs(render_api.interpolate_attrs(attrs, template))
+    component_callable = template.interpolations[start_template_interpolation_index].value
+    result_template = component_callable(attrs, embedded_template, embedded_struct_t)
+    if result_template:
+        return (container_tag, iter(render_api.walk_template(bf, result_template, render_api.process_template(result_template, struct_cache))))
+
+
+def interpolate_raw_text(render_api, struct_cache, q, bf, last_container_tag, template, value) -> RenderQueueItem:
+    container_tag, content_t = value
+    bf.append(render_api.escape_html_content_in_tag(container_tag, render_api.resolve_text_without_recursion(template, container_tag, content_t)))
+
+
+def interpolate_escapable_raw_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+    container_tag, content_t = ip_info
+    bf.append(render_api.escape_html_text(render_api.resolve_text_without_recursion(template, container_tag, content_t)))
+
+
+def interpolate_struct_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+    container_tag, ip_index = ip_info
+    value = template.interpolations[ip_index].value # data provided to a parsed t-string
+    return interpolate_text(render_api, struct_cache, q, bf, last_container_tag, template, (container_tag, value))
+
+
+def interpolate_user_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+    return interpolate_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info)
+
+
+def interpolate_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+    container_tag, value = ip_info
+    if container_tag is None:
+        container_tag = last_constainer_tag
+
+    if isinstance(value, Template):
+        return (container_tag, iter(render_api.walk_template(bf, value, render_api.process_template(value, struct_cache))))
+    elif hasattr(value, '__iter__'):
+        return (container_tag, (((interpolate_user_text, template, (None, v)) for v in iter(value))))
+    elif value is False or value is None:
+        # Do nothing here, we don't even need to yield ''.
+        return
+    else:
+        if container_tag not in ('style', 'script', 'title', 'textarea', '<!--'):
+            if hasattr(value, '__html__'):
+                bf.append(value.__html__())
+            else:
+                bf.append(render_api.escape_html_text(value))
+        else:
+            bf.append(render_api.escape_html_content_in_tag(container_tag, str(value)))
+
+
 @dataclass
 class TransformService:
     """
@@ -65,27 +175,29 @@ def to_struct_template(self, struct_node: Node) -> Template:
         """ Recombine stream of tokens from node trees into a new template. """
         return Template(*self.streamer(struct_node))
 
-    def component_streamer(self, component_node: Component, last_container_tag: str|None=None) -> Generator[str|Interpolation, ...]:
-        """ Stream the component contents but not the component itself. """
-        yield from self.streamer(TFragment(component_node.children), last_container_tag=last_container_tag)
+    def _stream_comment_interpolation(self, text_t):
+        info = ('<!--', text_t, comment_interpolator)
+        return Interpolation((interpolate_comment, info), '', None, 'html_comment_template')
 
-    def _stream_comment_interpolation(self, template):
-        return Interpolation(('<!--', text_t), '', None, 'html_comment_template')
-
-    def _stream_attrs_interpolation(self, attrs):
-        return Interpolation(attrs, '', None, 'html_attrs_seq')
+    def _stream_attrs_interpolation(self, last_container_tag, attrs):
+        info = (last_container_tag, attrs)
+        return Interpolation((interpolate_attrs, info), '', None, 'html_attrs_seq')
 
     def _stream_component_interpolation(self, last_container_tag, attrs, comp_info):
-        return Interpolation((last_container_tag, attrs, comp_info.starttag_interpolation_index, comp_info.strings_slice_begin, comp_info.strings_slice_end), '', None, 'tdom_component')
+        info = (last_container_tag, attrs, comp_info.starttag_interpolation_index, comp_info.strings_slice_begin, comp_info.strings_slice_end)
+        return Interpolation((interpolate_component, info), '', None, 'tdom_component')
 
     def _stream_raw_text_interpolation(self, last_container_tag, text_t):
-        return Interpolation((last_container_tag, text_t), '', None, 'html_raw_text_template')
+        info = (last_container_tag, text_t)
+        return Interpolation((interpolate_raw_text, info), '', None, 'html_raw_text_template')
 
     def _stream_escapable_raw_text_interpolation(self, last_container_tag, text_t):
-        return Interpolation((last_container_tag, text_t), '', None, 'html_escapable_raw_text_template')
+        info = (last_container_tag, text_t)
+        return Interpolation((interpolate_escapable_raw_text, info), '', None, 'html_escapable_raw_text_template')
 
     def _stream_text_interpolation(self, last_container_tag: str|None, values_index: int):
-        return Interpolation((last_container_tag, values_index), '', None, 'html_normal_interpolation')
+        info = (last_container_tag, values_index)
+        return Interpolation((interpolate_struct_text, info), '', None, 'html_normal_interpolation')
 
     def streamer(self, root: TNode, last_container_tag: str|None=None) -> Generator[str|Interpolation, ...]:
         """
@@ -106,23 +218,22 @@ def streamer(self, root: TNode, last_container_tag: str|None=None) -> Generator[
                 case TFragment(children):
                     q.extend([(last_container_tag, child) for child in reversed(children)])
                 case TElement(tag, attrs, children, component_info):
-                    match component_info:
-                        case None:
-                            yield f'<{tag}'
-                            if self.has_dynamic_attrs(attrs):
-                                yield self._stream_attrs_interpolation(attrs)
-                            else:
-                                yield self.static_attrs_to_str(attrs)
-                            # This is just a want to have.
-                            if self.slash_void and tag in VOID_ELEMENTS:
-                                yield ' />'
-                            else:
-                                yield '>'
-                            if tag not in VOID_ELEMENTS:
-                                q.append((last_container_tag, EndTag(f'</{tag}>')))
-                                q.extend([(tag, child) for child in reversed(children)])
-                        case ComponentInfo() as comp_info:
-                            yield self._stream_component_interpolation(last_container_tag, attrs, comp_info)
+                    if component_info is None:
+                        yield f'<{tag}'
+                        if self.has_dynamic_attrs(attrs):
+                            yield self._stream_attrs_interpolation(tag, attrs)
+                        else:
+                            yield self.static_attrs_to_str(attrs)
+                        # This is just a want to have.
+                        if self.slash_void and tag in VOID_ELEMENTS:
+                            yield ' />'
+                        else:
+                            yield '>'
+                        if tag not in VOID_ELEMENTS:
+                            q.append((last_container_tag, EndTag(f'</{tag}>')))
+                            q.extend([(tag, child) for child in reversed(children)])
+                    else:
+                        yield self._stream_component_interpolation(last_container_tag, attrs, component_info)
                 case TText(text_t):
                     if last_container_tag in CDATA_CONTENT_ELEMENTS:
                         # Must be handled all at once.
@@ -200,141 +311,59 @@ def render_template(self, template, struct_cache=None, last_container_tag=None):
         """
         if struct_cache is None:
             struct_cache = {}
-        
-        bf = StringIO()
-
-        # Each item should contain (container_tag, contents_iterator).
-        dq: Deque[tuple[
-            str|None,
-            Iterator[
-                tuple[
-                    tuple[
-                        str|None,
-                        Template|None],
-                    object]]]] = deque()
-        dq.append((last_container_tag, iter(self.walk_template(template, self.process_template(template, struct_cache)))))
-        while dq:
-            last_container_tag, it = dq.pop()
-            for (chunk_type, template), chunk in it:
-                if chunk_type is None:
-                    bf.write(chunk) # string in t-string
-                    continue
-                match chunk_type:
-                    case 'html_normal_interpolation'|'user_html_content':
-                        if chunk_type == 'html_normal_interpolation':
-                            container_tag, ip_index = chunk
-                            value = template.interpolations[ip_index].value # data provided to a parsed t-string
-                            if not container_tag:
-                                container_tag = last_container_tag
-                        else:
-                            value = chunk # directly from interpolated iterable
-                            container_tag = last_container_tag
-                        match value:
-                            case Template():
-                                dq.append((last_container_tag, it))
-                                # How do we know to process a template this way?
-                                dq.append((container_tag, iter(self.walk_template(value, self.process_template(value, struct_cache)))))
-                                break
-                            case str():
-                                if container_tag not in ('style', 'script', 'title', 'textarea', '<!--'):
-                                    bf.write(self.escape_html_text(value))
-                                else:
-                                    bf.write(self.escape_html_content_in_tag(container_tag, value))
-                            case Iterable():
-                                dq.append((last_container_tag, it))
-                                dq.append((container_tag, ((('user_html_content', template), v) for v in iter(value))))
-                                break
-                            case False | None:
-                                # Do nothing here, we don't even need to yield ''.
-                                pass
-                            case HasHTMLDunder():
-                                res = value.__html__()
-                                match res:
-                                    case Iterable():
-                                        # @NOTE: This is not an tdom aware iterator.
-                                        # @NOTE: We need a way to tie back into the grid here.
-                                        for r in res:
-                                            bf.write(r)
-                                    case str():
-                                        bf.write(res)
-                            case _:
-                                # @TODO: This escape should probably be container tag aware.
-                                bf.write(self.escape_html_text(str(value)))
-                    case 'html_comment_template': # HTML <!-- : no recursion
-                        container_tag, comment_t = chunk
-                        assert container_tag == '<!--'
-                        bf.write(self.escape_html_comment(self.resolve_text_without_recursion(template, container_tag, comment_t)))
-                    case 'html_raw_text_template': # HTML script, style : no recursion
-                        container_tag, content_t = chunk
-                        bf.write(self.escape_html_content_in_tag(container_tag, self.resolve_text_without_recursion(template, container_tag, content_t)))
-                    case 'html_escapable_raw_text_template': # HTML title, textarea : no recursion
-                        container_tag, content_t = chunk
-                        bf.write(self.escape_html_text(self.resolve_text_without_recursion(template, container_tag, content_t)))
-                    case 'html_attrs_seq':
-                        attrs = self.resolve_attrs(self.interpolate_attrs(chunk, template))
-                        attrs_str = ''.join(f' {k}' if v is True else f' {k}="{self.escape_html_text(v)}"' for k, v in attrs.items() if v is not None and v is not False)
-                        bf.write(attrs_str)
-                    case 'tdom_component':
-                        """
-                        - Extract embedded template or use empty template.
-                        - Transform embedded template into struct template.
-                        - Resolve attrs but don't stringify.
-                        - Resolve callable.
-                        - Invoke callable with attrs, embedded template, embedded struct template. (no garbage barge? how can we pass the cache?)
-                        - If callable returns a result template then
-                             * transform it to a struct template
-                             * iteratively recurse into that result template and start outputting it
-                        """
-                        (container_tag, attrs, start_template_interpolation_index, start_template_string_index, end_template_string_index) = chunk
-                        if end_template_string_index is not None:
-                            embedded_template = self.transform_api.extract_embedded_template(template, start_template_string_index, end_template_string_index)
-                        else:
-                            embedded_template = Template('')
-                        embedded_struct_t = self.process_template(embedded_template, struct_cache)
-                        attrs = self.resolve_attrs(self.interpolate_attrs(attrs, template))
-                        component_callable = template.interpolations[start_template_interpolation_index].value
-                        result_template = component_callable(attrs, embedded_template, embedded_struct_t)
-                        if result_template:
-                            dq.append((last_container_tag, it))
-                            dq.append((container_tag, iter(self.walk_template(result_template, self.process_template(result_template, struct_cache)))))
-                            break
-                    case _:
-                        raise ValueError(f'Unknown chunk type {chunk_type}: {chunk}')
-
-        yield bf.getvalue()
+
+        bf: list[str] = []
+        q: list[RenderQueueItem] = []
+        q.append((last_container_tag, self.walk_template(bf, template, self.process_template(template, struct_cache))))
+        while q:
+            last_container_tag, it = q.pop()
+            for (interpolator, template, ip_info) in it:
+                render_queue_item = interpolator(self, struct_cache, q, bf, last_container_tag, template, ip_info)
+                if render_queue_item is not None:
+                    #
+                    # Pause the current iterator and push a new iterator on top of it.
+                    #
+                    q.append((last_container_tag, it))
+                    q.append(render_queue_item)
+                    break
+        return ''.join(bf)
 
     def resolve_text_without_recursion(self, template, container_tag, content_t):
         parts = list(content_t)
         exact = len(parts) == 1 and len(content_t.interpolations) == 1
         if exact:
             value = template.interpolations[parts[0].value].value
-            match value:
-                case str():
-                    return value
-                case None|False:
-                    return ''
-                case Template()|Iterable():
-                    raise ValueError(f'Recursive includes are not supported within {container_tag}')
-                case HasHTMLDunder():
-                    return Markup(str(value.__html__()))
+            if value is None or value is False:
+                return ''
+            elif isinstance(value, str):
+                return value
+            elif hasattr(value, '__html__'):
+                return Markup(value.__html__())
+            elif isinstance(value, (Template, Iterable)):
+                raise ValueError(f'Recursive includes are not supported within {container_tag}')
+            else:
+                return str(value)
         else:
             text = []
             for part in content_t:
                 if isinstance(part, str):
-                    text.append(part)
+                    if part:
+                        text.append(part)
                     continue
                 value = template.interpolations[part.value].value
-                match value:
-                    case str():
+                if value is None or value is False:
+                    continue
+                elif isinstance(value , str):
+                    if value:
                         text.append(value)
-                    case None|False:
-                        continue
-                    case Template()|Iterable():
+                    elif isinstance(value, (Template, Iterable)):
                         raise ValueError(f'Recursive includes are not supported within {container_tag}')
-                    case HasHTMLDunder():
+                    elif hasattr(value, '__html__'):
                         raise ValueError(f'Non-exact trusted interpolations are not supported within {container_tag}')
-                    case _:
-                        text.append(str(value))
+                    else:
+                        value_str = str(value)
+                        if value_str:
+                            text.append(value_str)
             return ''.join(text)
 
     def process_template(self, template, struct_cache):
@@ -361,7 +390,7 @@ def interpolate_attrs(self, attrs, template) -> Generator[tuple[str, object|None
                 case _:
                     raise ValueError(f'Unrecognized attr format {attr}')
 
-    def resolve_attrs(self, attrs) -> dict[str, object|None|AttrMarker]:
+    def resolve_attrs(self, attrs) -> dict[str, object|None]:
         new_attrs = LastUpdatedOrderedDict()
         klass = {}
         for k, v in attrs:
@@ -434,12 +463,20 @@ def resolve_attrs(self, attrs) -> dict[str, object|None|AttrMarker]:
                     new_attrs[k] = v
         return new_attrs
 
-    def walk_template(self, template, struct_t):
-        for part in struct_t:
-            if isinstance(part, str):
-                yield ((None, None), part)
-            else:
-                yield ((part.format_spec, template), part.value)
+    def walk_template(self, bf, template, struct_t):
+        strings = struct_t.strings
+        ips = struct_t.interpolations
+        last_str = len(strings) - 1
+        idx = 0
+        while idx != last_str:
+            if strings[idx]:
+                bf.append(strings[idx])
+            # @TODO: Should the template just be jammed in here too?
+            populate, value = ips[idx].value
+            yield (populate, template, value)
+            idx += 1
+        if strings[idx]:
+            bf.append(strings[idx])
 
 
 def render_service_factory():

From ff76c79a532bf1a5efcd1ed2ad4ac16b9e6206e8 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 30 Nov 2025 20:32:13 -0800
Subject: [PATCH 04/81] Fix typos.

---
 tdom/transformer.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 6f43a86..7bafa1a 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -76,7 +76,7 @@ def interpolate_comment(render_api, struct_cache, q, bf, last_container_tag, tem
 
 
 def interpolate_attrs(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
-    constainer_tag, attrs = ip_info
+    container_tag, attrs = ip_info
     attrs = render_api.resolve_attrs(render_api.interpolate_attrs(attrs, template))
     attrs_str = ''.join(f' {k}' if v is True else f' {k}="{render_api.escape_html_text(v)}"' for k, v in attrs.items() if v is not None and v is not False)
     bf.append(attrs_str)
@@ -129,7 +129,7 @@ def interpolate_user_text(render_api, struct_cache, q, bf, last_container_tag, t
 def interpolate_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
     container_tag, value = ip_info
     if container_tag is None:
-        container_tag = last_constainer_tag
+        container_tag = last_container_tag
 
     if isinstance(value, Template):
         return (container_tag, iter(render_api.walk_template(bf, value, render_api.process_template(value, struct_cache))))

From 4ac31c592f37ddced79af09f9b582dd7da8d5ab2 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 30 Nov 2025 23:31:26 -0800
Subject: [PATCH 05/81] Add optimization around str.

---
 tdom/transformer.py | 38 +++++++++++++++++++++++---------------
 1 file changed, 23 insertions(+), 15 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 7bafa1a..8844eae 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -2,7 +2,7 @@
 from string.templatelib import Interpolation, Template
 from io import StringIO, BufferedWriter
 from typing import Callable
-from collections.abc import Iterable
+from collections.abc import Iterable, Sequence
 import typing as t
 from collections import deque
 
@@ -131,21 +131,27 @@ def interpolate_text(render_api, struct_cache, q, bf, last_container_tag, templa
     if container_tag is None:
         container_tag = last_container_tag
 
-    if isinstance(value, Template):
-        return (container_tag, iter(render_api.walk_template(bf, value, render_api.process_template(value, struct_cache))))
-    elif hasattr(value, '__iter__'):
-        return (container_tag, (((interpolate_user_text, template, (None, v)) for v in iter(value))))
-    elif value is False or value is None:
-        # Do nothing here, we don't even need to yield ''.
-        return
-    else:
-        if container_tag not in ('style', 'script', 'title', 'textarea', '<!--'):
-            if hasattr(value, '__html__'):
-                bf.append(value.__html__())
-            else:
-                bf.append(render_api.escape_html_text(value))
+    #
+    # Try to optimize past this block if the value is a str.
+    #
+    if not isinstance(value, str):
+        if isinstance(value, Template):
+            return (container_tag, iter(render_api.walk_template(bf, value, render_api.process_template(value, struct_cache))))
+        elif isinstance(value, Sequence):
+            return (container_tag, (((interpolate_user_text, template, (None, v)) for v in iter(value))))
+        elif value is False or value is None:
+            # Do nothing here, we don't even need to yield ''.
+            return
+
+    if container_tag not in ('style', 'script', 'title', 'textarea', '<!--'):
+        if hasattr(value, '__html__'):
+            bf.append(value.__html__())
         else:
-            bf.append(render_api.escape_html_content_in_tag(container_tag, str(value)))
+            bf.append(render_api.escape_html_text(value))
+    else:
+        # @TODO: How could this happen?
+        raise ValueError(f'We cannot escape text within {container_tag} when multiple interpolations could occur.')
+        #bf.append(render_api.escape_html_content_in_tag(container_tag, str(value)))
 
 
 @dataclass
@@ -373,6 +379,7 @@ def process_template(self, template, struct_cache):
 
     def interpolate_attrs(self, attrs, template) -> Generator[tuple[str, object|None]]:
         """ Plug `template` values into any attribute interpolations. """
+        # @TODO: This should probably be using the processor to resolve these.
         for attr in attrs:
             match attr:
                 case [str()]:
@@ -391,6 +398,7 @@ def interpolate_attrs(self, attrs, template) -> Generator[tuple[str, object|None
                     raise ValueError(f'Unrecognized attr format {attr}')
 
     def resolve_attrs(self, attrs) -> dict[str, object|None]:
+        # @TODO: This should be using the processor to resolve these.
         new_attrs = LastUpdatedOrderedDict()
         klass = {}
         for k, v in attrs:

From 2cd9537b6e53e70ef9a94981cda870843ef77939 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Mon, 1 Dec 2025 14:52:53 -0800
Subject: [PATCH 06/81] Add select example.

---
 tdom/transformer_test.py | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 3001386..31afdfc 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -16,3 +16,20 @@ def get_sample_t(idx, spread_attrs, button_text):
     new_sample_t = get_sample_t("zebra", {"diff": "yes"}, t"<div>{sample_t}</div>") # You dirty dog! Stay. In. Your. Scope.
     assert ''.join(render_api.render_template(new_sample_t, struct_cache)) == \
         f'<div><button data-key="zebra" diff="yes"><div><div><button data-key="99" data-enabled>RENDER</button></div></div></button></div>'
+
+def test_render_select():
+    render_api = render_service_factory()
+
+    def get_select_t(options, selected_values):
+        return t'''<select>{[
+            t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>" for opt in options]
+        }</select>'''
+
+    def get_color_select_t(selected_values: set) -> Template:
+        PRIMARY_COLORS = [("R", "Red"), ("Y", "Yellow"), ("B", "Blue")]
+        assert set(selected_values).issubset(set([opt[0] for opt in PRIMARY_COLORS]))
+        return get_select_t(PRIMARY_COLORS, selected_values)
+
+    struct_cache = {}
+    assert render_api.render_template(get_color_select_t(set()), struct_cache) == '<select><option value="R">Red</option><option value="Y">Yellow</option><option value="B">Blue</option></select>'
+    assert render_api.render_template(get_color_select_t({'Y'}), struct_cache) == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'

From 18b4290aebff9c26918e46dd4b2f813365ebee55 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Mon, 1 Dec 2025 14:53:11 -0800
Subject: [PATCH 07/81] cleanup/docs

---
 tdom/transformer.py | 52 ++++++++++++++++++++++++++++-----------------
 1 file changed, 33 insertions(+), 19 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 8844eae..20e6446 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -38,18 +38,21 @@ class EndTag:
     end_tag: str
 
 
-BREAK_ITR = 'break_itr'
-
-
 class Interpolator(t.Protocol):
 
-    def __call__(self, render_api, struct_cache, q, bf, last_container_tag, template, value) -> RenderQueueItem:
+    def __call__(self, render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
         """
         Populates an interpolation or returns iterator to decende into.
 
         If recursion is required then pushes current iterator
         render_api
+            The current render api, provides various helper methods to the interpolator.
         struct_cache
+            The struct cache, this is mainly needed because it is not bound to the render api
+            and this might change.  If we want to run a new template through the render api we need
+            the cache to pass in which is kind of kludgy.  Maybe the render_api should be more of a
+            render_session or something that binds the cache and the render service together.  OR
+            we can just pass around 50 params...
         q
             A list-like queue of iterators paired with the container tag the results are in.
         bf
@@ -58,31 +61,35 @@ def __call__(self, render_api, struct_cache, q, bf, last_container_tag, template
             The last HTML tag known for this interpolation, this cannot always be 100% accurate.
         template
             The "values" template that is being used to fulfill interpolations.
-        value
-            The value of the "structure" template interpolation or a standalone value usually
-            from a user supplied iterator.
+        ip_info
+            The information provided in the structured template interpolation OR from another source,
+            for example a value from a user provided iterator.
 
+        Returns a render queue item when the main iteration loops needs to be paused and restarted to descend.
         """
         pass
 
+
 type InterpolationInfo = object | None
+
+
 type RenderQueueItem = tuple[str | None, Iteratable[tuple[Interpolator, Template, InterpolationInfo]]]
 
 
-def interpolate_comment(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+def interpolate_comment(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, comment_t = ip_info
     assert container_tag == '<!--'
     bf.append(render_api.escape_html_comment(render_api.resolve_text_without_recursion(template, container_tag, comment_t)))
 
 
-def interpolate_attrs(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+def interpolate_attrs(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, attrs = ip_info
     attrs = render_api.resolve_attrs(render_api.interpolate_attrs(attrs, template))
     attrs_str = ''.join(f' {k}' if v is True else f' {k}="{render_api.escape_html_text(v)}"' for k, v in attrs.items() if v is not None and v is not False)
     bf.append(attrs_str)
 
 
-def interpolate_component(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+def interpolate_component(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     """
     - Extract embedded template or use empty template.
     - Transform embedded template into struct template.
@@ -106,27 +113,34 @@ def interpolate_component(render_api, struct_cache, q, bf, last_container_tag, t
         return (container_tag, iter(render_api.walk_template(bf, result_template, render_api.process_template(result_template, struct_cache))))
 
 
-def interpolate_raw_text(render_api, struct_cache, q, bf, last_container_tag, template, value) -> RenderQueueItem:
+def interpolate_raw_text(render_api, struct_cache, q, bf, last_container_tag, template, value) -> RenderQueueItem | None:
     container_tag, content_t = value
     bf.append(render_api.escape_html_content_in_tag(container_tag, render_api.resolve_text_without_recursion(template, container_tag, content_t)))
 
 
-def interpolate_escapable_raw_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+def interpolate_escapable_raw_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, content_t = ip_info
     bf.append(render_api.escape_html_text(render_api.resolve_text_without_recursion(template, container_tag, content_t)))
 
 
-def interpolate_struct_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+def interpolate_struct_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, ip_index = ip_info
+    # @TODO: We just completely ignore any conversion or format_spec here.
+    # This is actually a much larger problem/decision of how can a user give us more information about what to do
+    # with their input AND should that be a one-off OR cached with the structured template forever.
+    # For example
+    #   - The 3rd interpolation will always be a html-aware Template string
+    #   - The 4th interpolation will be an iterator of html-aware Template strings
+    #   - The 5th interpolation will be an iterator of strings to render and escape.
     value = template.interpolations[ip_index].value # data provided to a parsed t-string
     return interpolate_text(render_api, struct_cache, q, bf, last_container_tag, template, (container_tag, value))
 
 
-def interpolate_user_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+def interpolate_user_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     return interpolate_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info)
 
 
-def interpolate_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem:
+def interpolate_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, value = ip_info
     if container_tag is None:
         container_tag = last_container_tag
@@ -209,7 +223,7 @@ def streamer(self, root: TNode, last_container_tag: str|None=None) -> Generator[
         """
         Stream template parts back out so they can be consolidated into a new metadata-aware template.
         """
-        q = [(last_container_tag, root)]
+        q: list[tuple(str | None, TNode | EndTag)] = [(last_container_tag, root)]
         while q:
             last_container_tag, tnode = q.pop()
             match tnode:
@@ -303,7 +317,7 @@ class RenderService:
 
     escape_html_content_in_tag: Callable = default_escape_html_content_in_tag
 
-    def render_template(self, template, struct_cache=None, last_container_tag=None):
+    def render_template(self, template, struct_cache=None, last_container_tag=None) -> str:
         """
         Iterate left to right and pause and push new iterators when descending depth-first.
 
@@ -334,7 +348,7 @@ def render_template(self, template, struct_cache=None, last_container_tag=None):
                     break
         return ''.join(bf)
 
-    def resolve_text_without_recursion(self, template, container_tag, content_t):
+    def resolve_text_without_recursion(self, template, container_tag, content_t) -> str:
         parts = list(content_t)
         exact = len(parts) == 1 and len(content_t.interpolations) == 1
         if exact:
@@ -379,7 +393,6 @@ def process_template(self, template, struct_cache):
 
     def interpolate_attrs(self, attrs, template) -> Generator[tuple[str, object|None]]:
         """ Plug `template` values into any attribute interpolations. """
-        # @TODO: This should probably be using the processor to resolve these.
         for attr in attrs:
             match attr:
                 case [str()]:
@@ -489,3 +502,4 @@ def walk_template(self, bf, template, struct_t):
 
 def render_service_factory():
     return RenderService(transform_api=TransformService())
+

From cab0f10ef93972fa38a480f0344c4ac237ff2208 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 25 Dec 2025 19:42:32 -0800
Subject: [PATCH 08/81] Add back iterable interpolation.

---
 tdom/transformer.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 20e6446..1b48ff9 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -151,7 +151,7 @@ def interpolate_text(render_api, struct_cache, q, bf, last_container_tag, templa
     if not isinstance(value, str):
         if isinstance(value, Template):
             return (container_tag, iter(render_api.walk_template(bf, value, render_api.process_template(value, struct_cache))))
-        elif isinstance(value, Sequence):
+        elif isinstance(value, Sequence) or hasattr(value, '__iter__'):
             return (container_tag, (((interpolate_user_text, template, (None, v)) for v in iter(value))))
         elif value is False or value is None:
             # Do nothing here, we don't even need to yield ''.

From 370631275fb504fbe95942d014cc0aad8e9bc585 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 25 Dec 2025 19:43:51 -0800
Subject: [PATCH 09/81] Make these write only so lru_cache on methods of
 subclasses work.

---
 tdom/transformer.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 1b48ff9..59a73b6 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -168,7 +168,7 @@ def interpolate_text(render_api, struct_cache, q, bf, last_container_tag, templa
         #bf.append(render_api.escape_html_content_in_tag(container_tag, str(value)))
 
 
-@dataclass
+@dataclass(frozen=True)
 class TransformService:
     """
     Turn a structure node tree into an optimized Template that can be quickly interpolated into a string.
@@ -306,7 +306,7 @@ def extract_embedded_template(self, template: Template, start_index: int, end_in
         return Template(*parts)
 
 
-@dataclass
+@dataclass(frozen=True)
 class RenderService:
 
     transform_api: TransformService

From 7c3170f2b2301dda27a94e460e775be72ceaccd8 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 25 Dec 2025 19:45:14 -0800
Subject: [PATCH 10/81] Add context var handling but we should probably just
 use a dedicated marker for this during parsing instead of having this weird
 component return API.

---
 tdom/transformer.py | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 59a73b6..32b84be 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -108,9 +108,14 @@ def interpolate_component(render_api, struct_cache, q, bf, last_container_tag, t
     embedded_struct_t = render_api.process_template(embedded_template, struct_cache)
     attrs = render_api.resolve_attrs(render_api.interpolate_attrs(attrs, template))
     component_callable = template.interpolations[start_template_interpolation_index].value
-    result_template = component_callable(attrs, embedded_template, embedded_struct_t)
+    result_template, context_values = component_callable(attrs, embedded_template, embedded_struct_t)
     if result_template:
-        return (container_tag, iter(render_api.walk_template(bf, result_template, render_api.process_template(result_template, struct_cache))))
+        result_struct = render_api.process_template(result_template, struct_cache)
+        if context_values:
+            walker = render_api.walk_template_with_context(bf, result_template, result_struct, context_values=context_values)
+        else:
+            walker = render_api.walk_template(bf, result_template, result_struct)
+        return (container_tag, iter(walker))
 
 
 def interpolate_raw_text(render_api, struct_cache, q, bf, last_container_tag, template, value) -> RenderQueueItem | None:
@@ -484,6 +489,14 @@ def resolve_attrs(self, attrs) -> dict[str, object|None]:
                     new_attrs[k] = v
         return new_attrs
 
+    def walk_template_with_context(self, bf, template, struct_t, context_values=None):
+        if context_values:
+            cm = ContextVarSetter(context_values=context_values)
+        else:
+            cm = nullcontext()
+        with cm:
+            yield from self.walk_template(bf, template, struct_t)
+
     def walk_template(self, bf, template, struct_t):
         strings = struct_t.strings
         ips = struct_t.interpolations
@@ -499,6 +512,24 @@ def walk_template(self, bf, template, struct_t):
         if strings[idx]:
             bf.append(strings[idx])
 
+from contextlib import nullcontext
+from contextvars import ContextVar, Token
+class ContextVarSetter:
+    context_values: tuple[tuple[ContextVar, object]]
+    tokens: tuple[Token] | None = None
+
+    def __init__(self, context_values=None):
+        self.context_values = context_values
+
+    def __enter__(self):
+        self.tokens = tuple([var.set(val) for var, val in self.context_values])
+        print (f'{[var.get() for var, _ in self.context_values]}')
+        print (f'{self.tokens=}')
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        for idx, var_value in enumerate(self.context_values):
+            var_value[0].reset(self.tokens[idx])
+
 
 def render_service_factory():
     return RenderService(transform_api=TransformService())

From f9b1228a33c8e710c2c9166672d44f8e425a125b Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 25 Dec 2025 19:45:35 -0800
Subject: [PATCH 11/81] Add context vars proof of concept test but needs more
 concurrency.

---
 tdom/transformer_test.py | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 31afdfc..5098470 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -33,3 +33,26 @@ def get_color_select_t(selected_values: set) -> Template:
     struct_cache = {}
     assert render_api.render_template(get_color_select_t(set()), struct_cache) == '<select><option value="R">Red</option><option value="Y">Yellow</option><option value="B">Blue</option></select>'
     assert render_api.render_template(get_color_select_t({'Y'}), struct_cache) == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'
+
+from contextvars import ContextVar
+
+
+theme_context_var = ContextVar('theme', default='default')
+
+
+def test_component():
+
+    def ThemeContext(attrs, embedded_t, embedded_struct):
+        context_values = ((theme_context_var, attrs.get('value', 'normal')),)
+        return embedded_t, context_values
+
+    def ThemedDiv(attrs, embedded_t, embedded_struct):
+        theme = theme_context_var.get()
+        return t'<div data-theme="{theme}">{embedded_t}</div>', ()
+
+    render_api = render_service_factory()
+    body_t = t"<div><{ThemeContext} value='holiday'><{ThemedDiv}><b>Cheers!</b></{ThemedDiv}></{ThemeContext}></div>"
+    with theme_context_var.set('not-the-default'):
+        assert render_api.render_template(body_t) == '<div><div data-theme="holiday"><b>Cheers!</b></div></div>'
+        assert theme_context_var.get() == 'not-the-default'
+    assert theme_context_var.get() == 'default'

From 02f82d8937799a5a13a3e8adb1315a06d8a26e82 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Wed, 31 Dec 2025 01:11:15 -0800
Subject: [PATCH 12/81] Finish rebase.

---
 tdom/template_utils.py |  11 ++
 tdom/transformer.py    | 246 ++++++++++++++---------------------------
 2 files changed, 97 insertions(+), 160 deletions(-)

diff --git a/tdom/template_utils.py b/tdom/template_utils.py
index 39dc8b3..cbdcde6 100644
--- a/tdom/template_utils.py
+++ b/tdom/template_utils.py
@@ -74,3 +74,14 @@ def __post_init__(self):
             raise ValueError(
                 "TemplateRef must have one more string than interpolation indexes."
             )
+
+    def __iter__(self):
+        index = 0
+        last_s_index = len(self.strings) - 1
+        while index <= last_s_index:
+            s = self.strings[index]
+            if s:
+                yield s
+            if index < last_s_index:
+                yield self.i_indexes[index]
+            index += 1
diff --git a/tdom/transformer.py b/tdom/transformer.py
index 32b84be..7316b43 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -1,20 +1,26 @@
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from string.templatelib import Interpolation, Template
-from io import StringIO, BufferedWriter
 from typing import Callable
 from collections.abc import Iterable, Sequence
 import typing as t
-from collections import deque
+from contextlib import nullcontext
+from contextvars import ContextVar, Token
+import functools
+from markupsafe import Markup
 
-from .parser import parse_html
-from .nodes import (
+from .parser import TemplateParser
+from .tnodes import (
     TNode,
     TFragment,
     TElement,
     TText,
-    DocumentType,
+    TDocumentType,
     TComment,
-    ComponentInfo,
+    TComponent,
+    TLiteralAttribute,
+    TAttribute,
+)
+from .nodes import (
     VOID_ELEMENTS,
     CDATA_CONTENT_ELEMENTS,
     RCDATA_CONTENT_ELEMENTS,
@@ -22,15 +28,10 @@
 from .escaping import (
     escape_html_content_in_tag as default_escape_html_content_in_tag,
     escape_html_text as default_escape_html_text,
-    escape_html_script as default_escape_html_script,
     escape_html_comment as default_escape_html_comment,
     )
-from .processor import LastUpdatedOrderedDict
-
-
-@t.runtime_checkable
-class HasHTMLDunder(t.Protocol):
-    def __html__(self) -> str: ...  # pragma: no cover
+from .utils import CachableTemplate
+from .processor import _resolve_t_attrs, AttributesDict
 
 
 @dataclass
@@ -73,7 +74,7 @@ def __call__(self, render_api, struct_cache, q, bf, last_container_tag, template
 type InterpolationInfo = object | None
 
 
-type RenderQueueItem = tuple[str | None, Iteratable[tuple[Interpolator, Template, InterpolationInfo]]]
+type RenderQueueItem = tuple[str | None, Iterable[tuple[Interpolator, Template, InterpolationInfo]]]
 
 
 def interpolate_comment(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
@@ -84,7 +85,7 @@ def interpolate_comment(render_api, struct_cache, q, bf, last_container_tag, tem
 
 def interpolate_attrs(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, attrs = ip_info
-    attrs = render_api.resolve_attrs(render_api.interpolate_attrs(attrs, template))
+    attrs = render_api.interpolate_attrs(attrs, template)
     attrs_str = ''.join(f' {k}' if v is True else f' {k}="{render_api.escape_html_text(v)}"' for k, v in attrs.items() if v is not None and v is not False)
     bf.append(attrs_str)
 
@@ -100,14 +101,16 @@ def interpolate_component(render_api, struct_cache, q, bf, last_container_tag, t
          * transform it to a struct template
          * iteratively recurse into that result template and start outputting it
     """
-    (container_tag, attrs, start_template_interpolation_index, start_template_string_index, end_template_string_index) = ip_info
-    if end_template_string_index is not None:
-        embedded_template = render_api.transform_api.extract_embedded_template(template, start_template_string_index, end_template_string_index)
+    (container_tag, attrs, start_i_index, end_i_index, body_start_s_index) = ip_info
+    if start_i_index != end_i_index and end_i_index is not None:
+        embedded_template = render_api.transform_api.extract_embedded_template(template, body_start_s_index, end_i_index)
     else:
         embedded_template = Template('')
     embedded_struct_t = render_api.process_template(embedded_template, struct_cache)
-    attrs = render_api.resolve_attrs(render_api.interpolate_attrs(attrs, template))
-    component_callable = template.interpolations[start_template_interpolation_index].value
+    attrs = render_api.interpolate_attrs(attrs, template)
+    component_callable = template.interpolations[start_i_index].value
+    if start_i_index != end_i_index and end_i_index is not None and component_callable != template.interpolations[end_i_index].value:
+        raise TypeError('Component callable in start tag must match component callable in end tag.')
     result_template, context_values = component_callable(attrs, embedded_template, embedded_struct_t)
     if result_template:
         result_struct = render_api.process_template(result_template, struct_cache)
@@ -193,23 +196,27 @@ def transform_template(self, values_template: Template) -> Template:
         struct_node = self.to_struct_node(values_template)
         return self.to_struct_template(struct_node)
 
-    def to_struct_node(self, values_template: Template) -> Node:
-        return parse_html(values_template)
+    def to_struct_node(self, values_template: Template) -> TNode:
+        return TemplateParser.parse(values_template)
 
-    def to_struct_template(self, struct_node: Node) -> Template:
+    def to_struct_template(self, struct_node: TNode) -> Template:
         """ Recombine stream of tokens from node trees into a new template. """
         return Template(*self.streamer(struct_node))
 
     def _stream_comment_interpolation(self, text_t):
-        info = ('<!--', text_t, comment_interpolator)
+        info = ('<!--', text_t, interpolate_comment)
         return Interpolation((interpolate_comment, info), '', None, 'html_comment_template')
 
     def _stream_attrs_interpolation(self, last_container_tag, attrs):
         info = (last_container_tag, attrs)
         return Interpolation((interpolate_attrs, info), '', None, 'html_attrs_seq')
 
-    def _stream_component_interpolation(self, last_container_tag, attrs, comp_info):
-        info = (last_container_tag, attrs, comp_info.starttag_interpolation_index, comp_info.strings_slice_begin, comp_info.strings_slice_end)
+    def _stream_component_interpolation(self, last_container_tag, attrs, start_i_index, end_i_index):
+        # If the interpolation is at 1, then the opening string starts inside at least string 2 (+1)
+        # but it can't start until after any dynamic attributes without our own tag
+        # so we have to count past those.
+        body_start_s_index  = start_i_index + 1 + len([1 for attr in attrs if not isinstance(attr, TLiteralAttribute)])
+        info = (last_container_tag, attrs, start_i_index, end_i_index, body_start_s_index)
         return Interpolation((interpolate_component, info), '', None, 'tdom_component')
 
     def _stream_raw_text_interpolation(self, last_container_tag, text_t):
@@ -224,42 +231,44 @@ def _stream_text_interpolation(self, last_container_tag: str|None, values_index:
         info = (last_container_tag, values_index)
         return Interpolation((interpolate_struct_text, info), '', None, 'html_normal_interpolation')
 
-    def streamer(self, root: TNode, last_container_tag: str|None=None) -> Generator[str|Interpolation, ...]:
+    def streamer(self, root: TNode, last_container_tag: str|None=None) -> t.Iterable[str|Interpolation]:
         """
         Stream template parts back out so they can be consolidated into a new metadata-aware template.
         """
-        q: list[tuple(str | None, TNode | EndTag)] = [(last_container_tag, root)]
+        q: list[tuple[str | None, TNode | EndTag]] = [(last_container_tag, root)]
         while q:
             last_container_tag, tnode = q.pop()
             match tnode:
                 case EndTag(end_tag):
                     yield end_tag
-                case DocumentType(text):
+                case TDocumentType(text):
                     yield f'<!doctype {text}>'
-                case TComment(text_t):
+                case TComment(ref):
+                    text_t = Template(*[part if isinstance(part, str) else Interpolation(part, '', None, '') for part in iter(ref)])
                     yield '<!--'
                     yield self._stream_comment_interpolation(text_t)
                     yield '-->'
                 case TFragment(children):
                     q.extend([(last_container_tag, child) for child in reversed(children)])
-                case TElement(tag, attrs, children, component_info):
-                    if component_info is None:
-                        yield f'<{tag}'
-                        if self.has_dynamic_attrs(attrs):
-                            yield self._stream_attrs_interpolation(tag, attrs)
-                        else:
-                            yield self.static_attrs_to_str(attrs)
-                        # This is just a want to have.
-                        if self.slash_void and tag in VOID_ELEMENTS:
-                            yield ' />'
-                        else:
-                            yield '>'
-                        if tag not in VOID_ELEMENTS:
-                            q.append((last_container_tag, EndTag(f'</{tag}>')))
-                            q.extend([(tag, child) for child in reversed(children)])
+                case TComponent(start_i_index, end_i_index, attrs, children):
+                    yield self._stream_component_interpolation(last_container_tag, attrs, start_i_index, end_i_index)
+                case TElement(tag, attrs, children):
+                    yield f'<{tag}'
+                    if self.has_dynamic_attrs(attrs):
+                        yield self._stream_attrs_interpolation(tag, attrs)
+                    else:
+                        # @TODO: Probably find a less risky way to do this.
+                        yield ''.join((f'{k}={default_escape_html_text(v)}' if v is not None else f'{k}' for k, v in _resolve_t_attrs(attrs, ()).items() if v is not False and v is not None))
+                    # This is just a want to have.
+                    if self.slash_void and tag in VOID_ELEMENTS:
+                        yield ' />'
                     else:
-                        yield self._stream_component_interpolation(last_container_tag, attrs, component_info)
-                case TText(text_t):
+                        yield '>'
+                    if tag not in VOID_ELEMENTS:
+                        q.append((last_container_tag, EndTag(f'</{tag}>')))
+                        q.extend([(tag, child) for child in reversed(children)])
+                case TText(ref):
+                    text_t = Template(*[part if isinstance(part, str) else Interpolation(part, '', None, '') for part in iter(ref)])
                     if last_container_tag in CDATA_CONTENT_ELEMENTS:
                         # Must be handled all at once.
                         yield self._stream_raw_text_interpolation(last_container_tag, text_t)
@@ -277,31 +286,25 @@ def streamer(self, root: TNode, last_container_tag: str|None=None) -> Generator[
                 case _:
                     raise ValueError(f'Unrecognized tnode: {tnode}')
 
-    def static_attrs_to_str(self, attrs: tuple[tuple[str | int, ...], ...]) -> str:
-        return ''.join(f' {attr[0]}' if len(attr) == 1 else f' {attr[0]}="{self.escape_html_text(attr[1])}"' for attr in attrs)
-
-    def has_dynamic_attrs(self, attrs: tuple[tuple[str|int, ...], ...]) -> bool:
+    def has_dynamic_attrs(self, attrs: t.Sequence[TAttribute]) -> bool:
         for attr in attrs:
-             match attr:
-                 case [str()] | [str(), str()]:
-                     continue
-                 case _:
-                     return True
+            if not isinstance(attr, TLiteralAttribute):
+                return True
         return False
 
-    def extract_embedded_template(self, template: Template, start_index: int, end_index: int):
+    def extract_embedded_template(self, template: Template, body_start_s_index: int, end_i_index: int):
         """
         Extract the template parts exclusively from start tag to end tag.
 
         @TODO: "There must be a better way."
         """
-        assert end_index is not None and start_index <= end_index
         # Copy the parts out of the containing template.
-        index = start_index
+        index = body_start_s_index
+        last_s_index = end_i_index
         parts = []
-        while index < end_index:
+        while index <= last_s_index:
             parts.append(template.strings[index])
-            if index < end_index - 1:
+            if index != last_s_index:
                 parts.append(template.interpolations[index])
             index += 1
         # Now trim the first part to the end of the opening tag.
@@ -396,98 +399,9 @@ def process_template(self, template, struct_cache):
             struct_cache[template.strings] = self.transform_api.transform_template(template)
         return struct_cache[template.strings]
 
-    def interpolate_attrs(self, attrs, template) -> Generator[tuple[str, object|None]]:
+    def interpolate_attrs(self, attrs, template) -> AttributesDict:
         """ Plug `template` values into any attribute interpolations. """
-        for attr in attrs:
-            match attr:
-                case [str()]:
-                    yield (attr[0], True)
-                case [str(), str()]:
-                    yield (attr[0], attr[1])
-                case [str(), int()]:
-                    yield (attr[0], template.interpolations[attr[1]].value)
-                case [str(), str()|int(), _, *_]:
-                    v_str = ''.join(part if isinstance(part, str) else str(template.interpolations[part.value].value) for part in attr[1:])
-                    yield (attr[0], v_str)
-                case [int()]:
-                    spread_attrs = template.interpolations[attr[0]].value
-                    yield from spread_attrs.items() if hasattr(spread_attrs, 'items') else spread_attrs
-                case _:
-                    raise ValueError(f'Unrecognized attr format {attr}')
-
-    def resolve_attrs(self, attrs) -> dict[str, object|None]:
-        # @TODO: This should be using the processor to resolve these.
-        new_attrs = LastUpdatedOrderedDict()
-        klass = {}
-        for k, v in attrs:
-            match k:
-                case 'class':
-                    # Special cases to allow unsetting all classes.  Do we really need all over these?
-                    if v is True:
-                        new_attrs['class'] = v
-                        klass.clear()
-                    elif v is None:
-                        new_attrs['class'] = None
-                        klass.clear()
-                    elif v == '':
-                        new_attrs['class'] = ''
-                        klass.clear()
-                    else:
-                        q = [v]
-                        changes = {}
-                        while q:
-                            sub_v = q.pop()
-                            match sub_v:
-                                case str():
-                                    if ' ' not in sub_v:
-                                        changes[sub_v] = True
-                                    else:
-                                        for cn in sub_v.split():
-                                            changes[cn] = True
-                                case dict():
-                                    for cn, enabled in sub_v.items():
-                                        changes[cn] = enabled
-                                case Iterable():
-                                    q.extend(reversed(sub_v))
-                                case None|False:
-                                    pass
-                                case _:
-                                    raise ValueError(f'Unrecognized format for class attribute: {sub_v}')
-                        if changes:
-                            klass.update(changes)
-                            class_str = ' '.join(cn for cn, enabled in klass.items() if enabled)
-                            if class_str != new_attrs.get('class', None):
-                                new_attrs['class'] = class_str
-                case 'style':
-                    match v:
-                        case None:
-                            new_attrs['style'] = None
-                        case str():
-                            new_attrs['style'] = v
-                        case Iterable():
-                            new_attrs['style'] = '; '.join(f'{pn}: {pv}' for pn, pv in (v.items() if hasattr(v, 'items') else v))
-                        case _:
-                            raise ValueError(f'Unrecognized format for style attribute: {v}')
-                case 'aria':
-                    for an, av in (v.items() if hasattr(v, 'items') else v):
-                        full_name = f'aria-{an}'
-                        match av:
-                            case True:
-                                new_attrs[full_name] = 'true'
-                            case False:
-                                new_attrs[full_name] = 'false'
-                            case None:
-                                new_attrs[full_name] = None
-                            case str():
-                                new_attrs[full_name] = av
-                            case _:
-                                new_attrs[full_name] = str(av)
-                case 'data':
-                    for dn, dv in (v.items() if hasattr(v, 'items') else v):
-                        new_attrs[f'data-{dn}'] = dv
-                case _:
-                    new_attrs[k] = v
-        return new_attrs
+        return _resolve_t_attrs(attrs, template.interpolations)
 
     def walk_template_with_context(self, bf, template, struct_t, context_values=None):
         if context_values:
@@ -512,19 +426,17 @@ def walk_template(self, bf, template, struct_t):
         if strings[idx]:
             bf.append(strings[idx])
 
-from contextlib import nullcontext
-from contextvars import ContextVar, Token
+
 class ContextVarSetter:
-    context_values: tuple[tuple[ContextVar, object]]
-    tokens: tuple[Token] | None = None
+    context_values: tuple[tuple[ContextVar, object],...]
+    tokens: tuple[Token,...]
 
-    def __init__(self, context_values=None):
+    def __init__(self, context_values=()):
         self.context_values = context_values
+        self.tokens = ()
 
     def __enter__(self):
         self.tokens = tuple([var.set(val) for var, val in self.context_values])
-        print (f'{[var.get() for var, _ in self.context_values]}')
-        print (f'{self.tokens=}')
 
     def __exit__(self, exc_type, exc_value, traceback):
         for idx, var_value in enumerate(self.context_values):
@@ -534,3 +446,17 @@ def __exit__(self, exc_type, exc_value, traceback):
 def render_service_factory():
     return RenderService(transform_api=TransformService())
 
+
+#
+# SHIM: This is here until we can find a way to make a configurable cache.
+#
+@dataclass(frozen=True)
+class CachedRenderService(RenderService):
+
+    @functools.lru_cache
+    def _process_template(self, cached_template: CachableTemplate):
+        return self.transform_api.transform_template(cached_template.template)
+
+    def process_template(self, template: Template, struct_cache: dict):
+        ct = CachableTemplate(template)
+        return self._process_template(ct)

From e37d2281a6444d5a4ab2d1f92219b8e6c8237dee Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Wed, 31 Dec 2025 18:05:30 -0800
Subject: [PATCH 13/81] Expand tests.

---
 tdom/transformer_test.py | 83 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 3 deletions(-)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 5098470..146e8d4 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -1,4 +1,8 @@
 from .transformer import render_service_factory
+from contextvars import ContextVar
+
+
+theme_context_var = ContextVar('theme', default='default')
 
 
 def test_render_template():
@@ -34,13 +38,13 @@ def get_color_select_t(selected_values: set) -> Template:
     assert render_api.render_template(get_color_select_t(set()), struct_cache) == '<select><option value="R">Red</option><option value="Y">Yellow</option><option value="B">Blue</option></select>'
     assert render_api.render_template(get_color_select_t({'Y'}), struct_cache) == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'
 
-from contextvars import ContextVar
 
 
-theme_context_var = ContextVar('theme', default='default')
 
 
-def test_component():
+
+
+def test_render_component_with_context():
 
     def ThemeContext(attrs, embedded_t, embedded_struct):
         context_values = ((theme_context_var, attrs.get('value', 'normal')),)
@@ -56,3 +60,76 @@ def ThemedDiv(attrs, embedded_t, embedded_struct):
         assert render_api.render_template(body_t) == '<div><div data-theme="holiday"><b>Cheers!</b></div></div>'
         assert theme_context_var.get() == 'not-the-default'
     assert theme_context_var.get() == 'default'
+
+
+def test_render_template_components_smoketest():
+
+    def PageComponent(attrs, content_t, content_struct):
+        return t'''<div class="content">{content_t}</div>''', ()
+
+    def FooterComponent(attrs, body_t, body_struct):
+        return t'<div class="footer"><a href="about">About</a></div>', ()
+
+    def LayoutComponent(attrs, body_t, body_struct):
+        return t'''<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <script src="scripts.js"></script>
+    <link rel="stylesheet" href="styles.css">
+  </head>
+  <body>{body_t}<{FooterComponent} /></body>
+</html>
+''', ()
+
+    render_api = render_service_factory()
+    content = 'HTML never goes out of style.'
+    content_str = render_api.render_template(t'<{LayoutComponent}><{PageComponent}>{content}</{PageComponent}></{LayoutComponent}>')
+    assert content_str == '''<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <script src="scripts.js"></script>
+    <link rel="stylesheet" href="styles.css">
+  </head>
+  <body><div class="content">HTML never goes out of style.</div><div class="footer"><a href="about">About</a></div></body>
+</html>
+'''
+
+
+def test_render_template_functions_smoketest():
+
+    def make_page_t(content: str) -> Template:
+        return t'''<div class="content">{content}</div>'''
+
+    def make_footer_t() -> Template:
+        return t'<div class="footer"><a href="about">About</a></div>'
+
+    def make_layout_t(body_t: Template) -> Template:
+        footer_t = make_footer_t()
+        return t'''<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <script src="scripts.js"></script>
+    <link rel="stylesheet" href="styles.css">
+  </head>
+  <body>{body_t}{footer_t}</body>
+</html>
+'''
+
+    render_api = render_service_factory()
+    content = 'HTML never goes out of style.'
+    layout_t = make_layout_t(make_page_t(content))
+    content_str = render_api.render_template(layout_t)
+    assert content_str == '''<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <script src="scripts.js"></script>
+    <link rel="stylesheet" href="styles.css">
+  </head>
+  <body><div class="content">HTML never goes out of style.</div><div class="footer"><a href="about">About</a></div></body>
+</html>
+'''
+

From 8df29bd60683cf01e9e20f2ca56f49005bf0d533 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Wed, 31 Dec 2025 21:53:40 -0800
Subject: [PATCH 14/81] Delegate as much attribute resolution to processor as
 possible.

---
 tdom/transformer.py | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 7316b43..2b19857 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -8,7 +8,7 @@
 import functools
 from markupsafe import Markup
 
-from .parser import TemplateParser
+from .parser import TemplateParser, HTMLAttributesDict
 from .tnodes import (
     TNode,
     TFragment,
@@ -31,7 +31,7 @@
     escape_html_comment as default_escape_html_comment,
     )
 from .utils import CachableTemplate
-from .processor import _resolve_t_attrs, AttributesDict
+from .processor import _resolve_t_attrs, AttributesDict, _resolve_html_attrs
 
 
 @dataclass
@@ -39,6 +39,10 @@ class EndTag:
     end_tag: str
 
 
+def render_html_attrs(html_attrs: HTMLAttributesDict, escape: Callable = default_escape_html_text) -> str:
+    return ''.join((f' {k}="{v}"' if v is not None else f' {k}' for k, v in html_attrs.items()))
+
+
 class Interpolator(t.Protocol):
 
     def __call__(self, render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
@@ -85,8 +89,8 @@ def interpolate_comment(render_api, struct_cache, q, bf, last_container_tag, tem
 
 def interpolate_attrs(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, attrs = ip_info
-    attrs = render_api.interpolate_attrs(attrs, template)
-    attrs_str = ''.join(f' {k}' if v is True else f' {k}="{render_api.escape_html_text(v)}"' for k, v in attrs.items() if v is not None and v is not False)
+    html_attrs = render_api.interpolate_attrs(attrs, template)
+    attrs_str = render_html_attrs(_resolve_html_attrs(html_attrs))
     bf.append(attrs_str)
 
 
@@ -257,8 +261,7 @@ def streamer(self, root: TNode, last_container_tag: str|None=None) -> t.Iterable
                     if self.has_dynamic_attrs(attrs):
                         yield self._stream_attrs_interpolation(tag, attrs)
                     else:
-                        # @TODO: Probably find a less risky way to do this.
-                        yield ''.join((f'{k}={default_escape_html_text(v)}' if v is not None else f'{k}' for k, v in _resolve_t_attrs(attrs, ()).items() if v is not False and v is not None))
+                        yield render_html_attrs(_resolve_html_attrs(_resolve_t_attrs(attrs, interpolations=())))
                     # This is just a want to have.
                     if self.slash_void and tag in VOID_ELEMENTS:
                         yield ' />'

From f862917625e039c061305f268560d01c2cb4d6b0 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Wed, 31 Dec 2025 21:55:13 -0800
Subject: [PATCH 15/81] Cleanup transformer tests.

---
 tdom/transformer_test.py | 47 ++++++++++++++++++++--------------------
 1 file changed, 24 insertions(+), 23 deletions(-)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 146e8d4..4351d09 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -1,47 +1,48 @@
 from .transformer import render_service_factory
 from contextvars import ContextVar
+from string.templatelib import Template
 
 
 theme_context_var = ContextVar('theme', default='default')
 
 
-def test_render_template():
+def test_render_template_repeated():
     def get_sample_t(idx, spread_attrs, button_text):
         return t'''<div><button data-key={idx} {spread_attrs}>{button_text}</button></div>'''
     render_api = render_service_factory()
     struct_cache = {}
-    for count in (1, 1, 100):
-        for idx in range(count):
-            spread_attrs = {'data-enabled': True}
-            button_text = 'RENDER'
-            sample_t = get_sample_t(idx, spread_attrs, button_text)
-            assert ''.join(render_api.render_template(sample_t, struct_cache)) == f'<div><button data-key="{idx}" data-enabled>RENDER</button></div>'
-
-    new_sample_t = get_sample_t("zebra", {"diff": "yes"}, t"<div>{sample_t}</div>") # You dirty dog! Stay. In. Your. Scope.
-    assert ''.join(render_api.render_template(new_sample_t, struct_cache)) == \
-        f'<div><button data-key="zebra" diff="yes"><div><div><button data-key="99" data-enabled>RENDER</button></div></div></button></div>'
-
-def test_render_select():
+    for idx in range(3):
+        spread_attrs = {'data-enabled': True}
+        button_text = 'RENDER'
+        sample_t = get_sample_t(idx, spread_attrs, button_text)
+        assert render_api.render_template(sample_t, struct_cache) == f'<div><button data-key="{idx}" data-enabled>RENDER</button></div>'
+
+def test_render_template_iterables():
     render_api = render_service_factory()
 
-    def get_select_t(options, selected_values):
+    def get_select_t_with_list(options, selected_values):
         return t'''<select>{[
             t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>" for opt in options]
         }</select>'''
+    def get_select_t_with_generator(options, selected_values):
+        return t'''<select>{(
+            t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>" for opt in options)
+        }</select>'''
+    def get_select_t_with_concat(options, selected_values):
+        parts = [t'<select>']
+        parts.extend([t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>" for opt in options])
+        parts.append(t'</select>')
+        return sum(parts, t"")
 
-    def get_color_select_t(selected_values: set) -> Template:
+    def get_color_select_t(selected_values: set, provider: Callable) -> Template:
         PRIMARY_COLORS = [("R", "Red"), ("Y", "Yellow"), ("B", "Blue")]
         assert set(selected_values).issubset(set([opt[0] for opt in PRIMARY_COLORS]))
-        return get_select_t(PRIMARY_COLORS, selected_values)
+        return provider(PRIMARY_COLORS, selected_values)
 
     struct_cache = {}
-    assert render_api.render_template(get_color_select_t(set()), struct_cache) == '<select><option value="R">Red</option><option value="Y">Yellow</option><option value="B">Blue</option></select>'
-    assert render_api.render_template(get_color_select_t({'Y'}), struct_cache) == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'
-
-
-
-
-
+    for provider in (get_select_t_with_list,get_select_t_with_generator,get_select_t_with_concat):
+        assert render_api.render_template(get_color_select_t(set(), provider), struct_cache) == '<select><option value="R">Red</option><option value="Y">Yellow</option><option value="B">Blue</option></select>'
+        assert render_api.render_template(get_color_select_t({'Y'}, provider), struct_cache) == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'
 
 
 def test_render_component_with_context():

From 23260fbf6a793bca47afc161376b66833e83f64a Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 1 Jan 2026 00:01:56 -0800
Subject: [PATCH 16/81] Use another lru cache.

---
 tdom/transformer.py | 68 +++++++++++++++++++++------------------------
 1 file changed, 31 insertions(+), 37 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 2b19857..6136428 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -45,19 +45,13 @@ def render_html_attrs(html_attrs: HTMLAttributesDict, escape: Callable = default
 
 class Interpolator(t.Protocol):
 
-    def __call__(self, render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+    def __call__(self, render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
         """
         Populates an interpolation or returns iterator to decende into.
 
         If recursion is required then pushes current iterator
         render_api
             The current render api, provides various helper methods to the interpolator.
-        struct_cache
-            The struct cache, this is mainly needed because it is not bound to the render api
-            and this might change.  If we want to run a new template through the render api we need
-            the cache to pass in which is kind of kludgy.  Maybe the render_api should be more of a
-            render_session or something that binds the cache and the render service together.  OR
-            we can just pass around 50 params...
         q
             A list-like queue of iterators paired with the container tag the results are in.
         bf
@@ -81,20 +75,20 @@ def __call__(self, render_api, struct_cache, q, bf, last_container_tag, template
 type RenderQueueItem = tuple[str | None, Iterable[tuple[Interpolator, Template, InterpolationInfo]]]
 
 
-def interpolate_comment(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_comment(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, comment_t = ip_info
     assert container_tag == '<!--'
     bf.append(render_api.escape_html_comment(render_api.resolve_text_without_recursion(template, container_tag, comment_t)))
 
 
-def interpolate_attrs(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_attrs(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, attrs = ip_info
     html_attrs = render_api.interpolate_attrs(attrs, template)
     attrs_str = render_html_attrs(_resolve_html_attrs(html_attrs))
     bf.append(attrs_str)
 
 
-def interpolate_component(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_component(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     """
     - Extract embedded template or use empty template.
     - Transform embedded template into struct template.
@@ -110,14 +104,14 @@ def interpolate_component(render_api, struct_cache, q, bf, last_container_tag, t
         embedded_template = render_api.transform_api.extract_embedded_template(template, body_start_s_index, end_i_index)
     else:
         embedded_template = Template('')
-    embedded_struct_t = render_api.process_template(embedded_template, struct_cache)
+    embedded_struct_t = render_api.process_template(embedded_template)
     attrs = render_api.interpolate_attrs(attrs, template)
     component_callable = template.interpolations[start_i_index].value
     if start_i_index != end_i_index and end_i_index is not None and component_callable != template.interpolations[end_i_index].value:
         raise TypeError('Component callable in start tag must match component callable in end tag.')
     result_template, context_values = component_callable(attrs, embedded_template, embedded_struct_t)
     if result_template:
-        result_struct = render_api.process_template(result_template, struct_cache)
+        result_struct = render_api.process_template(result_template)
         if context_values:
             walker = render_api.walk_template_with_context(bf, result_template, result_struct, context_values=context_values)
         else:
@@ -125,17 +119,17 @@ def interpolate_component(render_api, struct_cache, q, bf, last_container_tag, t
         return (container_tag, iter(walker))
 
 
-def interpolate_raw_text(render_api, struct_cache, q, bf, last_container_tag, template, value) -> RenderQueueItem | None:
+def interpolate_raw_text(render_api, q, bf, last_container_tag, template, value) -> RenderQueueItem | None:
     container_tag, content_t = value
     bf.append(render_api.escape_html_content_in_tag(container_tag, render_api.resolve_text_without_recursion(template, container_tag, content_t)))
 
 
-def interpolate_escapable_raw_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_escapable_raw_text(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, content_t = ip_info
     bf.append(render_api.escape_html_text(render_api.resolve_text_without_recursion(template, container_tag, content_t)))
 
 
-def interpolate_struct_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_struct_text(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, ip_index = ip_info
     # @TODO: We just completely ignore any conversion or format_spec here.
     # This is actually a much larger problem/decision of how can a user give us more information about what to do
@@ -145,14 +139,14 @@ def interpolate_struct_text(render_api, struct_cache, q, bf, last_container_tag,
     #   - The 4th interpolation will be an iterator of html-aware Template strings
     #   - The 5th interpolation will be an iterator of strings to render and escape.
     value = template.interpolations[ip_index].value # data provided to a parsed t-string
-    return interpolate_text(render_api, struct_cache, q, bf, last_container_tag, template, (container_tag, value))
+    return interpolate_text(render_api, q, bf, last_container_tag, template, (container_tag, value))
 
 
-def interpolate_user_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
-    return interpolate_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info)
+def interpolate_user_text(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+    return interpolate_text(render_api, q, bf, last_container_tag, template, ip_info)
 
 
-def interpolate_text(render_api, struct_cache, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_text(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, value = ip_info
     if container_tag is None:
         container_tag = last_container_tag
@@ -162,7 +156,7 @@ def interpolate_text(render_api, struct_cache, q, bf, last_container_tag, templa
     #
     if not isinstance(value, str):
         if isinstance(value, Template):
-            return (container_tag, iter(render_api.walk_template(bf, value, render_api.process_template(value, struct_cache))))
+            return (container_tag, iter(render_api.walk_template(bf, value, render_api.process_template(value))))
         elif isinstance(value, Sequence) or hasattr(value, '__iter__'):
             return (container_tag, (((interpolate_user_text, template, (None, v)) for v in iter(value))))
         elif value is False or value is None:
@@ -208,7 +202,7 @@ def to_struct_template(self, struct_node: TNode) -> Template:
         return Template(*self.streamer(struct_node))
 
     def _stream_comment_interpolation(self, text_t):
-        info = ('<!--', text_t, interpolate_comment)
+        info = ('<!--', text_t)
         return Interpolation((interpolate_comment, info), '', None, 'html_comment_template')
 
     def _stream_attrs_interpolation(self, last_container_tag, attrs):
@@ -328,7 +322,7 @@ class RenderService:
 
     escape_html_content_in_tag: Callable = default_escape_html_content_in_tag
 
-    def render_template(self, template, struct_cache=None, last_container_tag=None) -> str:
+    def render_template(self, template, last_container_tag=None) -> str:
         """
         Iterate left to right and pause and push new iterators when descending depth-first.
 
@@ -340,16 +334,13 @@ def render_template(self, template, struct_cache=None, last_container_tag=None)
         text processing.  When working with fragments we might not know the
         container tag until the fragment is included at render-time.
         """
-        if struct_cache is None:
-            struct_cache = {}
-
         bf: list[str] = []
         q: list[RenderQueueItem] = []
-        q.append((last_container_tag, self.walk_template(bf, template, self.process_template(template, struct_cache))))
+        q.append((last_container_tag, self.walk_template(bf, template, self.process_template(template))))
         while q:
             last_container_tag, it = q.pop()
             for (interpolator, template, ip_info) in it:
-                render_queue_item = interpolator(self, struct_cache, q, bf, last_container_tag, template, ip_info)
+                render_queue_item = interpolator(self, q, bf, last_container_tag, template, ip_info)
                 if render_queue_item is not None:
                     #
                     # Pause the current iterator and push a new iterator on top of it.
@@ -397,10 +388,9 @@ def resolve_text_without_recursion(self, template, container_tag, content_t) ->
                             text.append(value_str)
             return ''.join(text)
 
-    def process_template(self, template, struct_cache):
-        if template.strings not in struct_cache:
-            struct_cache[template.strings] = self.transform_api.transform_template(template)
-        return struct_cache[template.strings]
+    def process_template(self, template):
+        """ This is just a wrap-point for caching. """
+        return self.transform_api.transform_template(template)
 
     def interpolate_attrs(self, attrs, template) -> AttributesDict:
         """ Plug `template` values into any attribute interpolations. """
@@ -450,16 +440,20 @@ def render_service_factory():
     return RenderService(transform_api=TransformService())
 
 
+def cached_render_service_factory():
+    return RenderService(transform_api=CachedTransformService())
+
+
 #
 # SHIM: This is here until we can find a way to make a configurable cache.
 #
 @dataclass(frozen=True)
-class CachedRenderService(RenderService):
+class CachedTransformService(TransformService):
 
-    @functools.lru_cache
-    def _process_template(self, cached_template: CachableTemplate):
-        return self.transform_api.transform_template(cached_template.template)
+    @functools.lru_cache(512)
+    def _transform_template(self, cached_template: CachableTemplate) -> TNode:
+        return super().transform_template(cached_template.template)
 
-    def process_template(self, template: Template, struct_cache: dict):
+    def transform_template(self, template: Template) -> TNode:
         ct = CachableTemplate(template)
-        return self._process_template(ct)
+        return self._transform_template(ct)

From a3c3ab4924d2f4758442734bfd0832aed0578dd6 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 1 Jan 2026 00:02:30 -0800
Subject: [PATCH 17/81] Expand tests for cache, add another large smoketest.

---
 tdom/transformer_test.py | 88 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 77 insertions(+), 11 deletions(-)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 4351d09..08cdb29 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -1,4 +1,4 @@
-from .transformer import render_service_factory
+from .transformer import render_service_factory, cached_render_service_factory, CachedTransformService
 from contextvars import ContextVar
 from string.templatelib import Template
 
@@ -6,16 +6,83 @@
 theme_context_var = ContextVar('theme', default='default')
 
 
+def test_render_template_smoketest():
+    comment_text = 'comment is not literal'
+    interpolated_class = 'red'
+    text_in_element = 'text is not literal'
+    templated = "not literal"
+    spread_attrs={'data-on': True}
+    def comp(attrs, body_t, body_struct):
+        return t'<div>{body_t}</div>', ()
+    smoke_t = t'''<!doctype html>
+<html>
+<body>
+<!-- literal -->
+<span attr="literal">literal</span>
+<!-- {comment_text} -->
+<span>{text_in_element}</span>
+<span attr="literal" class={interpolated_class} title="is {templated}" {spread_attrs}>{text_in_element}</span>
+<{comp}><span>comp body</span></{comp}>
+</body>
+</html>'''
+    smoke_str = '''<!doctype html>
+<html>
+<body>
+<!-- literal -->
+<span attr="literal">literal</span>
+<!-- comment is not literal -->
+<span>text is not literal</span>
+<span attr="literal" title="is not literal" data-on class="red">text is not literal</span>
+<div><span>comp body</span></div>
+</body>
+</html>'''
+    render_api = render_service_factory()
+    assert render_api.render_template(smoke_t) == smoke_str
+
+
+def struct_repr(st):
+    return st.strings, tuple([(i.value, i.expression, i.conversion, i.format_spec) for i in st.interpolations])
+
+
+def test_process_template_internal_cache():
+    sample_t = t'''<div>{'content'}</div>'''
+    sample_diff_t = t'''<div>{'diffcontent'}</div>'''
+    alt_t = t'''<span>{'content'}</span>'''
+    render_api = render_service_factory()
+    cached_render_api = cached_render_service_factory()
+    #CachedTransformService
+    tnode1 = render_api.process_template(sample_t)
+    tnode2 = render_api.process_template(sample_t)
+    cached_tnode1 = cached_render_api.process_template(sample_t)
+    cached_tnode2 = cached_render_api.process_template(sample_t)
+    cached_tnode3 = cached_render_api.process_template(sample_diff_t)
+    assert tnode1 is not cached_tnode1
+    assert tnode1 is not cached_tnode2
+    assert tnode1 is not cached_tnode3
+    assert tnode1 is not tnode2
+    assert cached_tnode1 is cached_tnode2
+    assert cached_tnode1 is cached_tnode3
+    assert struct_repr(tnode1) == struct_repr(cached_tnode1)
+    assert struct_repr(tnode2) == struct_repr(cached_tnode1)
+    # @TODO: Maybe we should be acting directly on the transform service here?
+    ci = cached_render_api.transform_api._transform_template.cache_info()
+    assert ci.hits == 2, "lookup #2 and lookup #3"
+    assert ci.misses == 1, "lookup #1"
+    cached_tnode4 = cached_render_api.process_template(alt_t)
+    assert cached_tnode1 is not cached_tnode4
+    assert struct_repr(cached_tnode1) != struct_repr(cached_tnode4)
+
+
 def test_render_template_repeated():
     def get_sample_t(idx, spread_attrs, button_text):
         return t'''<div><button data-key={idx} {spread_attrs}>{button_text}</button></div>'''
-    render_api = render_service_factory()
-    struct_cache = {}
-    for idx in range(3):
-        spread_attrs = {'data-enabled': True}
-        button_text = 'RENDER'
-        sample_t = get_sample_t(idx, spread_attrs, button_text)
-        assert render_api.render_template(sample_t, struct_cache) == f'<div><button data-key="{idx}" data-enabled>RENDER</button></div>'
+    render_apis = (render_service_factory(), cached_render_service_factory())
+    for render_api in render_apis:
+        for idx in range(3):
+            spread_attrs = {'data-enabled': True}
+            button_text = 'RENDER'
+            sample_t = get_sample_t(idx, spread_attrs, button_text)
+            assert render_api.render_template(sample_t) == f'<div><button data-key="{idx}" data-enabled>RENDER</button></div>'
 
 def test_render_template_iterables():
     render_api = render_service_factory()
@@ -39,10 +106,9 @@ def get_color_select_t(selected_values: set, provider: Callable) -> Template:
         assert set(selected_values).issubset(set([opt[0] for opt in PRIMARY_COLORS]))
         return provider(PRIMARY_COLORS, selected_values)
 
-    struct_cache = {}
     for provider in (get_select_t_with_list,get_select_t_with_generator,get_select_t_with_concat):
-        assert render_api.render_template(get_color_select_t(set(), provider), struct_cache) == '<select><option value="R">Red</option><option value="Y">Yellow</option><option value="B">Blue</option></select>'
-        assert render_api.render_template(get_color_select_t({'Y'}, provider), struct_cache) == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'
+        assert render_api.render_template(get_color_select_t(set(), provider)) == '<select><option value="R">Red</option><option value="Y">Yellow</option><option value="B">Blue</option></select>'
+        assert render_api.render_template(get_color_select_t({'Y'}, provider)) == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'
 
 
 def test_render_component_with_context():

From 7c41ee142e013a7ec6f14d4453772d25f63d4edb Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 1 Jan 2026 00:12:29 -0800
Subject: [PATCH 18/81] Fix signature.

---
 tdom/transformer.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 6136428..0f248be 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -451,9 +451,9 @@ def cached_render_service_factory():
 class CachedTransformService(TransformService):
 
     @functools.lru_cache(512)
-    def _transform_template(self, cached_template: CachableTemplate) -> TNode:
+    def _transform_template(self, cached_template: CachableTemplate) -> Template:
         return super().transform_template(cached_template.template)
 
-    def transform_template(self, template: Template) -> TNode:
-        ct = CachableTemplate(template)
+    def transform_template(self, values_template: Template) -> Template:
+        ct = CachableTemplate(values_template)
         return self._transform_template(ct)

From 5d65cc73ee25dfe2db87810fb9fa4a0038baa875 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 1 Jan 2026 00:12:41 -0800
Subject: [PATCH 19/81] Add __html__ to smoke test.

---
 tdom/transformer_test.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 08cdb29..8d4626d 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -1,7 +1,7 @@
 from .transformer import render_service_factory, cached_render_service_factory, CachedTransformService
 from contextvars import ContextVar
 from string.templatelib import Template
-
+from markupsafe import Markup
 
 theme_context_var = ContextVar('theme', default='default')
 
@@ -12,6 +12,7 @@ def test_render_template_smoketest():
     text_in_element = 'text is not literal'
     templated = "not literal"
     spread_attrs={'data-on': True}
+    markup_content = Markup('<div>safe</div>')
     def comp(attrs, body_t, body_struct):
         return t'<div>{body_t}</div>', ()
     smoke_t = t'''<!doctype html>
@@ -23,6 +24,7 @@ def comp(attrs, body_t, body_struct):
 <span>{text_in_element}</span>
 <span attr="literal" class={interpolated_class} title="is {templated}" {spread_attrs}>{text_in_element}</span>
 <{comp}><span>comp body</span></{comp}>
+{markup_content}
 </body>
 </html>'''
     smoke_str = '''<!doctype html>
@@ -34,6 +36,7 @@ def comp(attrs, body_t, body_struct):
 <span>text is not literal</span>
 <span attr="literal" title="is not literal" data-on class="red">text is not literal</span>
 <div><span>comp body</span></div>
+<div>safe</div>
 </body>
 </html>'''
     render_api = render_service_factory()

From 808a0c3a7ba3f868be879665cfaca18fd076f62a Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 1 Jan 2026 01:22:28 -0800
Subject: [PATCH 20/81] Add in experiment with callable info style components.

---
 tdom/transformer.py      | 76 ++++++++++++++++++++++++++++++++++++++--
 tdom/transformer_test.py | 46 ++++++++++++++++++++----
 2 files changed, 113 insertions(+), 9 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 0f248be..f6c3c3f 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -31,7 +31,8 @@
     escape_html_comment as default_escape_html_comment,
     )
 from .utils import CachableTemplate
-from .processor import _resolve_t_attrs, AttributesDict, _resolve_html_attrs
+from .processor import _resolve_t_attrs, AttributesDict, _resolve_html_attrs, _kebab_to_snake
+from .callables import get_callable_info
 
 
 @dataclass
@@ -88,6 +89,62 @@ def interpolate_attrs(render_api, q, bf, last_container_tag, template, ip_info)
     bf.append(attrs_str)
 
 
+def invoke_passthru(component_callable, attrs, embedded_template, embedded_struct_t):
+    result_template = component_callable(attrs, embedded_template, embedded_struct_t)
+    return result_template, ()
+
+
+def invoke_passthru_cvalues(component_callable, attrs, embedded_template, embedded_struct_t):
+    result_template, context_values = component_callable(attrs, embedded_template, embedded_struct_t)
+    return result_template, context_values
+
+
+def _prep_cinfo(component_callable, attrs, embedded_template, embedded_struct_t):
+    # @TODO: This is lifted from the processor and then grossified.
+    # Not sure this will work out but maybe we'd unify these.
+    callable_info = get_callable_info(component_callable)
+
+    if callable_info.requires_positional:
+        raise TypeError(
+            "Component callables cannot have required positional arguments."
+        )
+
+    kwargs: AttributesDict = {}
+
+    # Add all supported attributes
+    for attr_name, attr_value in attrs.items():
+        snake_name = _kebab_to_snake(attr_name)
+        if snake_name in callable_info.named_params or callable_info.kwargs:
+            kwargs[snake_name] = attr_value
+
+    # Add system vars if appropriate
+    if "embedded_template" in callable_info.named_params or callable_info.kwargs:
+        kwargs["embedded_template"] = embedded_template
+    # I'm sure the phone is ringing of the hook for this one.
+    if "embedded_struct_t" in callable_info.named_params or callable_info.kwargs:
+        kwargs["embedded_struct_t"] = embedded_struct_t
+
+    # Check to make sure we've fully satisfied the callable's requirements
+    missing = callable_info.required_named_params - kwargs.keys()
+    if missing:
+        raise TypeError(
+            f"Missing required parameters for component: {', '.join(missing)}"
+        )
+    return kwargs
+
+
+def invoke_cinfo(component_callable, attrs, embedded_template, embedded_struct_t):
+    kwargs = _prep_cinfo(component_callable, attrs, embedded_template, embedded_struct_t)
+    result = component_callable(**kwargs)
+    return result, ()
+
+
+def invoke_cinfo_cvalues(component_callable, attrs, embedded_template, embedded_struct_t):
+    kwargs = _prep_cinfo(component_callable, attrs, embedded_template, embedded_struct_t)
+    result, context_values = component_callable(**kwargs)
+    return result, context_values
+
+
 def interpolate_component(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     """
     - Extract embedded template or use empty template.
@@ -106,10 +163,23 @@ def interpolate_component(render_api, q, bf, last_container_tag, template, ip_in
         embedded_template = Template('')
     embedded_struct_t = render_api.process_template(embedded_template)
     attrs = render_api.interpolate_attrs(attrs, template)
-    component_callable = template.interpolations[start_i_index].value
+    start_i = template.interpolations[start_i_index]
+    component_callable = start_i.value
     if start_i_index != end_i_index and end_i_index is not None and component_callable != template.interpolations[end_i_index].value:
         raise TypeError('Component callable in start tag must match component callable in end tag.')
-    result_template, context_values = component_callable(attrs, embedded_template, embedded_struct_t)
+
+    # @TODO: Amazingly this works!  It looks terrible though! Maybe we'll keep pushing symbols around...
+    if start_i.format_spec == '' or start_i.format_spec == 'passthru':
+        invoke_strat = invoke_passthru
+    elif start_i.format_spec == 'passthru+cvalues':
+        invoke_strat = invoke_passthru_cvalues
+    elif start_i.format_spec == 'cinfo':
+        invoke_strat = invoke_cinfo
+    elif start_i.format_spec == 'cinfo+cvalues':
+        invoke_strat = invoke_cinfo_cvalues
+    else:
+        raise ValueError(f'Unknown format spec: {start_i.format_spec}')
+    result_template, context_values = invoke_strat(component_callable, attrs, embedded_template, embedded_struct_t)
     if result_template:
         result_struct = render_api.process_template(result_template)
         if context_values:
diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 8d4626d..05770b2 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -14,7 +14,7 @@ def test_render_template_smoketest():
     spread_attrs={'data-on': True}
     markup_content = Markup('<div>safe</div>')
     def comp(attrs, body_t, body_struct):
-        return t'<div>{body_t}</div>', ()
+        return t'<div>{body_t}</div>'
     smoke_t = t'''<!doctype html>
 <html>
 <body>
@@ -122,10 +122,10 @@ def ThemeContext(attrs, embedded_t, embedded_struct):
 
     def ThemedDiv(attrs, embedded_t, embedded_struct):
         theme = theme_context_var.get()
-        return t'<div data-theme="{theme}">{embedded_t}</div>', ()
+        return t'<div data-theme="{theme}">{embedded_t}</div>'
 
     render_api = render_service_factory()
-    body_t = t"<div><{ThemeContext} value='holiday'><{ThemedDiv}><b>Cheers!</b></{ThemedDiv}></{ThemeContext}></div>"
+    body_t = t"<div><{ThemeContext:passthru+cvalues} value='holiday'><{ThemedDiv}><b>Cheers!</b></{ThemedDiv}></{ThemeContext}></div>"
     with theme_context_var.set('not-the-default'):
         assert render_api.render_template(body_t) == '<div><div data-theme="holiday"><b>Cheers!</b></div></div>'
         assert theme_context_var.get() == 'not-the-default'
@@ -135,10 +135,10 @@ def ThemedDiv(attrs, embedded_t, embedded_struct):
 def test_render_template_components_smoketest():
 
     def PageComponent(attrs, content_t, content_struct):
-        return t'''<div class="content">{content_t}</div>''', ()
+        return t'''<div class="content">{content_t}</div>'''
 
     def FooterComponent(attrs, body_t, body_struct):
-        return t'<div class="footer"><a href="about">About</a></div>', ()
+        return t'<div class="footer"><a href="about">About</a></div>'
 
     def LayoutComponent(attrs, body_t, body_struct):
         return t'''<!doctype html>
@@ -150,7 +150,7 @@ def LayoutComponent(attrs, body_t, body_struct):
   </head>
   <body>{body_t}<{FooterComponent} /></body>
 </html>
-''', ()
+'''
 
     render_api = render_service_factory()
     content = 'HTML never goes out of style.'
@@ -203,3 +203,37 @@ def make_layout_t(body_t: Template) -> Template:
 </html>
 '''
 
+def test_render_template_components_cinfo_smoketest():
+
+    def PageComponent(embedded_template=None):
+        return t'''<div class="content">{embedded_template}</div>'''
+
+    def FooterComponent():
+        return t'<div class="footer"><a href="about">About</a></div>'
+
+    def LayoutComponent(embedded_template=None):
+        assert embedded_template
+        return t'''<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <script src="scripts.js"></script>
+    <link rel="stylesheet" href="styles.css">
+  </head>
+  <body>{embedded_template}<{FooterComponent:cinfo} /></body>
+</html>
+'''
+
+    render_api = render_service_factory()
+    content = 'HTML never goes out of style.'
+    content_str = render_api.render_template(t'<{LayoutComponent:cinfo}><{PageComponent:cinfo}>{content}</{PageComponent:cinfo}></{LayoutComponent:cinfo}>')
+    assert content_str == '''<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <script src="scripts.js"></script>
+    <link rel="stylesheet" href="styles.css">
+  </head>
+  <body><div class="content">HTML never goes out of style.</div><div class="footer"><a href="about">About</a></div></body>
+</html>
+'''

From 7c93227c2a8e48354ad9ce256e3633d647c7e036 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sat, 3 Jan 2026 22:34:09 -0800
Subject: [PATCH 21/81] Type checking fixes.

---
 tdom/transformer_test.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 05770b2..9d64a70 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -1,7 +1,10 @@
-from .transformer import render_service_factory, cached_render_service_factory, CachedTransformService
 from contextvars import ContextVar
 from string.templatelib import Template
 from markupsafe import Markup
+import typing as t
+
+from .transformer import render_service_factory, cached_render_service_factory, CachedTransformService
+
 
 theme_context_var = ContextVar('theme', default='default')
 
@@ -67,7 +70,8 @@ def test_process_template_internal_cache():
     assert cached_tnode1 is cached_tnode3
     assert struct_repr(tnode1) == struct_repr(cached_tnode1)
     assert struct_repr(tnode2) == struct_repr(cached_tnode1)
-    # @TODO: Maybe we should be acting directly on the transform service here?
+    # Technically this could be the superclass which doesn't have cached method.
+    assert isinstance(cached_render_api.transform_api, CachedTransformService)
     ci = cached_render_api.transform_api._transform_template.cache_info()
     assert ci.hits == 2, "lookup #2 and lookup #3"
     assert ci.misses == 1, "lookup #1"
@@ -104,7 +108,7 @@ def get_select_t_with_concat(options, selected_values):
         parts.append(t'</select>')
         return sum(parts, t"")
 
-    def get_color_select_t(selected_values: set, provider: Callable) -> Template:
+    def get_color_select_t(selected_values: set, provider: t.Callable) -> Template:
         PRIMARY_COLORS = [("R", "Red"), ("Y", "Yellow"), ("B", "Blue")]
         assert set(selected_values).issubset(set([opt[0] for opt in PRIMARY_COLORS]))
         return provider(PRIMARY_COLORS, selected_values)

From b93c4d74502b8eeee057688975f9d57dfc5f588c Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sat, 3 Jan 2026 22:34:48 -0800
Subject: [PATCH 22/81] Cleanup attr handling names.

---
 tdom/transformer.py | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index f6c3c3f..a7cd66a 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -31,7 +31,7 @@
     escape_html_comment as default_escape_html_comment,
     )
 from .utils import CachableTemplate
-from .processor import _resolve_t_attrs, AttributesDict, _resolve_html_attrs, _kebab_to_snake
+from .processor import _resolve_t_attrs, AttributesDict, _resolve_html_attrs as coerce_to_html_attrs, _kebab_to_snake
 from .callables import get_callable_info
 
 
@@ -84,8 +84,8 @@ def interpolate_comment(render_api, q, bf, last_container_tag, template, ip_info
 
 def interpolate_attrs(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, attrs = ip_info
-    html_attrs = render_api.interpolate_attrs(attrs, template)
-    attrs_str = render_html_attrs(_resolve_html_attrs(html_attrs))
+    resolved_attrs = render_api.resolve_attrs(attrs, template)
+    attrs_str = render_html_attrs(coerce_to_html_attrs(resolved_attrs))
     bf.append(attrs_str)
 
 
@@ -162,7 +162,7 @@ def interpolate_component(render_api, q, bf, last_container_tag, template, ip_in
     else:
         embedded_template = Template('')
     embedded_struct_t = render_api.process_template(embedded_template)
-    attrs = render_api.interpolate_attrs(attrs, template)
+    resolved_attrs = render_api.resolve_attrs(attrs, template)
     start_i = template.interpolations[start_i_index]
     component_callable = start_i.value
     if start_i_index != end_i_index and end_i_index is not None and component_callable != template.interpolations[end_i_index].value:
@@ -179,7 +179,7 @@ def interpolate_component(render_api, q, bf, last_container_tag, template, ip_in
         invoke_strat = invoke_cinfo_cvalues
     else:
         raise ValueError(f'Unknown format spec: {start_i.format_spec}')
-    result_template, context_values = invoke_strat(component_callable, attrs, embedded_template, embedded_struct_t)
+    result_template, context_values = invoke_strat(component_callable, resolved_attrs, embedded_template, embedded_struct_t)
     if result_template:
         result_struct = render_api.process_template(result_template)
         if context_values:
@@ -325,7 +325,7 @@ def streamer(self, root: TNode, last_container_tag: str|None=None) -> t.Iterable
                     if self.has_dynamic_attrs(attrs):
                         yield self._stream_attrs_interpolation(tag, attrs)
                     else:
-                        yield render_html_attrs(_resolve_html_attrs(_resolve_t_attrs(attrs, interpolations=())))
+                        yield render_html_attrs(coerce_to_html_attrs(_resolve_t_attrs(attrs, interpolations=())))
                     # This is just a want to have.
                     if self.slash_void and tag in VOID_ELEMENTS:
                         yield ' />'
@@ -462,8 +462,12 @@ def process_template(self, template):
         """ This is just a wrap-point for caching. """
         return self.transform_api.transform_template(template)
 
-    def interpolate_attrs(self, attrs, template) -> AttributesDict:
-        """ Plug `template` values into any attribute interpolations. """
+    def resolve_attrs(self, attrs, template) -> AttributesDict:
+        """
+        - interpolate interpolations
+        - perform special attribute handling
+        - merge
+        """
         return _resolve_t_attrs(attrs, template.interpolations)
 
     def walk_template_with_context(self, bf, template, struct_t, context_values=None):

From f273e943b19d96baf9b1c2a9c7c5778126721907 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sat, 3 Jan 2026 23:04:39 -0800
Subject: [PATCH 23/81] Add in a few explainations.

---
 tdom/transformer.py | 40 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index a7cd66a..0a3f32b 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -359,10 +359,27 @@ def has_dynamic_attrs(self, attrs: t.Sequence[TAttribute]) -> bool:
                 return True
         return False
 
-    def extract_embedded_template(self, template: Template, body_start_s_index: int, end_i_index: int):
+    def extract_embedded_template(self, template: Template, body_start_s_index: int, end_i_index: int) -> Template:
         """
         Extract the template parts exclusively from start tag to end tag.
 
+        Note that interpolations INSIDE the start tag make this more complex
+        than just "the `s_index` after the component callable's `i_index`".
+
+        Example:
+        ```python
+        template = (
+            t'<{comp} attr={attr}>'
+                t'<div>{content} <span>{footer}</span></div>'
+            t'</{comp}>'
+        )
+        assert self.extract_embedded_template(template, 2, 4) == (
+            t'<div>{content} <span>{footer}</span></div>'
+        )
+        starttag = t'<{comp} attr={attr}>'
+        endtag = t'</{comp}>'
+        assert template == starttag + self.extract_embedded_template(template, 2, 4) + endtag
+        ```
         @TODO: "There must be a better way."
         """
         # Copy the parts out of the containing template.
@@ -421,6 +438,14 @@ def render_template(self, template, last_container_tag=None) -> str:
         return ''.join(bf)
 
     def resolve_text_without_recursion(self, template, container_tag, content_t) -> str:
+        """
+        Resolve the text in the given template without recursing into more structured text.
+
+        This can be bypassed by interpolating an exact match with an object with `__html__()`.
+
+        A non-exact match is not allowed because we cannot process escaping
+        across the boundary between other content and the pass-through content.
+        """
         parts = list(content_t)
         exact = len(parts) == 1 and len(content_t.interpolations) == 1
         if exact:
@@ -495,7 +520,16 @@ def walk_template(self, bf, template, struct_t):
 
 
 class ContextVarSetter:
-    context_values: tuple[tuple[ContextVar, object],...]
+    """
+    Context manager for working with many context vars (instead of only 1).
+
+    This is meant to be created, used immediately and then discarded.
+
+    This allows for dynamically specifying a tuple of var / value pairs that
+    another part of the program can use to wrap some called code without knowing
+    anything about either.
+    """
+    context_values: tuple[tuple[ContextVar, object],...] # Cvar / value pair.
     tokens: tuple[Token,...]
 
     def __init__(self, context_values=()):
@@ -503,9 +537,11 @@ def __init__(self, context_values=()):
         self.tokens = ()
 
     def __enter__(self):
+        """ Set every given context var to its paired value. """
         self.tokens = tuple([var.set(val) for var, val in self.context_values])
 
     def __exit__(self, exc_type, exc_value, traceback):
+        """ Reset every given context var. """
         for idx, var_value in enumerate(self.context_values):
             var_value[0].reset(self.tokens[idx])
 

From cdf531b237b58a3c14c6dc4161a42a015b634a44 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Tue, 13 Jan 2026 00:11:28 -0800
Subject: [PATCH 24/81] Use clearer name.

---
 tdom/transformer.py | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 0a3f32b..1815868 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -31,7 +31,12 @@
     escape_html_comment as default_escape_html_comment,
     )
 from .utils import CachableTemplate
-from .processor import _resolve_t_attrs, AttributesDict, _resolve_html_attrs as coerce_to_html_attrs, _kebab_to_snake
+from .processor import (
+    _resolve_t_attrs as resolve_dynamic_attrs,
+    AttributesDict,
+    _resolve_html_attrs as coerce_to_html_attrs,
+    _kebab_to_snake,
+)
 from .callables import get_callable_info
 
 
@@ -325,7 +330,7 @@ def streamer(self, root: TNode, last_container_tag: str|None=None) -> t.Iterable
                     if self.has_dynamic_attrs(attrs):
                         yield self._stream_attrs_interpolation(tag, attrs)
                     else:
-                        yield render_html_attrs(coerce_to_html_attrs(_resolve_t_attrs(attrs, interpolations=())))
+                        yield render_html_attrs(coerce_to_html_attrs(resolve_dynamic_attrs(attrs, interpolations=())))
                     # This is just a want to have.
                     if self.slash_void and tag in VOID_ELEMENTS:
                         yield ' />'
@@ -493,7 +498,7 @@ def resolve_attrs(self, attrs, template) -> AttributesDict:
         - perform special attribute handling
         - merge
         """
-        return _resolve_t_attrs(attrs, template.interpolations)
+        return resolve_dynamic_attrs(attrs, template.interpolations)
 
     def walk_template_with_context(self, bf, template, struct_t, context_values=None):
         if context_values:

From dc8b381f3060926418dc0f9249a460a849ab2db9 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Tue, 13 Jan 2026 23:49:45 -0800
Subject: [PATCH 25/81] Try to push API in the direction of tdom's node api.

---
 tdom/transformer.py | 86 +++++++++++++++++++++------------------------
 1 file changed, 41 insertions(+), 45 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 1815868..785d26a 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -94,18 +94,8 @@ def interpolate_attrs(render_api, q, bf, last_container_tag, template, ip_info)
     bf.append(attrs_str)
 
 
-def invoke_passthru(component_callable, attrs, embedded_template, embedded_struct_t):
-    result_template = component_callable(attrs, embedded_template, embedded_struct_t)
-    return result_template, ()
-
-
-def invoke_passthru_cvalues(component_callable, attrs, embedded_template, embedded_struct_t):
-    result_template, context_values = component_callable(attrs, embedded_template, embedded_struct_t)
-    return result_template, context_values
-
-
-def _prep_cinfo(component_callable, attrs, embedded_template, embedded_struct_t):
-    # @TODO: This is lifted from the processor and then grossified.
+def _prep_cinfo(component_callable, attrs, system):
+    # @DESIGN: This is lifted from the processor and then grossified.
     # Not sure this will work out but maybe we'd unify these.
     callable_info = get_callable_info(component_callable)
 
@@ -116,38 +106,30 @@ def _prep_cinfo(component_callable, attrs, embedded_template, embedded_struct_t)
 
     kwargs: AttributesDict = {}
 
-    # Add all supported attributes
+    # Inject system kwargs first.
+    if system:
+        if callable_info.kwargs:
+            kwargs.update(system)
+        else:
+            for kw in system:
+                if kw in callable_info.named_params:
+                    kwargs[kw] = system[kw]
+
+    # Plaster attributes in over top of system kwargs.
     for attr_name, attr_value in attrs.items():
         snake_name = _kebab_to_snake(attr_name)
         if snake_name in callable_info.named_params or callable_info.kwargs:
             kwargs[snake_name] = attr_value
 
-    # Add system vars if appropriate
-    if "embedded_template" in callable_info.named_params or callable_info.kwargs:
-        kwargs["embedded_template"] = embedded_template
-    # I'm sure the phone is ringing of the hook for this one.
-    if "embedded_struct_t" in callable_info.named_params or callable_info.kwargs:
-        kwargs["embedded_struct_t"] = embedded_struct_t
-
     # Check to make sure we've fully satisfied the callable's requirements
     missing = callable_info.required_named_params - kwargs.keys()
     if missing:
         raise TypeError(
             f"Missing required parameters for component: {', '.join(missing)}"
         )
-    return kwargs
 
-
-def invoke_cinfo(component_callable, attrs, embedded_template, embedded_struct_t):
-    kwargs = _prep_cinfo(component_callable, attrs, embedded_template, embedded_struct_t)
-    result = component_callable(**kwargs)
-    return result, ()
-
-
-def invoke_cinfo_cvalues(component_callable, attrs, embedded_template, embedded_struct_t):
-    kwargs = _prep_cinfo(component_callable, attrs, embedded_template, embedded_struct_t)
-    result, context_values = component_callable(**kwargs)
-    return result, context_values
+    expect_cvalues = (not callable_info.return_is_undefined) and (callable_info.return_origin is not Template)
+    return kwargs, expect_cvalues
 
 
 def interpolate_component(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
@@ -163,6 +145,7 @@ def interpolate_component(render_api, q, bf, last_container_tag, template, ip_in
     """
     (container_tag, attrs, start_i_index, end_i_index, body_start_s_index) = ip_info
     if start_i_index != end_i_index and end_i_index is not None:
+        # @DESIGN: We extract the embedded template from the original outer template.
         embedded_template = render_api.transform_api.extract_embedded_template(template, body_start_s_index, end_i_index)
     else:
         embedded_template = Template('')
@@ -173,18 +156,23 @@ def interpolate_component(render_api, q, bf, last_container_tag, template, ip_in
     if start_i_index != end_i_index and end_i_index is not None and component_callable != template.interpolations[end_i_index].value:
         raise TypeError('Component callable in start tag must match component callable in end tag.')
 
-    # @TODO: Amazingly this works!  It looks terrible though! Maybe we'll keep pushing symbols around...
-    if start_i.format_spec == '' or start_i.format_spec == 'passthru':
-        invoke_strat = invoke_passthru
-    elif start_i.format_spec == 'passthru+cvalues':
-        invoke_strat = invoke_passthru_cvalues
-    elif start_i.format_spec == 'cinfo':
-        invoke_strat = invoke_cinfo
-    elif start_i.format_spec == 'cinfo+cvalues':
-        invoke_strat = invoke_cinfo_cvalues
+    # @DESIGN: Inject system vars via manager?
+    system_dict = render_api.get_system(children=embedded_template, children_struct=embedded_struct_t)
+    # @DESIGN: Determine return signature from callable info (cached inspection) ?
+    kwargs, expect_cvalues = _prep_cinfo(component_callable, resolved_attrs, system_dict)
+    res = component_callable(**kwargs)
+    # @DESIGN: Determine return signature via runtime inspection?
+    if isinstance(res, tuple):
+        result_template, comp_info = res
+        context_values = comp_info.get('context_values', ()) if comp_info else ()
     else:
-        raise ValueError(f'Unknown format spec: {start_i.format_spec}')
-    result_template, context_values = invoke_strat(component_callable, resolved_attrs, embedded_template, embedded_struct_t)
+        result_template = res
+        comp_info = None
+        context_values = ()
+
+    # @DESIGN: Use open-ended dict for opt-in second return argument?
+    context_values = comp_info.get('context_values', ()) if comp_info else ()
+
     if result_template:
         result_struct = render_api.process_template(result_template)
         if context_values:
@@ -330,8 +318,10 @@ def streamer(self, root: TNode, last_container_tag: str|None=None) -> t.Iterable
                     if self.has_dynamic_attrs(attrs):
                         yield self._stream_attrs_interpolation(tag, attrs)
                     else:
+                        # @DESIGN: We can't customize the html attrs rendering here because we are not even
+                        # in the RENDERER!
                         yield render_html_attrs(coerce_to_html_attrs(resolve_dynamic_attrs(attrs, interpolations=())))
-                    # This is just a want to have.
+                    # @DESIGN: This is just a want to have.
                     if self.slash_void and tag in VOID_ELEMENTS:
                         yield ' />'
                     else:
@@ -385,7 +375,7 @@ def extract_embedded_template(self, template: Template, body_start_s_index: int,
         endtag = t'</{comp}>'
         assert template == starttag + self.extract_embedded_template(template, 2, 4) + endtag
         ```
-        @TODO: "There must be a better way."
+        @DESIGN: "There must be a better way."
         """
         # Copy the parts out of the containing template.
         index = body_start_s_index
@@ -414,6 +404,9 @@ class RenderService:
 
     escape_html_content_in_tag: Callable = default_escape_html_content_in_tag
 
+    def get_system(self, children, children_struct):
+        return {'children': children, 'children_struct': children_struct}
+
     def render_template(self, template, last_container_tag=None) -> str:
         """
         Iterate left to right and pause and push new iterators when descending depth-first.
@@ -426,6 +419,8 @@ def render_template(self, template, last_container_tag=None) -> str:
         text processing.  When working with fragments we might not know the
         container tag until the fragment is included at render-time.
         """
+        # @DESIGN: We put all the strings in a list and then ''.join them at
+        # the end.
         bf: list[str] = []
         q: list[RenderQueueItem] = []
         q.append((last_container_tag, self.walk_template(bf, template, self.process_template(template))))
@@ -572,3 +567,4 @@ def _transform_template(self, cached_template: CachableTemplate) -> Template:
     def transform_template(self, values_template: Template) -> Template:
         ct = CachableTemplate(values_template)
         return self._transform_template(ct)
+

From b7f2a1357b6bad9bcac0021b35c17a9545c3b7cb Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Wed, 14 Jan 2026 21:21:51 -0800
Subject: [PATCH 26/81] Actually use the escape function.

---
 tdom/transformer.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 785d26a..f565204 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -46,7 +46,7 @@ class EndTag:
 
 
 def render_html_attrs(html_attrs: HTMLAttributesDict, escape: Callable = default_escape_html_text) -> str:
-    return ''.join((f' {k}="{v}"' if v is not None else f' {k}' for k, v in html_attrs.items()))
+    return ''.join((f' {k}="{escape(v)}"' if v is not None else f' {k}' for k, v in html_attrs.items()))
 
 
 class Interpolator(t.Protocol):

From 4ff937e7316bc4c2f11f637b0145d36e74d020e6 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Wed, 14 Jan 2026 21:22:10 -0800
Subject: [PATCH 27/81] Use call info style.

---
 tdom/transformer_test.py | 42 +++++++++++++++++++---------------------
 1 file changed, 20 insertions(+), 22 deletions(-)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 9d64a70..f6b9a1b 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -16,8 +16,8 @@ def test_render_template_smoketest():
     templated = "not literal"
     spread_attrs={'data-on': True}
     markup_content = Markup('<div>safe</div>')
-    def comp(attrs, body_t, body_struct):
-        return t'<div>{body_t}</div>'
+    def comp(children):
+        return t'<div>{children}</div>'
     smoke_t = t'''<!doctype html>
 <html>
 <body>
@@ -120,16 +120,15 @@ def get_color_select_t(selected_values: set, provider: t.Callable) -> Template:
 
 def test_render_component_with_context():
 
-    def ThemeContext(attrs, embedded_t, embedded_struct):
-        context_values = ((theme_context_var, attrs.get('value', 'normal')),)
-        return embedded_t, context_values
+    def ThemeContext(theme, children):
+        return children, {'context_values': ((theme_context_var, theme),)}
 
-    def ThemedDiv(attrs, embedded_t, embedded_struct):
+    def ThemedDiv(children):
         theme = theme_context_var.get()
-        return t'<div data-theme="{theme}">{embedded_t}</div>'
+        return t'<div data-theme="{theme}">{children}</div>'
 
     render_api = render_service_factory()
-    body_t = t"<div><{ThemeContext:passthru+cvalues} value='holiday'><{ThemedDiv}><b>Cheers!</b></{ThemedDiv}></{ThemeContext}></div>"
+    body_t = t"<div><{ThemeContext} theme='holiday'><{ThemedDiv}><b>Cheers!</b></{ThemedDiv}></{ThemeContext}></div>"
     with theme_context_var.set('not-the-default'):
         assert render_api.render_template(body_t) == '<div><div data-theme="holiday"><b>Cheers!</b></div></div>'
         assert theme_context_var.get() == 'not-the-default'
@@ -138,13 +137,13 @@ def ThemedDiv(attrs, embedded_t, embedded_struct):
 
 def test_render_template_components_smoketest():
 
-    def PageComponent(attrs, content_t, content_struct):
-        return t'''<div class="content">{content_t}</div>'''
+    def PageComponent(children):
+        return t'''<div class="content">{children}</div>'''
 
-    def FooterComponent(attrs, body_t, body_struct):
+    def FooterComponent():
         return t'<div class="footer"><a href="about">About</a></div>'
 
-    def LayoutComponent(attrs, body_t, body_struct):
+    def LayoutComponent(children):
         return t'''<!doctype html>
 <html>
   <head>
@@ -152,7 +151,7 @@ def LayoutComponent(attrs, body_t, body_struct):
     <script src="scripts.js"></script>
     <link rel="stylesheet" href="styles.css">
   </head>
-  <body>{body_t}<{FooterComponent} /></body>
+  <body>{children}<{FooterComponent} /></body>
 </html>
 '''
 
@@ -179,7 +178,7 @@ def make_page_t(content: str) -> Template:
     def make_footer_t() -> Template:
         return t'<div class="footer"><a href="about">About</a></div>'
 
-    def make_layout_t(body_t: Template) -> Template:
+    def make_layout_t(children) -> Template:
         footer_t = make_footer_t()
         return t'''<!doctype html>
 <html>
@@ -188,7 +187,7 @@ def make_layout_t(body_t: Template) -> Template:
     <script src="scripts.js"></script>
     <link rel="stylesheet" href="styles.css">
   </head>
-  <body>{body_t}{footer_t}</body>
+  <body>{children}{footer_t}</body>
 </html>
 '''
 
@@ -207,16 +206,15 @@ def make_layout_t(body_t: Template) -> Template:
 </html>
 '''
 
-def test_render_template_components_cinfo_smoketest():
+def test_render_template_components_smoketest():
 
-    def PageComponent(embedded_template=None):
-        return t'''<div class="content">{embedded_template}</div>'''
+    def PageComponent(children):
+        return t'''<div class="content">{children}</div>'''
 
     def FooterComponent():
         return t'<div class="footer"><a href="about">About</a></div>'
 
-    def LayoutComponent(embedded_template=None):
-        assert embedded_template
+    def LayoutComponent(children):
         return t'''<!doctype html>
 <html>
   <head>
@@ -224,13 +222,13 @@ def LayoutComponent(embedded_template=None):
     <script src="scripts.js"></script>
     <link rel="stylesheet" href="styles.css">
   </head>
-  <body>{embedded_template}<{FooterComponent:cinfo} /></body>
+  <body>{children}<{FooterComponent} /></body>
 </html>
 '''
 
     render_api = render_service_factory()
     content = 'HTML never goes out of style.'
-    content_str = render_api.render_template(t'<{LayoutComponent:cinfo}><{PageComponent:cinfo}>{content}</{PageComponent:cinfo}></{LayoutComponent:cinfo}>')
+    content_str = render_api.render_template(t'<{LayoutComponent}><{PageComponent}>{content}</{PageComponent}></{LayoutComponent}>')
     assert content_str == '''<!doctype html>
 <html>
   <head>

From 216bfc091c1e3339e7940ee5c3e0a82f366923e1 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Wed, 14 Jan 2026 21:31:10 -0800
Subject: [PATCH 28/81] Stop using cinfo to determine if context values will be
 returned.

---
 tdom/transformer.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index f565204..7a83690 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -128,8 +128,7 @@ def _prep_cinfo(component_callable, attrs, system):
             f"Missing required parameters for component: {', '.join(missing)}"
         )
 
-    expect_cvalues = (not callable_info.return_is_undefined) and (callable_info.return_origin is not Template)
-    return kwargs, expect_cvalues
+    return kwargs
 
 
 def interpolate_component(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
@@ -159,7 +158,7 @@ def interpolate_component(render_api, q, bf, last_container_tag, template, ip_in
     # @DESIGN: Inject system vars via manager?
     system_dict = render_api.get_system(children=embedded_template, children_struct=embedded_struct_t)
     # @DESIGN: Determine return signature from callable info (cached inspection) ?
-    kwargs, expect_cvalues = _prep_cinfo(component_callable, resolved_attrs, system_dict)
+    kwargs = _prep_cinfo(component_callable, resolved_attrs, system_dict)
     res = component_callable(**kwargs)
     # @DESIGN: Determine return signature via runtime inspection?
     if isinstance(res, tuple):

From f83e63b24e4a93fe733eb84a05bcc82119bb771c Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Wed, 14 Jan 2026 22:39:01 -0800
Subject: [PATCH 29/81] Match other calls.

---
 tdom/transformer.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 7a83690..8aa8b29 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -181,8 +181,8 @@ def interpolate_component(render_api, q, bf, last_container_tag, template, ip_in
         return (container_tag, iter(walker))
 
 
-def interpolate_raw_text(render_api, q, bf, last_container_tag, template, value) -> RenderQueueItem | None:
-    container_tag, content_t = value
+def interpolate_raw_text(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+    container_tag, content_t = ip_info
     bf.append(render_api.escape_html_content_in_tag(container_tag, render_api.resolve_text_without_recursion(template, container_tag, content_t)))
 
 

From 620bcf2fe3f4e4f155e1c108719bfb9eac227ea8 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Wed, 14 Jan 2026 23:59:51 -0800
Subject: [PATCH 30/81] Add more comments to tests and make more idiomatic with
 processor.

---
 tdom/transformer_test.py | 142 ++++++++++++++++++++-------------------
 1 file changed, 73 insertions(+), 69 deletions(-)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index f6b9a1b..eedfca7 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -6,7 +6,7 @@
 from .transformer import render_service_factory, cached_render_service_factory, CachedTransformService
 
 
-theme_context_var = ContextVar('theme', default='default')
+THEME_CTX = ContextVar('theme', default='default')
 
 
 def test_render_template_smoketest():
@@ -16,7 +16,7 @@ def test_render_template_smoketest():
     templated = "not literal"
     spread_attrs={'data-on': True}
     markup_content = Markup('<div>safe</div>')
-    def comp(children):
+    def WrapperComponent(children):
         return t'<div>{children}</div>'
     smoke_t = t'''<!doctype html>
 <html>
@@ -26,7 +26,7 @@ def comp(children):
 <!-- {comment_text} -->
 <span>{text_in_element}</span>
 <span attr="literal" class={interpolated_class} title="is {templated}" {spread_attrs}>{text_in_element}</span>
-<{comp}><span>comp body</span></{comp}>
+<{WrapperComponent}><span>comp body</span></{WrapperComponent}>
 {markup_content}
 </body>
 </html>'''
@@ -47,40 +47,56 @@ def comp(children):
 
 
 def struct_repr(st):
+    """ Breakdown Templates into comparable parts for test verification. """
     return st.strings, tuple([(i.value, i.expression, i.conversion, i.format_spec) for i in st.interpolations])
 
 
 def test_process_template_internal_cache():
+    """ Test that cache and non-cache both generally work as expected. """
     sample_t = t'''<div>{'content'}</div>'''
     sample_diff_t = t'''<div>{'diffcontent'}</div>'''
     alt_t = t'''<span>{'content'}</span>'''
     render_api = render_service_factory()
     cached_render_api = cached_render_service_factory()
-    #CachedTransformService
     tnode1 = render_api.process_template(sample_t)
     tnode2 = render_api.process_template(sample_t)
     cached_tnode1 = cached_render_api.process_template(sample_t)
     cached_tnode2 = cached_render_api.process_template(sample_t)
     cached_tnode3 = cached_render_api.process_template(sample_diff_t)
+    # Check that the uncached and cached services are actually
+    # returning non-identical results.
     assert tnode1 is not cached_tnode1
     assert tnode1 is not cached_tnode2
     assert tnode1 is not cached_tnode3
+    # Check that the uncached service returns a brand new result everytime.
     assert tnode1 is not tnode2
+    # Check that the cached service is returning the exact same, identical, result.
     assert cached_tnode1 is cached_tnode2
-    assert cached_tnode1 is cached_tnode3
+    # Even if the input templates are not identical (but are still equivalent).
+    assert cached_tnode1 is cached_tnode3 and sample_t is not sample_diff_t
+    # Check that the cached service and uncached services return
+    # results that are equivalent (even though they are not (id)entical).
     assert struct_repr(tnode1) == struct_repr(cached_tnode1)
     assert struct_repr(tnode2) == struct_repr(cached_tnode1)
     # Technically this could be the superclass which doesn't have cached method.
     assert isinstance(cached_render_api.transform_api, CachedTransformService)
+    # Now that we are setup we check that the cache is internally
+    # working as we intended.
     ci = cached_render_api.transform_api._transform_template.cache_info()
-    assert ci.hits == 2, "lookup #2 and lookup #3"
-    assert ci.misses == 1, "lookup #1"
+    # cached_tnode2 and cached_tnode3 are hits after cached_tnode1
+    assert ci.hits == 2
+    # cached_tnode1 was a miss because cache was empty (brand new)
+    assert ci.misses == 1
     cached_tnode4 = cached_render_api.process_template(alt_t)
+    # A different template produces a brand new tnode.
     assert cached_tnode1 is not cached_tnode4
+    # The template is new AND has a different structure so it also
+    # produces an unequivalent tnode.
     assert struct_repr(cached_tnode1) != struct_repr(cached_tnode4)
 
 
 def test_render_template_repeated():
+    """ Crude check for any unintended state being kept between calls. """
     def get_sample_t(idx, spread_attrs, button_text):
         return t'''<div><button data-key={idx} {spread_attrs}>{button_text}</button></div>'''
     render_apis = (render_service_factory(), cached_render_service_factory())
@@ -118,32 +134,41 @@ def get_color_select_t(selected_values: set, provider: t.Callable) -> Template:
         assert render_api.render_template(get_color_select_t({'Y'}, provider)) == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'
 
 
-def test_render_component_with_context():
+def test_context_provider_pattern():
+    def ThemeProvider(theme, children):
+        return children, {'context_values': ((THEME_CTX, theme),)}
 
-    def ThemeContext(theme, children):
-        return children, {'context_values': ((theme_context_var, theme),)}
+    def IntermediateWrapper(children):
+        # Wrap in between the provider and consumer just to make sure there
+        # is no direct interaction.
+        return t'<div>{children}</div>'
 
-    def ThemedDiv(children):
-        theme = theme_context_var.get()
-        return t'<div data-theme="{theme}">{children}</div>'
+    def ThemeConsumer(children):
+        theme = THEME_CTX.get()
+        return t'<p data-theme="{theme}">{children}</p>'
 
     render_api = render_service_factory()
-    body_t = t"<div><{ThemeContext} theme='holiday'><{ThemedDiv}><b>Cheers!</b></{ThemedDiv}></{ThemeContext}></div>"
-    with theme_context_var.set('not-the-default'):
-        assert render_api.render_template(body_t) == '<div><div data-theme="holiday"><b>Cheers!</b></div></div>'
-        assert theme_context_var.get() == 'not-the-default'
-    assert theme_context_var.get() == 'default'
+    body_t = t"<body><{ThemeProvider} theme='holiday'><{IntermediateWrapper}><{ThemeConsumer}><b>Cheers!</b></{ThemeConsumer}></{IntermediateWrapper}></{ThemeProvider}></body>"
+    # Set the context var to a different value while rendering
+    # to make sure this value will be masked
+    with THEME_CTX.set('not-the-default'):
+        # During rendering the provider should overlay a new value.
+        assert render_api.render_template(body_t) == '<body><div><p data-theme="holiday"><b>Cheers!</b></p></div></body>'
+        # But afterwards we should be back to the old value.
+        assert THEME_CTX.get() == 'not-the-default'
+    # But after all that we should be back to the context var's offical default.
+    assert THEME_CTX.get() == 'default'
 
 
 def test_render_template_components_smoketest():
+    """ Broadly test that common template component usage works. """
+    def PageComponent(children, root_attrs=None):
+        return t'''<div class="content" {root_attrs}>{children}</div>'''
 
-    def PageComponent(children):
-        return t'''<div class="content">{children}</div>'''
-
-    def FooterComponent():
-        return t'<div class="footer"><a href="about">About</a></div>'
+    def FooterComponent(classes=('footer-default',)):
+        return t'<div class="footer" class={classes}><a href="about">About</a></div>'
 
-    def LayoutComponent(children):
+    def LayoutComponent(children, body_classes=None):
         return t'''<!doctype html>
 <html>
   <head>
@@ -151,13 +176,16 @@ def LayoutComponent(children):
     <script src="scripts.js"></script>
     <link rel="stylesheet" href="styles.css">
   </head>
-  <body>{children}<{FooterComponent} /></body>
+  <body class={body_classes}>
+    {children}
+    <{FooterComponent} />
+  </body>
 </html>
 '''
 
     render_api = render_service_factory()
     content = 'HTML never goes out of style.'
-    content_str = render_api.render_template(t'<{LayoutComponent}><{PageComponent}>{content}</{PageComponent}></{LayoutComponent}>')
+    content_str = render_api.render_template(t'<{LayoutComponent} body_classes={["theme-default"]}><{PageComponent}>{content}</{PageComponent}></{LayoutComponent}>')
     assert content_str == '''<!doctype html>
 <html>
   <head>
@@ -165,20 +193,24 @@ def LayoutComponent(children):
     <script src="scripts.js"></script>
     <link rel="stylesheet" href="styles.css">
   </head>
-  <body><div class="content">HTML never goes out of style.</div><div class="footer"><a href="about">About</a></div></body>
+  <body class="theme-default">
+    <div class="content">HTML never goes out of style.</div>
+    <div class="footer footer-default"><a href="about">About</a></div>
+  </body>
 </html>
 '''
 
 
 def test_render_template_functions_smoketest():
+    """ Broadly test that common template function usage works. """
 
-    def make_page_t(content: str) -> Template:
-        return t'''<div class="content">{content}</div>'''
+    def make_page_t(content, root_attrs=None) -> Template:
+        return t'''<div class="content" {root_attrs}>{content}</div>'''
 
-    def make_footer_t() -> Template:
-        return t'<div class="footer"><a href="about">About</a></div>'
+    def make_footer_t(classes=('footer-default',)) -> Template:
+        return t'<div class="footer" class={classes}><a href="about">About</a></div>'
 
-    def make_layout_t(children) -> Template:
+    def make_layout_t(body_t, body_classes=None) -> Template:
         footer_t = make_footer_t()
         return t'''<!doctype html>
 <html>
@@ -187,13 +219,16 @@ def make_layout_t(children) -> Template:
     <script src="scripts.js"></script>
     <link rel="stylesheet" href="styles.css">
   </head>
-  <body>{children}{footer_t}</body>
+  <body class={body_classes}>
+    {body_t}
+    {footer_t}
+  </body>
 </html>
 '''
 
     render_api = render_service_factory()
     content = 'HTML never goes out of style.'
-    layout_t = make_layout_t(make_page_t(content))
+    layout_t = make_layout_t(make_page_t(content), "theme-default")
     content_str = render_api.render_template(layout_t)
     assert content_str == '''<!doctype html>
 <html>
@@ -202,40 +237,9 @@ def make_layout_t(children) -> Template:
     <script src="scripts.js"></script>
     <link rel="stylesheet" href="styles.css">
   </head>
-  <body><div class="content">HTML never goes out of style.</div><div class="footer"><a href="about">About</a></div></body>
-</html>
-'''
-
-def test_render_template_components_smoketest():
-
-    def PageComponent(children):
-        return t'''<div class="content">{children}</div>'''
-
-    def FooterComponent():
-        return t'<div class="footer"><a href="about">About</a></div>'
-
-    def LayoutComponent(children):
-        return t'''<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <script src="scripts.js"></script>
-    <link rel="stylesheet" href="styles.css">
-  </head>
-  <body>{children}<{FooterComponent} /></body>
-</html>
-'''
-
-    render_api = render_service_factory()
-    content = 'HTML never goes out of style.'
-    content_str = render_api.render_template(t'<{LayoutComponent}><{PageComponent}>{content}</{PageComponent}></{LayoutComponent}>')
-    assert content_str == '''<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <script src="scripts.js"></script>
-    <link rel="stylesheet" href="styles.css">
-  </head>
-  <body><div class="content">HTML never goes out of style.</div><div class="footer"><a href="about">About</a></div></body>
+  <body class="theme-default">
+    <div class="content">HTML never goes out of style.</div>
+    <div class="footer footer-default"><a href="about">About</a></div>
+  </body>
 </html>
 '''

From 166533631b5bd9f482b0cf41554d154107796460 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 15 Jan 2026 00:29:15 -0800
Subject: [PATCH 31/81] Call embedded template a children template to avoid
 confusion.

---
 tdom/transformer.py | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 8aa8b29..fb41ce5 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -133,22 +133,22 @@ def _prep_cinfo(component_callable, attrs, system):
 
 def interpolate_component(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     """
-    - Extract embedded template or use empty template.
-    - Transform embedded template into struct template.
+    - Extract children template or use empty template.
+    - Transform children template into struct template.
     - Resolve attrs but don't stringify.
     - Resolve callable.
-    - Invoke callable with attrs, embedded template, embedded struct template. (no garbage barge? how can we pass the cache?)
+    - Invoke callable with attrs
     - If callable returns a result template then
          * transform it to a struct template
          * iteratively recurse into that result template and start outputting it
     """
     (container_tag, attrs, start_i_index, end_i_index, body_start_s_index) = ip_info
     if start_i_index != end_i_index and end_i_index is not None:
-        # @DESIGN: We extract the embedded template from the original outer template.
-        embedded_template = render_api.transform_api.extract_embedded_template(template, body_start_s_index, end_i_index)
+        # @DESIGN: We extract the children template from the original outer template.
+        children_template = render_api.transform_api.extract_children_template(template, body_start_s_index, end_i_index)
     else:
-        embedded_template = Template('')
-    embedded_struct_t = render_api.process_template(embedded_template)
+        children_template = Template('')
+    children_struct_t = render_api.process_template(children_template)
     resolved_attrs = render_api.resolve_attrs(attrs, template)
     start_i = template.interpolations[start_i_index]
     component_callable = start_i.value
@@ -156,7 +156,7 @@ def interpolate_component(render_api, q, bf, last_container_tag, template, ip_in
         raise TypeError('Component callable in start tag must match component callable in end tag.')
 
     # @DESIGN: Inject system vars via manager?
-    system_dict = render_api.get_system(children=embedded_template, children_struct=embedded_struct_t)
+    system_dict = render_api.get_system(children=children_template, children_struct=children_struct_t)
     # @DESIGN: Determine return signature from callable info (cached inspection) ?
     kwargs = _prep_cinfo(component_callable, resolved_attrs, system_dict)
     res = component_callable(**kwargs)
@@ -353,7 +353,7 @@ def has_dynamic_attrs(self, attrs: t.Sequence[TAttribute]) -> bool:
                 return True
         return False
 
-    def extract_embedded_template(self, template: Template, body_start_s_index: int, end_i_index: int) -> Template:
+    def extract_children_template(self, template: Template, body_start_s_index: int, end_i_index: int) -> Template:
         """
         Extract the template parts exclusively from start tag to end tag.
 
@@ -367,12 +367,12 @@ def extract_embedded_template(self, template: Template, body_start_s_index: int,
                 t'<div>{content} <span>{footer}</span></div>'
             t'</{comp}>'
         )
-        assert self.extract_embedded_template(template, 2, 4) == (
+        assert self.extract_children_template(template, 2, 4) == (
             t'<div>{content} <span>{footer}</span></div>'
         )
         starttag = t'<{comp} attr={attr}>'
         endtag = t'</{comp}>'
-        assert template == starttag + self.extract_embedded_template(template, 2, 4) + endtag
+        assert template == starttag + self.extract_children_template(template, 2, 4) + endtag
         ```
         @DESIGN: "There must be a better way."
         """

From 507457228934c35b2b463c91924aa1097e30e484 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 15 Jan 2026 12:45:25 -0800
Subject: [PATCH 32/81] Fix indent error.

---
 tdom/transformer.py | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index fb41ce5..86237b3 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -469,17 +469,17 @@ def resolve_text_without_recursion(self, template, container_tag, content_t) ->
                 value = template.interpolations[part.value].value
                 if value is None or value is False:
                     continue
-                elif isinstance(value , str):
+                elif isinstance(value, str):
                     if value:
                         text.append(value)
-                    elif isinstance(value, (Template, Iterable)):
-                        raise ValueError(f'Recursive includes are not supported within {container_tag}')
-                    elif hasattr(value, '__html__'):
-                        raise ValueError(f'Non-exact trusted interpolations are not supported within {container_tag}')
-                    else:
-                        value_str = str(value)
-                        if value_str:
-                            text.append(value_str)
+                elif isinstance(value, (Template, Iterable)):
+                    raise ValueError(f'Recursive includes are not supported within {container_tag}')
+                elif hasattr(value, '__html__'):
+                    raise ValueError(f'Non-exact trusted interpolations are not supported within {container_tag}')
+                else:
+                    value_str = str(value)
+                    if value_str:
+                        text.append(value_str)
             return ''.join(text)
 
     def process_template(self, template):

From 4b0ac3f9f82a0391e7c82eb048e6cb012a7f50bf Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 15 Jan 2026 12:59:44 -0800
Subject: [PATCH 33/81] Add some common escape tests.

---
 tdom/transformer_test.py | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index eedfca7..55eaf4f 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -1,7 +1,8 @@
 from contextvars import ContextVar
 from string.templatelib import Template
-from markupsafe import Markup
+from markupsafe import Markup, escape as markupsafe_escape
 import typing as t
+import pytest
 
 from .transformer import render_service_factory, cached_render_service_factory, CachedTransformService
 
@@ -243,3 +244,36 @@ def make_layout_t(body_t, body_classes=None) -> Template:
   </body>
 </html>
 '''
+
+
+def test_text_interpolation_with_dynamic_parent():
+    render_api = render_service_factory()
+    with pytest.raises(ValueError, match='Recursive includes are not supported within script'):
+        content = '<script>console.log("123!");</script>'
+        content_t = t'{content}'
+        _ = render_api.render_template(t'<script>{content_t}</script>')
+
+
+@pytest.mark.skip('Can we allow this?')
+def test_escape_escapable_raw_text_with_dynamic_parent():
+    content = '<script>console.log("123!");</script>'
+    content_t = t'{content}'
+    render_api = render_service_factory()
+    LT, GT, DQ = map(markupsafe_escape, ['<', '>', '"'])
+    assert render_api.render_template(t'<textarea>{content_t}</textarea>') == f'<textarea>{LT}script{GT}console.log({DQ}123!{DQ});{LT}/script{GT}</textarea>'
+
+
+def test_escape_structured_text_with_dynamic_parent():
+    content = '<script>console.log("123!");</script>'
+    content_t = t'{content}'
+    render_api = render_service_factory()
+    LT, GT, DQ = map(markupsafe_escape, ['<', '>', '"'])
+    assert render_api.render_template(t'<div>{content_t}</div>') == f'<div>{LT}script{GT}console.log({DQ}123!{DQ});{LT}/script{GT}</div>'
+
+
+def test_escape_structured_text():
+    content = '<script>console.log("123!");</script>'
+    content_t = t'<div>{content}</div>'
+    render_api = render_service_factory()
+    LT, GT, DQ = map(markupsafe_escape, ['<', '>', '"'])
+    assert render_api.render_template(content_t) == f'<div>{LT}script{GT}console.log({DQ}123!{DQ});{LT}/script{GT}</div>'

From 3932447887160080fd428b48e8628a7a8f956cad Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 15 Jan 2026 13:05:59 -0800
Subject: [PATCH 34/81] After switching from yield it seems we don't need to
 haul around the q arg anymore.

---
 tdom/transformer.py | 26 ++++++++++++--------------
 1 file changed, 12 insertions(+), 14 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 86237b3..b6dbaf6 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -51,15 +51,13 @@ def render_html_attrs(html_attrs: HTMLAttributesDict, escape: Callable = default
 
 class Interpolator(t.Protocol):
 
-    def __call__(self, render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+    def __call__(self, render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
         """
         Populates an interpolation or returns iterator to decende into.
 
         If recursion is required then pushes current iterator
         render_api
             The current render api, provides various helper methods to the interpolator.
-        q
-            A list-like queue of iterators paired with the container tag the results are in.
         bf
             A list-like output buffer.
         last_container_tag
@@ -81,13 +79,13 @@ def __call__(self, render_api, q, bf, last_container_tag, template, ip_info) ->
 type RenderQueueItem = tuple[str | None, Iterable[tuple[Interpolator, Template, InterpolationInfo]]]
 
 
-def interpolate_comment(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_comment(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, comment_t = ip_info
     assert container_tag == '<!--'
     bf.append(render_api.escape_html_comment(render_api.resolve_text_without_recursion(template, container_tag, comment_t)))
 
 
-def interpolate_attrs(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_attrs(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, attrs = ip_info
     resolved_attrs = render_api.resolve_attrs(attrs, template)
     attrs_str = render_html_attrs(coerce_to_html_attrs(resolved_attrs))
@@ -131,7 +129,7 @@ def _prep_cinfo(component_callable, attrs, system):
     return kwargs
 
 
-def interpolate_component(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_component(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     """
     - Extract children template or use empty template.
     - Transform children template into struct template.
@@ -181,17 +179,17 @@ def interpolate_component(render_api, q, bf, last_container_tag, template, ip_in
         return (container_tag, iter(walker))
 
 
-def interpolate_raw_text(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_raw_text(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, content_t = ip_info
     bf.append(render_api.escape_html_content_in_tag(container_tag, render_api.resolve_text_without_recursion(template, container_tag, content_t)))
 
 
-def interpolate_escapable_raw_text(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_escapable_raw_text(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, content_t = ip_info
     bf.append(render_api.escape_html_text(render_api.resolve_text_without_recursion(template, container_tag, content_t)))
 
 
-def interpolate_struct_text(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_struct_text(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, ip_index = ip_info
     # @TODO: We just completely ignore any conversion or format_spec here.
     # This is actually a much larger problem/decision of how can a user give us more information about what to do
@@ -201,14 +199,14 @@ def interpolate_struct_text(render_api, q, bf, last_container_tag, template, ip_
     #   - The 4th interpolation will be an iterator of html-aware Template strings
     #   - The 5th interpolation will be an iterator of strings to render and escape.
     value = template.interpolations[ip_index].value # data provided to a parsed t-string
-    return interpolate_text(render_api, q, bf, last_container_tag, template, (container_tag, value))
+    return interpolate_text(render_api, bf, last_container_tag, template, (container_tag, value))
 
 
-def interpolate_user_text(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
-    return interpolate_text(render_api, q, bf, last_container_tag, template, ip_info)
+def interpolate_user_text(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+    return interpolate_text(render_api, bf, last_container_tag, template, ip_info)
 
 
-def interpolate_text(render_api, q, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_text(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
     container_tag, value = ip_info
     if container_tag is None:
         container_tag = last_container_tag
@@ -426,7 +424,7 @@ def render_template(self, template, last_container_tag=None) -> str:
         while q:
             last_container_tag, it = q.pop()
             for (interpolator, template, ip_info) in it:
-                render_queue_item = interpolator(self, q, bf, last_container_tag, template, ip_info)
+                render_queue_item = interpolator(self, bf, last_container_tag, template, ip_info)
                 if render_queue_item is not None:
                     #
                     # Pause the current iterator and push a new iterator on top of it.

From 9d5bc1262e7f11ed71b3b597e96355e1a1ee3f91 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 15 Jan 2026 13:06:11 -0800
Subject: [PATCH 35/81] Formatting.

---
 tdom/escaping.py         |   6 +-
 tdom/transformer.py      | 321 ++++++++++++++++++++++++++++-----------
 tdom/transformer_test.py | 205 ++++++++++++++++---------
 3 files changed, 368 insertions(+), 164 deletions(-)

diff --git a/tdom/escaping.py b/tdom/escaping.py
index 915e5b8..2792873 100644
--- a/tdom/escaping.py
+++ b/tdom/escaping.py
@@ -82,11 +82,11 @@ def escape_html_script(text: str) -> str:
 
 def escape_html_content_in_tag(parent_tag, content):
     parent_tag = parent_tag.lower()
-    if parent_tag == 'script':
+    if parent_tag == "script":
         return escape_html_script(content)
-    elif parent_tag == '<!--':
+    elif parent_tag == "<!--":
         return escape_html_comment(content)
-    elif parent_tag == 'style':
+    elif parent_tag == "style":
         LT = "&lt;"
         close_str = f"</{parent_tag}>"
         # @TODO: This whole escaping business is probably be misguided... but we should cache this.
diff --git a/tdom/transformer.py b/tdom/transformer.py
index b6dbaf6..ff332db 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -24,12 +24,12 @@
     VOID_ELEMENTS,
     CDATA_CONTENT_ELEMENTS,
     RCDATA_CONTENT_ELEMENTS,
-    )
+)
 from .escaping import (
     escape_html_content_in_tag as default_escape_html_content_in_tag,
     escape_html_text as default_escape_html_text,
     escape_html_comment as default_escape_html_comment,
-    )
+)
 from .utils import CachableTemplate
 from .processor import (
     _resolve_t_attrs as resolve_dynamic_attrs,
@@ -45,13 +45,21 @@ class EndTag:
     end_tag: str
 
 
-def render_html_attrs(html_attrs: HTMLAttributesDict, escape: Callable = default_escape_html_text) -> str:
-    return ''.join((f' {k}="{escape(v)}"' if v is not None else f' {k}' for k, v in html_attrs.items()))
+def render_html_attrs(
+    html_attrs: HTMLAttributesDict, escape: Callable = default_escape_html_text
+) -> str:
+    return "".join(
+        (
+            f' {k}="{escape(v)}"' if v is not None else f" {k}"
+            for k, v in html_attrs.items()
+        )
+    )
 
 
 class Interpolator(t.Protocol):
-
-    def __call__(self, render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+    def __call__(
+        self, render_api, bf, last_container_tag, template, ip_info
+    ) -> RenderQueueItem | None:
         """
         Populates an interpolation or returns iterator to decende into.
 
@@ -76,16 +84,28 @@ def __call__(self, render_api, bf, last_container_tag, template, ip_info) -> Ren
 type InterpolationInfo = object | None
 
 
-type RenderQueueItem = tuple[str | None, Iterable[tuple[Interpolator, Template, InterpolationInfo]]]
+type RenderQueueItem = tuple[
+    str | None, Iterable[tuple[Interpolator, Template, InterpolationInfo]]
+]
 
 
-def interpolate_comment(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_comment(
+    render_api, bf, last_container_tag, template, ip_info
+) -> RenderQueueItem | None:
     container_tag, comment_t = ip_info
-    assert container_tag == '<!--'
-    bf.append(render_api.escape_html_comment(render_api.resolve_text_without_recursion(template, container_tag, comment_t)))
+    assert container_tag == "<!--"
+    bf.append(
+        render_api.escape_html_comment(
+            render_api.resolve_text_without_recursion(
+                template, container_tag, comment_t
+            )
+        )
+    )
 
 
-def interpolate_attrs(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_attrs(
+    render_api, bf, last_container_tag, template, ip_info
+) -> RenderQueueItem | None:
     container_tag, attrs = ip_info
     resolved_attrs = render_api.resolve_attrs(attrs, template)
     attrs_str = render_html_attrs(coerce_to_html_attrs(resolved_attrs))
@@ -129,7 +149,9 @@ def _prep_cinfo(component_callable, attrs, system):
     return kwargs
 
 
-def interpolate_component(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_component(
+    render_api, bf, last_container_tag, template, ip_info
+) -> RenderQueueItem | None:
     """
     - Extract children template or use empty template.
     - Transform children template into struct template.
@@ -143,53 +165,84 @@ def interpolate_component(render_api, bf, last_container_tag, template, ip_info)
     (container_tag, attrs, start_i_index, end_i_index, body_start_s_index) = ip_info
     if start_i_index != end_i_index and end_i_index is not None:
         # @DESIGN: We extract the children template from the original outer template.
-        children_template = render_api.transform_api.extract_children_template(template, body_start_s_index, end_i_index)
+        children_template = render_api.transform_api.extract_children_template(
+            template, body_start_s_index, end_i_index
+        )
     else:
-        children_template = Template('')
+        children_template = Template("")
     children_struct_t = render_api.process_template(children_template)
     resolved_attrs = render_api.resolve_attrs(attrs, template)
     start_i = template.interpolations[start_i_index]
     component_callable = start_i.value
-    if start_i_index != end_i_index and end_i_index is not None and component_callable != template.interpolations[end_i_index].value:
-        raise TypeError('Component callable in start tag must match component callable in end tag.')
+    if (
+        start_i_index != end_i_index
+        and end_i_index is not None
+        and component_callable != template.interpolations[end_i_index].value
+    ):
+        raise TypeError(
+            "Component callable in start tag must match component callable in end tag."
+        )
 
     # @DESIGN: Inject system vars via manager?
-    system_dict = render_api.get_system(children=children_template, children_struct=children_struct_t)
+    system_dict = render_api.get_system(
+        children=children_template, children_struct=children_struct_t
+    )
     # @DESIGN: Determine return signature from callable info (cached inspection) ?
     kwargs = _prep_cinfo(component_callable, resolved_attrs, system_dict)
     res = component_callable(**kwargs)
     # @DESIGN: Determine return signature via runtime inspection?
     if isinstance(res, tuple):
         result_template, comp_info = res
-        context_values = comp_info.get('context_values', ()) if comp_info else ()
+        context_values = comp_info.get("context_values", ()) if comp_info else ()
     else:
         result_template = res
         comp_info = None
         context_values = ()
 
     # @DESIGN: Use open-ended dict for opt-in second return argument?
-    context_values = comp_info.get('context_values', ()) if comp_info else ()
+    context_values = comp_info.get("context_values", ()) if comp_info else ()
 
     if result_template:
         result_struct = render_api.process_template(result_template)
         if context_values:
-            walker = render_api.walk_template_with_context(bf, result_template, result_struct, context_values=context_values)
+            walker = render_api.walk_template_with_context(
+                bf, result_template, result_struct, context_values=context_values
+            )
         else:
             walker = render_api.walk_template(bf, result_template, result_struct)
         return (container_tag, iter(walker))
 
 
-def interpolate_raw_text(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_raw_text(
+    render_api, bf, last_container_tag, template, ip_info
+) -> RenderQueueItem | None:
     container_tag, content_t = ip_info
-    bf.append(render_api.escape_html_content_in_tag(container_tag, render_api.resolve_text_without_recursion(template, container_tag, content_t)))
+    bf.append(
+        render_api.escape_html_content_in_tag(
+            container_tag,
+            render_api.resolve_text_without_recursion(
+                template, container_tag, content_t
+            ),
+        )
+    )
 
 
-def interpolate_escapable_raw_text(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_escapable_raw_text(
+    render_api, bf, last_container_tag, template, ip_info
+) -> RenderQueueItem | None:
     container_tag, content_t = ip_info
-    bf.append(render_api.escape_html_text(render_api.resolve_text_without_recursion(template, container_tag, content_t)))
+    bf.append(
+        render_api.escape_html_text(
+            render_api.resolve_text_without_recursion(
+                template, container_tag, content_t
+            )
+        )
+    )
 
 
-def interpolate_struct_text(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_struct_text(
+    render_api, bf, last_container_tag, template, ip_info
+) -> RenderQueueItem | None:
     container_tag, ip_index = ip_info
     # @TODO: We just completely ignore any conversion or format_spec here.
     # This is actually a much larger problem/decision of how can a user give us more information about what to do
@@ -198,15 +251,23 @@ def interpolate_struct_text(render_api, bf, last_container_tag, template, ip_inf
     #   - The 3rd interpolation will always be a html-aware Template string
     #   - The 4th interpolation will be an iterator of html-aware Template strings
     #   - The 5th interpolation will be an iterator of strings to render and escape.
-    value = template.interpolations[ip_index].value # data provided to a parsed t-string
-    return interpolate_text(render_api, bf, last_container_tag, template, (container_tag, value))
+    value = template.interpolations[
+        ip_index
+    ].value  # data provided to a parsed t-string
+    return interpolate_text(
+        render_api, bf, last_container_tag, template, (container_tag, value)
+    )
 
 
-def interpolate_user_text(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_user_text(
+    render_api, bf, last_container_tag, template, ip_info
+) -> RenderQueueItem | None:
     return interpolate_text(render_api, bf, last_container_tag, template, ip_info)
 
 
-def interpolate_text(render_api, bf, last_container_tag, template, ip_info) -> RenderQueueItem | None:
+def interpolate_text(
+    render_api, bf, last_container_tag, template, ip_info
+) -> RenderQueueItem | None:
     container_tag, value = ip_info
     if container_tag is None:
         container_tag = last_container_tag
@@ -216,22 +277,34 @@ def interpolate_text(render_api, bf, last_container_tag, template, ip_info) -> R
     #
     if not isinstance(value, str):
         if isinstance(value, Template):
-            return (container_tag, iter(render_api.walk_template(bf, value, render_api.process_template(value))))
-        elif isinstance(value, Sequence) or hasattr(value, '__iter__'):
-            return (container_tag, (((interpolate_user_text, template, (None, v)) for v in iter(value))))
+            return (
+                container_tag,
+                iter(
+                    render_api.walk_template(
+                        bf, value, render_api.process_template(value)
+                    )
+                ),
+            )
+        elif isinstance(value, Sequence) or hasattr(value, "__iter__"):
+            return (
+                container_tag,
+                (((interpolate_user_text, template, (None, v)) for v in iter(value))),
+            )
         elif value is False or value is None:
             # Do nothing here, we don't even need to yield ''.
             return
 
-    if container_tag not in ('style', 'script', 'title', 'textarea', '<!--'):
-        if hasattr(value, '__html__'):
+    if container_tag not in ("style", "script", "title", "textarea", "<!--"):
+        if hasattr(value, "__html__"):
             bf.append(value.__html__())
         else:
             bf.append(render_api.escape_html_text(value))
     else:
         # @TODO: How could this happen?
-        raise ValueError(f'We cannot escape text within {container_tag} when multiple interpolations could occur.')
-        #bf.append(render_api.escape_html_content_in_tag(container_tag, str(value)))
+        raise ValueError(
+            f"We cannot escape text within {container_tag} when multiple interpolations could occur."
+        )
+        # bf.append(render_api.escape_html_content_in_tag(container_tag, str(value)))
 
 
 @dataclass(frozen=True)
@@ -247,10 +320,10 @@ class TransformService:
 
     escape_html_text: Callable = default_escape_html_text
 
-    slash_void: bool = False # Apply a xhtml-style slash to void html elements.
+    slash_void: bool = False  # Apply a xhtml-style slash to void html elements.
 
     def transform_template(self, values_template: Template) -> Template:
-        """ Transform the given template into a template for rendering. """
+        """Transform the given template into a template for rendering."""
         struct_node = self.to_struct_node(values_template)
         return self.to_struct_template(struct_node)
 
@@ -258,38 +331,65 @@ def to_struct_node(self, values_template: Template) -> TNode:
         return TemplateParser.parse(values_template)
 
     def to_struct_template(self, struct_node: TNode) -> Template:
-        """ Recombine stream of tokens from node trees into a new template. """
+        """Recombine stream of tokens from node trees into a new template."""
         return Template(*self.streamer(struct_node))
 
     def _stream_comment_interpolation(self, text_t):
-        info = ('<!--', text_t)
-        return Interpolation((interpolate_comment, info), '', None, 'html_comment_template')
+        info = ("<!--", text_t)
+        return Interpolation(
+            (interpolate_comment, info), "", None, "html_comment_template"
+        )
 
     def _stream_attrs_interpolation(self, last_container_tag, attrs):
         info = (last_container_tag, attrs)
-        return Interpolation((interpolate_attrs, info), '', None, 'html_attrs_seq')
+        return Interpolation((interpolate_attrs, info), "", None, "html_attrs_seq")
 
-    def _stream_component_interpolation(self, last_container_tag, attrs, start_i_index, end_i_index):
+    def _stream_component_interpolation(
+        self, last_container_tag, attrs, start_i_index, end_i_index
+    ):
         # If the interpolation is at 1, then the opening string starts inside at least string 2 (+1)
         # but it can't start until after any dynamic attributes without our own tag
         # so we have to count past those.
-        body_start_s_index  = start_i_index + 1 + len([1 for attr in attrs if not isinstance(attr, TLiteralAttribute)])
-        info = (last_container_tag, attrs, start_i_index, end_i_index, body_start_s_index)
-        return Interpolation((interpolate_component, info), '', None, 'tdom_component')
+        body_start_s_index = (
+            start_i_index
+            + 1
+            + len([1 for attr in attrs if not isinstance(attr, TLiteralAttribute)])
+        )
+        info = (
+            last_container_tag,
+            attrs,
+            start_i_index,
+            end_i_index,
+            body_start_s_index,
+        )
+        return Interpolation((interpolate_component, info), "", None, "tdom_component")
 
     def _stream_raw_text_interpolation(self, last_container_tag, text_t):
         info = (last_container_tag, text_t)
-        return Interpolation((interpolate_raw_text, info), '', None, 'html_raw_text_template')
+        return Interpolation(
+            (interpolate_raw_text, info), "", None, "html_raw_text_template"
+        )
 
     def _stream_escapable_raw_text_interpolation(self, last_container_tag, text_t):
         info = (last_container_tag, text_t)
-        return Interpolation((interpolate_escapable_raw_text, info), '', None, 'html_escapable_raw_text_template')
+        return Interpolation(
+            (interpolate_escapable_raw_text, info),
+            "",
+            None,
+            "html_escapable_raw_text_template",
+        )
 
-    def _stream_text_interpolation(self, last_container_tag: str|None, values_index: int):
+    def _stream_text_interpolation(
+        self, last_container_tag: str | None, values_index: int
+    ):
         info = (last_container_tag, values_index)
-        return Interpolation((interpolate_struct_text, info), '', None, 'html_normal_interpolation')
+        return Interpolation(
+            (interpolate_struct_text, info), "", None, "html_normal_interpolation"
+        )
 
-    def streamer(self, root: TNode, last_container_tag: str|None=None) -> t.Iterable[str|Interpolation]:
+    def streamer(
+        self, root: TNode, last_container_tag: str | None = None
+    ) -> t.Iterable[str | Interpolation]:
         """
         Stream template parts back out so they can be consolidated into a new metadata-aware template.
         """
@@ -300,40 +400,66 @@ def streamer(self, root: TNode, last_container_tag: str|None=None) -> t.Iterable
                 case EndTag(end_tag):
                     yield end_tag
                 case TDocumentType(text):
-                    yield f'<!doctype {text}>'
+                    yield f"<!doctype {text}>"
                 case TComment(ref):
-                    text_t = Template(*[part if isinstance(part, str) else Interpolation(part, '', None, '') for part in iter(ref)])
-                    yield '<!--'
+                    text_t = Template(
+                        *[
+                            part
+                            if isinstance(part, str)
+                            else Interpolation(part, "", None, "")
+                            for part in iter(ref)
+                        ]
+                    )
+                    yield "<!--"
                     yield self._stream_comment_interpolation(text_t)
-                    yield '-->'
+                    yield "-->"
                 case TFragment(children):
-                    q.extend([(last_container_tag, child) for child in reversed(children)])
+                    q.extend(
+                        [(last_container_tag, child) for child in reversed(children)]
+                    )
                 case TComponent(start_i_index, end_i_index, attrs, children):
-                    yield self._stream_component_interpolation(last_container_tag, attrs, start_i_index, end_i_index)
+                    yield self._stream_component_interpolation(
+                        last_container_tag, attrs, start_i_index, end_i_index
+                    )
                 case TElement(tag, attrs, children):
-                    yield f'<{tag}'
+                    yield f"<{tag}"
                     if self.has_dynamic_attrs(attrs):
                         yield self._stream_attrs_interpolation(tag, attrs)
                     else:
                         # @DESIGN: We can't customize the html attrs rendering here because we are not even
                         # in the RENDERER!
-                        yield render_html_attrs(coerce_to_html_attrs(resolve_dynamic_attrs(attrs, interpolations=())))
+                        yield render_html_attrs(
+                            coerce_to_html_attrs(
+                                resolve_dynamic_attrs(attrs, interpolations=())
+                            )
+                        )
                     # @DESIGN: This is just a want to have.
                     if self.slash_void and tag in VOID_ELEMENTS:
-                        yield ' />'
+                        yield " />"
                     else:
-                        yield '>'
+                        yield ">"
                     if tag not in VOID_ELEMENTS:
-                        q.append((last_container_tag, EndTag(f'</{tag}>')))
+                        q.append((last_container_tag, EndTag(f"</{tag}>")))
                         q.extend([(tag, child) for child in reversed(children)])
                 case TText(ref):
-                    text_t = Template(*[part if isinstance(part, str) else Interpolation(part, '', None, '') for part in iter(ref)])
+                    text_t = Template(
+                        *[
+                            part
+                            if isinstance(part, str)
+                            else Interpolation(part, "", None, "")
+                            for part in iter(ref)
+                        ]
+                    )
                     if last_container_tag in CDATA_CONTENT_ELEMENTS:
                         # Must be handled all at once.
-                        yield self._stream_raw_text_interpolation(last_container_tag, text_t)
+                        yield self._stream_raw_text_interpolation(
+                            last_container_tag, text_t
+                        )
                     elif last_container_tag in RCDATA_CONTENT_ELEMENTS:
                         # We can handle all at once because there are no non-text children and everything must be string-ified.
-                        yield self._stream_escapable_raw_text_interpolation(last_container_tag, text_t)
+                        yield self._stream_escapable_raw_text_interpolation(
+                            last_container_tag, text_t
+                        )
                     else:
                         # Flatten the template back out into the stream because each interpolation can
                         # be escaped as is and structured content can be injected between text anyways.
@@ -341,9 +467,11 @@ def streamer(self, root: TNode, last_container_tag: str|None=None) -> t.Iterable
                             if isinstance(part, str):
                                 yield part
                             else:
-                                yield self._stream_text_interpolation(last_container_tag, part.value)
+                                yield self._stream_text_interpolation(
+                                    last_container_tag, part.value
+                                )
                 case _:
-                    raise ValueError(f'Unrecognized tnode: {tnode}')
+                    raise ValueError(f"Unrecognized tnode: {tnode}")
 
     def has_dynamic_attrs(self, attrs: t.Sequence[TAttribute]) -> bool:
         for attr in attrs:
@@ -351,7 +479,9 @@ def has_dynamic_attrs(self, attrs: t.Sequence[TAttribute]) -> bool:
                 return True
         return False
 
-    def extract_children_template(self, template: Template, body_start_s_index: int, end_i_index: int) -> Template:
+    def extract_children_template(
+        self, template: Template, body_start_s_index: int, end_i_index: int
+    ) -> Template:
         """
         Extract the template parts exclusively from start tag to end tag.
 
@@ -384,15 +514,14 @@ def extract_children_template(self, template: Template, body_start_s_index: int,
                 parts.append(template.interpolations[index])
             index += 1
         # Now trim the first part to the end of the opening tag.
-        parts[0] = parts[0][parts[0].find('>')+1:]
+        parts[0] = parts[0][parts[0].find(">") + 1 :]
         # Now trim the last part (could also be the first) to the start of the closing tag.
-        parts[-1] = parts[-1][:parts[-1].rfind('<')]
+        parts[-1] = parts[-1][: parts[-1].rfind("<")]
         return Template(*parts)
 
 
 @dataclass(frozen=True)
 class RenderService:
-
     transform_api: TransformService
 
     escape_html_text: Callable = default_escape_html_text
@@ -402,7 +531,7 @@ class RenderService:
     escape_html_content_in_tag: Callable = default_escape_html_content_in_tag
 
     def get_system(self, children, children_struct):
-        return {'children': children, 'children_struct': children_struct}
+        return {"children": children, "children_struct": children_struct}
 
     def render_template(self, template, last_container_tag=None) -> str:
         """
@@ -420,11 +549,18 @@ def render_template(self, template, last_container_tag=None) -> str:
         # the end.
         bf: list[str] = []
         q: list[RenderQueueItem] = []
-        q.append((last_container_tag, self.walk_template(bf, template, self.process_template(template))))
+        q.append(
+            (
+                last_container_tag,
+                self.walk_template(bf, template, self.process_template(template)),
+            )
+        )
         while q:
             last_container_tag, it = q.pop()
-            for (interpolator, template, ip_info) in it:
-                render_queue_item = interpolator(self, bf, last_container_tag, template, ip_info)
+            for interpolator, template, ip_info in it:
+                render_queue_item = interpolator(
+                    self, bf, last_container_tag, template, ip_info
+                )
                 if render_queue_item is not None:
                     #
                     # Pause the current iterator and push a new iterator on top of it.
@@ -432,7 +568,7 @@ def render_template(self, template, last_container_tag=None) -> str:
                     q.append((last_container_tag, it))
                     q.append(render_queue_item)
                     break
-        return ''.join(bf)
+        return "".join(bf)
 
     def resolve_text_without_recursion(self, template, container_tag, content_t) -> str:
         """
@@ -448,13 +584,15 @@ def resolve_text_without_recursion(self, template, container_tag, content_t) ->
         if exact:
             value = template.interpolations[parts[0].value].value
             if value is None or value is False:
-                return ''
+                return ""
             elif isinstance(value, str):
                 return value
-            elif hasattr(value, '__html__'):
+            elif hasattr(value, "__html__"):
                 return Markup(value.__html__())
             elif isinstance(value, (Template, Iterable)):
-                raise ValueError(f'Recursive includes are not supported within {container_tag}')
+                raise ValueError(
+                    f"Recursive includes are not supported within {container_tag}"
+                )
             else:
                 return str(value)
         else:
@@ -471,17 +609,21 @@ def resolve_text_without_recursion(self, template, container_tag, content_t) ->
                     if value:
                         text.append(value)
                 elif isinstance(value, (Template, Iterable)):
-                    raise ValueError(f'Recursive includes are not supported within {container_tag}')
-                elif hasattr(value, '__html__'):
-                    raise ValueError(f'Non-exact trusted interpolations are not supported within {container_tag}')
+                    raise ValueError(
+                        f"Recursive includes are not supported within {container_tag}"
+                    )
+                elif hasattr(value, "__html__"):
+                    raise ValueError(
+                        f"Non-exact trusted interpolations are not supported within {container_tag}"
+                    )
                 else:
                     value_str = str(value)
                     if value_str:
                         text.append(value_str)
-            return ''.join(text)
+            return "".join(text)
 
     def process_template(self, template):
-        """ This is just a wrap-point for caching. """
+        """This is just a wrap-point for caching."""
         return self.transform_api.transform_template(template)
 
     def resolve_attrs(self, attrs, template) -> AttributesDict:
@@ -526,19 +668,20 @@ class ContextVarSetter:
     another part of the program can use to wrap some called code without knowing
     anything about either.
     """
-    context_values: tuple[tuple[ContextVar, object],...] # Cvar / value pair.
-    tokens: tuple[Token,...]
+
+    context_values: tuple[tuple[ContextVar, object], ...]  # Cvar / value pair.
+    tokens: tuple[Token, ...]
 
     def __init__(self, context_values=()):
         self.context_values = context_values
         self.tokens = ()
 
     def __enter__(self):
-        """ Set every given context var to its paired value. """
+        """Set every given context var to its paired value."""
         self.tokens = tuple([var.set(val) for var, val in self.context_values])
 
     def __exit__(self, exc_type, exc_value, traceback):
-        """ Reset every given context var. """
+        """Reset every given context var."""
         for idx, var_value in enumerate(self.context_values):
             var_value[0].reset(self.tokens[idx])
 
@@ -556,7 +699,6 @@ def cached_render_service_factory():
 #
 @dataclass(frozen=True)
 class CachedTransformService(TransformService):
-
     @functools.lru_cache(512)
     def _transform_template(self, cached_template: CachableTemplate) -> Template:
         return super().transform_template(cached_template.template)
@@ -564,4 +706,3 @@ def _transform_template(self, cached_template: CachableTemplate) -> Template:
     def transform_template(self, values_template: Template) -> Template:
         ct = CachableTemplate(values_template)
         return self._transform_template(ct)
-
diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 55eaf4f..0f4e730 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -4,22 +4,28 @@
 import typing as t
 import pytest
 
-from .transformer import render_service_factory, cached_render_service_factory, CachedTransformService
+from .transformer import (
+    render_service_factory,
+    cached_render_service_factory,
+    CachedTransformService,
+)
 
 
-THEME_CTX = ContextVar('theme', default='default')
+THEME_CTX = ContextVar("theme", default="default")
 
 
 def test_render_template_smoketest():
-    comment_text = 'comment is not literal'
-    interpolated_class = 'red'
-    text_in_element = 'text is not literal'
+    comment_text = "comment is not literal"
+    interpolated_class = "red"
+    text_in_element = "text is not literal"
     templated = "not literal"
-    spread_attrs={'data-on': True}
-    markup_content = Markup('<div>safe</div>')
+    spread_attrs = {"data-on": True}
+    markup_content = Markup("<div>safe</div>")
+
     def WrapperComponent(children):
-        return t'<div>{children}</div>'
-    smoke_t = t'''<!doctype html>
+        return t"<div>{children}</div>"
+
+    smoke_t = t"""<!doctype html>
 <html>
 <body>
 <!-- literal -->
@@ -30,8 +36,8 @@ def WrapperComponent(children):
 <{WrapperComponent}><span>comp body</span></{WrapperComponent}>
 {markup_content}
 </body>
-</html>'''
-    smoke_str = '''<!doctype html>
+</html>"""
+    smoke_str = """<!doctype html>
 <html>
 <body>
 <!-- literal -->
@@ -42,21 +48,26 @@ def WrapperComponent(children):
 <div><span>comp body</span></div>
 <div>safe</div>
 </body>
-</html>'''
+</html>"""
     render_api = render_service_factory()
     assert render_api.render_template(smoke_t) == smoke_str
 
 
 def struct_repr(st):
-    """ Breakdown Templates into comparable parts for test verification. """
-    return st.strings, tuple([(i.value, i.expression, i.conversion, i.format_spec) for i in st.interpolations])
+    """Breakdown Templates into comparable parts for test verification."""
+    return st.strings, tuple(
+        [
+            (i.value, i.expression, i.conversion, i.format_spec)
+            for i in st.interpolations
+        ]
+    )
 
 
 def test_process_template_internal_cache():
-    """ Test that cache and non-cache both generally work as expected. """
-    sample_t = t'''<div>{'content'}</div>'''
-    sample_diff_t = t'''<div>{'diffcontent'}</div>'''
-    alt_t = t'''<span>{'content'}</span>'''
+    """Test that cache and non-cache both generally work as expected."""
+    sample_t = t"""<div>{"content"}</div>"""
+    sample_diff_t = t"""<div>{"diffcontent"}</div>"""
+    alt_t = t"""<span>{"content"}</span>"""
     render_api = render_service_factory()
     cached_render_api = cached_render_service_factory()
     tnode1 = render_api.process_template(sample_t)
@@ -97,32 +108,51 @@ def test_process_template_internal_cache():
 
 
 def test_render_template_repeated():
-    """ Crude check for any unintended state being kept between calls. """
+    """Crude check for any unintended state being kept between calls."""
+
     def get_sample_t(idx, spread_attrs, button_text):
-        return t'''<div><button data-key={idx} {spread_attrs}>{button_text}</button></div>'''
+        return t"""<div><button data-key={idx} {spread_attrs}>{button_text}</button></div>"""
+
     render_apis = (render_service_factory(), cached_render_service_factory())
     for render_api in render_apis:
         for idx in range(3):
-            spread_attrs = {'data-enabled': True}
-            button_text = 'RENDER'
+            spread_attrs = {"data-enabled": True}
+            button_text = "RENDER"
             sample_t = get_sample_t(idx, spread_attrs, button_text)
-            assert render_api.render_template(sample_t) == f'<div><button data-key="{idx}" data-enabled>RENDER</button></div>'
+            assert (
+                render_api.render_template(sample_t)
+                == f'<div><button data-key="{idx}" data-enabled>RENDER</button></div>'
+            )
+
 
 def test_render_template_iterables():
     render_api = render_service_factory()
 
     def get_select_t_with_list(options, selected_values):
-        return t'''<select>{[
-            t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>" for opt in options]
-        }</select>'''
+        return t"""<select>{
+            [
+                t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>"
+                for opt in options
+            ]
+        }</select>"""
+
     def get_select_t_with_generator(options, selected_values):
-        return t'''<select>{(
-            t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>" for opt in options)
-        }</select>'''
+        return t"""<select>{
+            (
+                t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>"
+                for opt in options
+            )
+        }</select>"""
+
     def get_select_t_with_concat(options, selected_values):
-        parts = [t'<select>']
-        parts.extend([t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>" for opt in options])
-        parts.append(t'</select>')
+        parts = [t"<select>"]
+        parts.extend(
+            [
+                t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>"
+                for opt in options
+            ]
+        )
+        parts.append(t"</select>")
         return sum(parts, t"")
 
     def get_color_select_t(selected_values: set, provider: t.Callable) -> Template:
@@ -130,19 +160,29 @@ def get_color_select_t(selected_values: set, provider: t.Callable) -> Template:
         assert set(selected_values).issubset(set([opt[0] for opt in PRIMARY_COLORS]))
         return provider(PRIMARY_COLORS, selected_values)
 
-    for provider in (get_select_t_with_list,get_select_t_with_generator,get_select_t_with_concat):
-        assert render_api.render_template(get_color_select_t(set(), provider)) == '<select><option value="R">Red</option><option value="Y">Yellow</option><option value="B">Blue</option></select>'
-        assert render_api.render_template(get_color_select_t({'Y'}, provider)) == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'
+    for provider in (
+        get_select_t_with_list,
+        get_select_t_with_generator,
+        get_select_t_with_concat,
+    ):
+        assert (
+            render_api.render_template(get_color_select_t(set(), provider))
+            == '<select><option value="R">Red</option><option value="Y">Yellow</option><option value="B">Blue</option></select>'
+        )
+        assert (
+            render_api.render_template(get_color_select_t({"Y"}, provider))
+            == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'
+        )
 
 
 def test_context_provider_pattern():
     def ThemeProvider(theme, children):
-        return children, {'context_values': ((THEME_CTX, theme),)}
+        return children, {"context_values": ((THEME_CTX, theme),)}
 
     def IntermediateWrapper(children):
         # Wrap in between the provider and consumer just to make sure there
         # is no direct interaction.
-        return t'<div>{children}</div>'
+        return t"<div>{children}</div>"
 
     def ThemeConsumer(children):
         theme = THEME_CTX.get()
@@ -152,25 +192,29 @@ def ThemeConsumer(children):
     body_t = t"<body><{ThemeProvider} theme='holiday'><{IntermediateWrapper}><{ThemeConsumer}><b>Cheers!</b></{ThemeConsumer}></{IntermediateWrapper}></{ThemeProvider}></body>"
     # Set the context var to a different value while rendering
     # to make sure this value will be masked
-    with THEME_CTX.set('not-the-default'):
+    with THEME_CTX.set("not-the-default"):
         # During rendering the provider should overlay a new value.
-        assert render_api.render_template(body_t) == '<body><div><p data-theme="holiday"><b>Cheers!</b></p></div></body>'
+        assert (
+            render_api.render_template(body_t)
+            == '<body><div><p data-theme="holiday"><b>Cheers!</b></p></div></body>'
+        )
         # But afterwards we should be back to the old value.
-        assert THEME_CTX.get() == 'not-the-default'
+        assert THEME_CTX.get() == "not-the-default"
     # But after all that we should be back to the context var's offical default.
-    assert THEME_CTX.get() == 'default'
+    assert THEME_CTX.get() == "default"
 
 
 def test_render_template_components_smoketest():
-    """ Broadly test that common template component usage works. """
+    """Broadly test that common template component usage works."""
+
     def PageComponent(children, root_attrs=None):
-        return t'''<div class="content" {root_attrs}>{children}</div>'''
+        return t"""<div class="content" {root_attrs}>{children}</div>"""
 
-    def FooterComponent(classes=('footer-default',)):
+    def FooterComponent(classes=("footer-default",)):
         return t'<div class="footer" class={classes}><a href="about">About</a></div>'
 
     def LayoutComponent(children, body_classes=None):
-        return t'''<!doctype html>
+        return t"""<!doctype html>
 <html>
   <head>
     <meta charset="utf-8">
@@ -182,12 +226,16 @@ def LayoutComponent(children, body_classes=None):
     <{FooterComponent} />
   </body>
 </html>
-'''
+"""
 
     render_api = render_service_factory()
-    content = 'HTML never goes out of style.'
-    content_str = render_api.render_template(t'<{LayoutComponent} body_classes={["theme-default"]}><{PageComponent}>{content}</{PageComponent}></{LayoutComponent}>')
-    assert content_str == '''<!doctype html>
+    content = "HTML never goes out of style."
+    content_str = render_api.render_template(
+        t"<{LayoutComponent} body_classes={['theme-default']}><{PageComponent}>{content}</{PageComponent}></{LayoutComponent}>"
+    )
+    assert (
+        content_str
+        == """<!doctype html>
 <html>
   <head>
     <meta charset="utf-8">
@@ -199,21 +247,22 @@ def LayoutComponent(children, body_classes=None):
     <div class="footer footer-default"><a href="about">About</a></div>
   </body>
 </html>
-'''
+"""
+    )
 
 
 def test_render_template_functions_smoketest():
-    """ Broadly test that common template function usage works. """
+    """Broadly test that common template function usage works."""
 
     def make_page_t(content, root_attrs=None) -> Template:
-        return t'''<div class="content" {root_attrs}>{content}</div>'''
+        return t"""<div class="content" {root_attrs}>{content}</div>"""
 
-    def make_footer_t(classes=('footer-default',)) -> Template:
+    def make_footer_t(classes=("footer-default",)) -> Template:
         return t'<div class="footer" class={classes}><a href="about">About</a></div>'
 
     def make_layout_t(body_t, body_classes=None) -> Template:
         footer_t = make_footer_t()
-        return t'''<!doctype html>
+        return t"""<!doctype html>
 <html>
   <head>
     <meta charset="utf-8">
@@ -225,13 +274,15 @@ def make_layout_t(body_t, body_classes=None) -> Template:
     {footer_t}
   </body>
 </html>
-'''
+"""
 
     render_api = render_service_factory()
-    content = 'HTML never goes out of style.'
+    content = "HTML never goes out of style."
     layout_t = make_layout_t(make_page_t(content), "theme-default")
     content_str = render_api.render_template(layout_t)
-    assert content_str == '''<!doctype html>
+    assert (
+        content_str
+        == """<!doctype html>
 <html>
   <head>
     <meta charset="utf-8">
@@ -243,37 +294,49 @@ def make_layout_t(body_t, body_classes=None) -> Template:
     <div class="footer footer-default"><a href="about">About</a></div>
   </body>
 </html>
-'''
+"""
+    )
 
 
 def test_text_interpolation_with_dynamic_parent():
     render_api = render_service_factory()
-    with pytest.raises(ValueError, match='Recursive includes are not supported within script'):
+    with pytest.raises(
+        ValueError, match="Recursive includes are not supported within script"
+    ):
         content = '<script>console.log("123!");</script>'
-        content_t = t'{content}'
-        _ = render_api.render_template(t'<script>{content_t}</script>')
+        content_t = t"{content}"
+        _ = render_api.render_template(t"<script>{content_t}</script>")
 
 
-@pytest.mark.skip('Can we allow this?')
+@pytest.mark.skip("Can we allow this?")
 def test_escape_escapable_raw_text_with_dynamic_parent():
     content = '<script>console.log("123!");</script>'
-    content_t = t'{content}'
+    content_t = t"{content}"
     render_api = render_service_factory()
-    LT, GT, DQ = map(markupsafe_escape, ['<', '>', '"'])
-    assert render_api.render_template(t'<textarea>{content_t}</textarea>') == f'<textarea>{LT}script{GT}console.log({DQ}123!{DQ});{LT}/script{GT}</textarea>'
+    LT, GT, DQ = map(markupsafe_escape, ["<", ">", '"'])
+    assert (
+        render_api.render_template(t"<textarea>{content_t}</textarea>")
+        == f"<textarea>{LT}script{GT}console.log({DQ}123!{DQ});{LT}/script{GT}</textarea>"
+    )
 
 
 def test_escape_structured_text_with_dynamic_parent():
     content = '<script>console.log("123!");</script>'
-    content_t = t'{content}'
+    content_t = t"{content}"
     render_api = render_service_factory()
-    LT, GT, DQ = map(markupsafe_escape, ['<', '>', '"'])
-    assert render_api.render_template(t'<div>{content_t}</div>') == f'<div>{LT}script{GT}console.log({DQ}123!{DQ});{LT}/script{GT}</div>'
+    LT, GT, DQ = map(markupsafe_escape, ["<", ">", '"'])
+    assert (
+        render_api.render_template(t"<div>{content_t}</div>")
+        == f"<div>{LT}script{GT}console.log({DQ}123!{DQ});{LT}/script{GT}</div>"
+    )
 
 
 def test_escape_structured_text():
     content = '<script>console.log("123!");</script>'
-    content_t = t'<div>{content}</div>'
+    content_t = t"<div>{content}</div>"
     render_api = render_service_factory()
-    LT, GT, DQ = map(markupsafe_escape, ['<', '>', '"'])
-    assert render_api.render_template(content_t) == f'<div>{LT}script{GT}console.log({DQ}123!{DQ});{LT}/script{GT}</div>'
+    LT, GT, DQ = map(markupsafe_escape, ["<", ">", '"'])
+    assert (
+        render_api.render_template(content_t)
+        == f"<div>{LT}script{GT}console.log({DQ}123!{DQ});{LT}/script{GT}</div>"
+    )

From 8bbc0d1c85b12d8697c737deb2c4a8eeefaf459c Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 15 Jan 2026 15:10:57 -0800
Subject: [PATCH 36/81] Stop pre-processing the component template and just act
 on return value.

---
 tdom/transformer.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index ff332db..dcc2eb9 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -170,7 +170,7 @@ def interpolate_component(
         )
     else:
         children_template = Template("")
-    children_struct_t = render_api.process_template(children_template)
+    # @DESIGN: children_struct_t = render_api.process_template(children_template) ?
     resolved_attrs = render_api.resolve_attrs(attrs, template)
     start_i = template.interpolations[start_i_index]
     component_callable = start_i.value
@@ -185,7 +185,7 @@ def interpolate_component(
 
     # @DESIGN: Inject system vars via manager?
     system_dict = render_api.get_system(
-        children=children_template, children_struct=children_struct_t
+        children=children_template #@DESIGN: children_struct=children_struct_t ?
     )
     # @DESIGN: Determine return signature from callable info (cached inspection) ?
     kwargs = _prep_cinfo(component_callable, resolved_attrs, system_dict)
@@ -530,8 +530,9 @@ class RenderService:
 
     escape_html_content_in_tag: Callable = default_escape_html_content_in_tag
 
-    def get_system(self, children, children_struct):
-        return {"children": children, "children_struct": children_struct}
+    def get_system(self, **kwargs):
+        # @DESIGN: Maybe inject more here?
+        return {**kwargs}
 
     def render_template(self, template, last_container_tag=None) -> str:
         """

From aad23649337c22339e8e39d14a5fca39e8c3c51c Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 15 Jan 2026 15:11:32 -0800
Subject: [PATCH 37/81] Start cleaning comments.

---
 tdom/transformer.py | 13 ++-----------
 1 file changed, 2 insertions(+), 11 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index dcc2eb9..0efa691 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -63,7 +63,8 @@ def __call__(
         """
         Populates an interpolation or returns iterator to decende into.
 
-        If recursion is required then pushes current iterator
+        If recursion is required then pushes current iterator.
+
         render_api
             The current render api, provides various helper methods to the interpolator.
         bf
@@ -152,16 +153,6 @@ def _prep_cinfo(component_callable, attrs, system):
 def interpolate_component(
     render_api, bf, last_container_tag, template, ip_info
 ) -> RenderQueueItem | None:
-    """
-    - Extract children template or use empty template.
-    - Transform children template into struct template.
-    - Resolve attrs but don't stringify.
-    - Resolve callable.
-    - Invoke callable with attrs
-    - If callable returns a result template then
-         * transform it to a struct template
-         * iteratively recurse into that result template and start outputting it
-    """
     (container_tag, attrs, start_i_index, end_i_index, body_start_s_index) = ip_info
     if start_i_index != end_i_index and end_i_index is not None:
         # @DESIGN: We extract the children template from the original outer template.

From 1a4bd02a9f7875a4486c75e4e3e428f3600bbe45 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 15 Jan 2026 15:16:11 -0800
Subject: [PATCH 38/81] Stop proxying transform api and just call it directly.

---
 tdom/transformer.py      | 12 ++++--------
 tdom/transformer_test.py | 12 ++++++------
 2 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 0efa691..7bc72d7 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -161,7 +161,7 @@ def interpolate_component(
         )
     else:
         children_template = Template("")
-    # @DESIGN: children_struct_t = render_api.process_template(children_template) ?
+    # @DESIGN: children_struct_t = render_api.transform_api.transform_template(children_template) ?
     resolved_attrs = render_api.resolve_attrs(attrs, template)
     start_i = template.interpolations[start_i_index]
     component_callable = start_i.value
@@ -194,7 +194,7 @@ def interpolate_component(
     context_values = comp_info.get("context_values", ()) if comp_info else ()
 
     if result_template:
-        result_struct = render_api.process_template(result_template)
+        result_struct = render_api.transform_api.transform_template(result_template)
         if context_values:
             walker = render_api.walk_template_with_context(
                 bf, result_template, result_struct, context_values=context_values
@@ -272,7 +272,7 @@ def interpolate_text(
                 container_tag,
                 iter(
                     render_api.walk_template(
-                        bf, value, render_api.process_template(value)
+                        bf, value, render_api.transform_api.transform_template(value)
                     )
                 ),
             )
@@ -544,7 +544,7 @@ def render_template(self, template, last_container_tag=None) -> str:
         q.append(
             (
                 last_container_tag,
-                self.walk_template(bf, template, self.process_template(template)),
+                self.walk_template(bf, template, self.transform_api.transform_template(template)),
             )
         )
         while q:
@@ -614,10 +614,6 @@ def resolve_text_without_recursion(self, template, container_tag, content_t) ->
                         text.append(value_str)
             return "".join(text)
 
-    def process_template(self, template):
-        """This is just a wrap-point for caching."""
-        return self.transform_api.transform_template(template)
-
     def resolve_attrs(self, attrs, template) -> AttributesDict:
         """
         - interpolate interpolations
diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 0f4e730..589b743 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -70,11 +70,11 @@ def test_process_template_internal_cache():
     alt_t = t"""<span>{"content"}</span>"""
     render_api = render_service_factory()
     cached_render_api = cached_render_service_factory()
-    tnode1 = render_api.process_template(sample_t)
-    tnode2 = render_api.process_template(sample_t)
-    cached_tnode1 = cached_render_api.process_template(sample_t)
-    cached_tnode2 = cached_render_api.process_template(sample_t)
-    cached_tnode3 = cached_render_api.process_template(sample_diff_t)
+    tnode1 = render_api.transform_api.transform_template(sample_t)
+    tnode2 = render_api.transform_api.transform_template(sample_t)
+    cached_tnode1 = cached_render_api.transform_api.transform_template(sample_t)
+    cached_tnode2 = cached_render_api.transform_api.transform_template(sample_t)
+    cached_tnode3 = cached_render_api.transform_api.transform_template(sample_diff_t)
     # Check that the uncached and cached services are actually
     # returning non-identical results.
     assert tnode1 is not cached_tnode1
@@ -99,7 +99,7 @@ def test_process_template_internal_cache():
     assert ci.hits == 2
     # cached_tnode1 was a miss because cache was empty (brand new)
     assert ci.misses == 1
-    cached_tnode4 = cached_render_api.process_template(alt_t)
+    cached_tnode4 = cached_render_api.transform_api.transform_template(alt_t)
     # A different template produces a brand new tnode.
     assert cached_tnode1 is not cached_tnode4
     # The template is new AND has a different structure so it also

From 6e337fbef2ed8ace20ce8bbe92141f71b1990f84 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Fri, 16 Jan 2026 13:35:39 -0800
Subject: [PATCH 39/81] Draft of using types.

---
 tdom/transformer.py | 201 ++++++++++++++++++++++++++++++++------------
 1 file changed, 148 insertions(+), 53 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 7bc72d7..cfee555 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -33,9 +33,10 @@
 from .utils import CachableTemplate
 from .processor import (
     _resolve_t_attrs as resolve_dynamic_attrs,
-    AttributesDict,
     _resolve_html_attrs as coerce_to_html_attrs,
     _kebab_to_snake,
+    HasHTMLDunder,
+    AttributesDict,
 )
 from .callables import get_callable_info
 
@@ -56,9 +57,22 @@ def render_html_attrs(
     )
 
 
-class Interpolator(t.Protocol):
+type InterpolateInfo = tuple
+
+
+type RenderQueueItem = tuple[
+    str | None, t.Iterable[tuple[InterpolatorProto, Template, InterpolateInfo]]
+]
+
+
+class InterpolatorProto(t.Protocol):
     def __call__(
-        self, render_api, bf, last_container_tag, template, ip_info
+        self,
+        render_api: RenderService,
+        bf: list[str],
+        last_container_tag: str | None,
+        template: Template,
+        ip_info: InterpolateInfo,
     ) -> RenderQueueItem | None:
         """
         Populates an interpolation or returns iterator to decende into.
@@ -79,21 +93,20 @@ def __call__(
 
         Returns a render queue item when the main iteration loops needs to be paused and restarted to descend.
         """
-        pass
-
+        raise NotImplementedError
 
-type InterpolationInfo = object | None
 
-
-type RenderQueueItem = tuple[
-    str | None, Iterable[tuple[Interpolator, Template, InterpolationInfo]]
-]
+type InterpolateCommentInfo = tuple[str, Template]
 
 
 def interpolate_comment(
-    render_api, bf, last_container_tag, template, ip_info
+    render_api: RenderService,
+    bf: list[str],
+    last_container_tag: str | None,
+    template: Template,
+    ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    container_tag, comment_t = ip_info
+    container_tag, comment_t = t.cast(InterpolateCommentInfo, ip_info)
     assert container_tag == "<!--"
     bf.append(
         render_api.escape_html_comment(
@@ -104,16 +117,25 @@ def interpolate_comment(
     )
 
 
+type InterpolateAttrsInfo = tuple[str, Sequence[TAttribute]]
+
+
 def interpolate_attrs(
-    render_api, bf, last_container_tag, template, ip_info
+    render_api: RenderService,
+    bf: list[str],
+    last_container_tag: str | None,
+    template: Template,
+    ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    container_tag, attrs = ip_info
+    container_tag, attrs = t.cast(InterpolateAttrsInfo, ip_info)
     resolved_attrs = render_api.resolve_attrs(attrs, template)
     attrs_str = render_html_attrs(coerce_to_html_attrs(resolved_attrs))
     bf.append(attrs_str)
 
 
-def _prep_cinfo(component_callable, attrs, system):
+def _prep_cinfo(
+    component_callable: Callable, attrs: AttributesDict, system: dict[str, object]
+):
     # @DESIGN: This is lifted from the processor and then grossified.
     # Not sure this will work out but maybe we'd unify these.
     callable_info = get_callable_info(component_callable)
@@ -150,10 +172,19 @@ def _prep_cinfo(component_callable, attrs, system):
     return kwargs
 
 
+type InterpolateComponentInfo = tuple[str, Sequence[TAttribute], int, int | None, int]
+
+
 def interpolate_component(
-    render_api, bf, last_container_tag, template, ip_info
+    render_api: RenderService,
+    bf: list[str],
+    last_container_tag: str | None,
+    template: Template,
+    ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    (container_tag, attrs, start_i_index, end_i_index, body_start_s_index) = ip_info
+    (container_tag, attrs, start_i_index, end_i_index, body_start_s_index) = t.cast(
+        InterpolateComponentInfo, ip_info
+    )
     if start_i_index != end_i_index and end_i_index is not None:
         # @DESIGN: We extract the children template from the original outer template.
         children_template = render_api.transform_api.extract_children_template(
@@ -176,7 +207,7 @@ def interpolate_component(
 
     # @DESIGN: Inject system vars via manager?
     system_dict = render_api.get_system(
-        children=children_template #@DESIGN: children_struct=children_struct_t ?
+        children=children_template  # @DESIGN: children_struct=children_struct_t ?
     )
     # @DESIGN: Determine return signature from callable info (cached inspection) ?
     kwargs = _prep_cinfo(component_callable, resolved_attrs, system_dict)
@@ -204,10 +235,17 @@ def interpolate_component(
         return (container_tag, iter(walker))
 
 
+type InterpolateRawTextInfo = tuple[str, Template]
+
+
 def interpolate_raw_text(
-    render_api, bf, last_container_tag, template, ip_info
+    render_api: RenderService,
+    bf: list[str],
+    last_container_tag: str | None,
+    template: Template,
+    ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    container_tag, content_t = ip_info
+    container_tag, content_t = t.cast(InterpolateRawTextInfo, ip_info)
     bf.append(
         render_api.escape_html_content_in_tag(
             container_tag,
@@ -218,10 +256,17 @@ def interpolate_raw_text(
     )
 
 
+type InterpolateEscapableRawTextInfo = tuple[str, Template]
+
+
 def interpolate_escapable_raw_text(
-    render_api, bf, last_container_tag, template, ip_info
+    render_api: RenderService,
+    bf: list[str],
+    last_container_tag: str | None,
+    template: Template,
+    ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    container_tag, content_t = ip_info
+    container_tag, content_t = t.cast(InterpolateEscapableRawTextInfo, ip_info)
     bf.append(
         render_api.escape_html_text(
             render_api.resolve_text_without_recursion(
@@ -231,10 +276,17 @@ def interpolate_escapable_raw_text(
     )
 
 
+type InterpolateStructTextInfo = tuple[str, int]
+
+
 def interpolate_struct_text(
-    render_api, bf, last_container_tag, template, ip_info
+    render_api: RenderService,
+    bf: list[str],
+    last_container_tag: str | None,
+    template: Template,
+    ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    container_tag, ip_index = ip_info
+    container_tag, ip_index = t.cast(InterpolateStructTextInfo, ip_info)
     # @TODO: We just completely ignore any conversion or format_spec here.
     # This is actually a much larger problem/decision of how can a user give us more information about what to do
     # with their input AND should that be a one-off OR cached with the structured template forever.
@@ -250,16 +302,35 @@ def interpolate_struct_text(
     )
 
 
+# @TODO: can we coerce this to still use typing even if we just str() everything ? -- `| object`
+type UserTextValueItem = None | str | Template | HasHTMLDunder
+# @TODO: See above about `| object`
+type UserTextValue = (
+    UserTextValueItem | Sequence[UserTextValueItem] | t.Iterable[UserTextValueItem]
+)
+
+
 def interpolate_user_text(
-    render_api, bf, last_container_tag, template, ip_info
+    render_api: RenderService,
+    bf: list[str],
+    last_container_tag: str | None,
+    template: Template,
+    ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
     return interpolate_text(render_api, bf, last_container_tag, template, ip_info)
 
 
+type InterpolateTextInfo = tuple[str, object]
+
+
 def interpolate_text(
-    render_api, bf, last_container_tag, template, ip_info
+    render_api: RenderService,
+    bf: list[str],
+    last_container_tag: str | None,
+    template: Template,
+    ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    container_tag, value = ip_info
+    container_tag, value = t.cast(InterpolateTextInfo, ip_info)
     if container_tag is None:
         container_tag = last_container_tag
 
@@ -276,17 +347,29 @@ def interpolate_text(
                     )
                 ),
             )
-        elif isinstance(value, Sequence) or hasattr(value, "__iter__"):
+        elif isinstance(value, t.Sequence) or hasattr(value, "__iter__"):
             return (
+                # yield (populate, template, value)
                 container_tag,
-                (((interpolate_user_text, template, (None, v)) for v in iter(value))),
+                (
+                    (
+                        interpolate_user_text,
+                        template,
+                        (container_tag, v if v is not None else None),
+                    )
+                    for v in t.cast(Iterable, value)
+                ),
             )
         elif value is False or value is None:
             # Do nothing here, we don't even need to yield ''.
             return
+        else:
+            # Fall's through, we should rewrite this.
+            pass
 
     if container_tag not in ("style", "script", "title", "textarea", "<!--"):
         if hasattr(value, "__html__"):
+            value = t.cast(HasHTMLDunder, value)
             bf.append(value.__html__())
         else:
             bf.append(render_api.escape_html_text(value))
@@ -313,25 +396,27 @@ class TransformService:
 
     slash_void: bool = False  # Apply a xhtml-style slash to void html elements.
 
-    def transform_template(self, values_template: Template) -> Template:
+    def transform_template(self, template: Template) -> Template:
         """Transform the given template into a template for rendering."""
-        struct_node = self.to_struct_node(values_template)
+        struct_node = self.to_struct_node(template)
         return self.to_struct_template(struct_node)
 
-    def to_struct_node(self, values_template: Template) -> TNode:
-        return TemplateParser.parse(values_template)
+    def to_struct_node(self, template: Template) -> TNode:
+        return TemplateParser.parse(template)
 
     def to_struct_template(self, struct_node: TNode) -> Template:
         """Recombine stream of tokens from node trees into a new template."""
         return Template(*self.streamer(struct_node))
 
-    def _stream_comment_interpolation(self, text_t):
+    def _stream_comment_interpolation(self, text_t: Template):
         info = ("<!--", text_t)
         return Interpolation(
             (interpolate_comment, info), "", None, "html_comment_template"
         )
 
-    def _stream_attrs_interpolation(self, last_container_tag, attrs):
+    def _stream_attrs_interpolation(
+        self, last_container_tag: str | None, attrs: t.Sequence[TAttribute]
+    ):
         info = (last_container_tag, attrs)
         return Interpolation((interpolate_attrs, info), "", None, "html_attrs_seq")
 
@@ -521,11 +606,13 @@ class RenderService:
 
     escape_html_content_in_tag: Callable = default_escape_html_content_in_tag
 
-    def get_system(self, **kwargs):
+    def get_system(self, **kwargs: object):
         # @DESIGN: Maybe inject more here?
         return {**kwargs}
 
-    def render_template(self, template, last_container_tag=None) -> str:
+    def render_template(
+        self, template: Template, last_container_tag: str | None = None
+    ) -> str:
         """
         Iterate left to right and pause and push new iterators when descending depth-first.
 
@@ -544,7 +631,9 @@ def render_template(self, template, last_container_tag=None) -> str:
         q.append(
             (
                 last_container_tag,
-                self.walk_template(bf, template, self.transform_api.transform_template(template)),
+                self.walk_template(
+                    bf, template, self.transform_api.transform_template(template)
+                ),
             )
         )
         while q:
@@ -562,7 +651,9 @@ def render_template(self, template, last_container_tag=None) -> str:
                     break
         return "".join(bf)
 
-    def resolve_text_without_recursion(self, template, container_tag, content_t) -> str:
+    def resolve_text_without_recursion(
+        self, template: Template, container_tag: str, content_t: Template
+    ) -> str:
         """
         Resolve the text in the given template without recursing into more structured text.
 
@@ -571,10 +662,9 @@ def resolve_text_without_recursion(self, template, container_tag, content_t) ->
         A non-exact match is not allowed because we cannot process escaping
         across the boundary between other content and the pass-through content.
         """
-        parts = list(content_t)
-        exact = len(parts) == 1 and len(content_t.interpolations) == 1
-        if exact:
-            value = template.interpolations[parts[0].value].value
+        if len(content_t.interpolations) == 1 and content_t.strings == ("", ""):
+            i_index = t.cast(int, content_t.interpolations[0].value)
+            value = template.interpolations[i_index].value
             if value is None or value is False:
                 return ""
             elif isinstance(value, str):
@@ -614,15 +704,18 @@ def resolve_text_without_recursion(self, template, container_tag, content_t) ->
                         text.append(value_str)
             return "".join(text)
 
-    def resolve_attrs(self, attrs, template) -> AttributesDict:
-        """
-        - interpolate interpolations
-        - perform special attribute handling
-        - merge
-        """
+    def resolve_attrs(
+        self, attrs: t.Sequence[TAttribute], template: Template
+    ) -> AttributesDict:
         return resolve_dynamic_attrs(attrs, template.interpolations)
 
-    def walk_template_with_context(self, bf, template, struct_t, context_values=None):
+    def walk_template_with_context(
+        self,
+        bf: list[str],
+        template: Template,
+        struct_t: Template,
+        context_values: tuple[tuple[ContextVar, object]] | None = None,
+    ) -> Iterable[tuple[InterpolatorProto, Template, InterpolateInfo]]:
         if context_values:
             cm = ContextVarSetter(context_values=context_values)
         else:
@@ -630,7 +723,9 @@ def walk_template_with_context(self, bf, template, struct_t, context_values=None
         with cm:
             yield from self.walk_template(bf, template, struct_t)
 
-    def walk_template(self, bf, template, struct_t):
+    def walk_template(
+        self, bf: list[str], template: Template, struct_t: Template
+    ) -> Iterable[tuple[InterpolatorProto, Template, InterpolateInfo]]:
         strings = struct_t.strings
         ips = struct_t.interpolations
         last_str = len(strings) - 1
@@ -691,6 +786,6 @@ class CachedTransformService(TransformService):
     def _transform_template(self, cached_template: CachableTemplate) -> Template:
         return super().transform_template(cached_template.template)
 
-    def transform_template(self, values_template: Template) -> Template:
-        ct = CachableTemplate(values_template)
+    def transform_template(self, template: Template) -> Template:
+        ct = CachableTemplate(template)
         return self._transform_template(ct)

From 57f73acf3bd1c0df64841d7025f1d58faa49fc09 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Fri, 16 Jan 2026 13:51:05 -0800
Subject: [PATCH 40/81] Use existing style escaping.

---
 tdom/escaping.py | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/tdom/escaping.py b/tdom/escaping.py
index 2792873..8605968 100644
--- a/tdom/escaping.py
+++ b/tdom/escaping.py
@@ -87,12 +87,7 @@ def escape_html_content_in_tag(parent_tag, content):
     elif parent_tag == "<!--":
         return escape_html_comment(content)
     elif parent_tag == "style":
-        LT = "&lt;"
-        close_str = f"</{parent_tag}>"
-        # @TODO: This whole escaping business is probably be misguided... but we should cache this.
-        close_str_re = re.compile(close_str, re.I | re.A)
-        replace_str = LT + close_str[1:]
-        return re.sub(close_str_re, replace_str, content)
+        return escape_html_style(content)
     else:
         # Fallback to nuclear solution.
         return escape_html_text(content)

From 6f3049b0d5edb08713e3563ed75cc75860fab15c Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Fri, 16 Jan 2026 14:45:53 -0800
Subject: [PATCH 41/81] Use interpolation format if present.

---
 tdom/transformer.py | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index cfee555..0366536 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -8,6 +8,7 @@
 import functools
 from markupsafe import Markup
 
+from .format import format_interpolation
 from .parser import TemplateParser, HTMLAttributesDict
 from .tnodes import (
     TNode,
@@ -287,16 +288,7 @@ def interpolate_struct_text(
     ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
     container_tag, ip_index = t.cast(InterpolateStructTextInfo, ip_info)
-    # @TODO: We just completely ignore any conversion or format_spec here.
-    # This is actually a much larger problem/decision of how can a user give us more information about what to do
-    # with their input AND should that be a one-off OR cached with the structured template forever.
-    # For example
-    #   - The 3rd interpolation will always be a html-aware Template string
-    #   - The 4th interpolation will be an iterator of html-aware Template strings
-    #   - The 5th interpolation will be an iterator of strings to render and escape.
-    value = template.interpolations[
-        ip_index
-    ].value  # data provided to a parsed t-string
+    value = format_interpolation(template.interpolations[ip_index])
     return interpolate_text(
         render_api, bf, last_container_tag, template, (container_tag, value)
     )

From 4b3223986c778a84780ae39a2ab4c53e6023df49 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Fri, 16 Jan 2026 15:22:13 -0800
Subject: [PATCH 42/81] Re-org to optimize native strs.

---
 tdom/transformer.py | 44 +++++++++++++++++++++++---------------------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 0366536..87fd4c8 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -326,10 +326,16 @@ def interpolate_text(
     if container_tag is None:
         container_tag = last_container_tag
 
-    #
-    # Try to optimize past this block if the value is a str.
-    #
-    if not isinstance(value, str):
+    if type(value) is str:  # ONLY native strings, not Markup/__html__, etc.
+        if container_tag not in ("style", "script", "title", "textarea", "<!--"):
+            bf.append(render_api.escape_html_text(value))
+        else:
+            # @TODO: How could this happen?
+            raise ValueError(
+                f"We cannot escape text within {container_tag} when multiple interpolations could occur."
+            )
+            # bf.append(render_api.escape_html_content_in_tag(container_tag, str(value)))
+    else:
         if isinstance(value, Template):
             return (
                 container_tag,
@@ -339,9 +345,12 @@ def interpolate_text(
                     )
                 ),
             )
-        elif isinstance(value, t.Sequence) or hasattr(value, "__iter__"):
+        elif not isinstance(value, str) and (
+            isinstance(value, t.Sequence) or hasattr(value, "__iter__")
+        ):
+            # If we don't guard against str instances then str subclasses will be
+            # treated as a sequence/iterable of chars.
             return (
-                # yield (populate, template, value)
                 container_tag,
                 (
                     (
@@ -356,21 +365,14 @@ def interpolate_text(
             # Do nothing here, we don't even need to yield ''.
             return
         else:
-            # Fall's through, we should rewrite this.
-            pass
-
-    if container_tag not in ("style", "script", "title", "textarea", "<!--"):
-        if hasattr(value, "__html__"):
-            value = t.cast(HasHTMLDunder, value)
-            bf.append(value.__html__())
-        else:
-            bf.append(render_api.escape_html_text(value))
-    else:
-        # @TODO: How could this happen?
-        raise ValueError(
-            f"We cannot escape text within {container_tag} when multiple interpolations could occur."
-        )
-        # bf.append(render_api.escape_html_content_in_tag(container_tag, str(value)))
+            if container_tag not in ("style", "script", "title", "textarea", "<!--"):
+                if hasattr(value, "__html__"):
+                    value = t.cast(HasHTMLDunder, value)
+                    bf.append(value.__html__())
+                else:
+                    bf.append(render_api.escape_html_text(str(value)))
+            else:
+                raise NotImplementedError("We cannot handle text escaping here.")
 
 
 @dataclass(frozen=True)

From 85450456ce9136f77ed9ad87287e07581bc2dd69 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Fri, 16 Jan 2026 15:26:14 -0800
Subject: [PATCH 43/81] Don't omit False, just render it to cleanup
 typing-story.

---
 tdom/transformer.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 87fd4c8..8f8798e 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -361,8 +361,8 @@ def interpolate_text(
                     for v in t.cast(Iterable, value)
                 ),
             )
-        elif value is False or value is None:
-            # Do nothing here, we don't even need to yield ''.
+        elif value is None:
+            # @DESIGN: Ignore None.
             return
         else:
             if container_tag not in ("style", "script", "title", "textarea", "<!--"):
@@ -370,6 +370,8 @@ def interpolate_text(
                     value = t.cast(HasHTMLDunder, value)
                     bf.append(value.__html__())
                 else:
+                    # @DESIGN: Everything that isn't an object we recognize is
+                    # coerced to a str() and emitted.
                     bf.append(render_api.escape_html_text(str(value)))
             else:
                 raise NotImplementedError("We cannot handle text escaping here.")

From 7307024ac1d10876f80e288546a31e780310174f Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Fri, 16 Jan 2026 22:28:01 -0800
Subject: [PATCH 44/81] Refactor component kwargs preparation to make it
 reusable.

---
 tdom/processor.py | 63 ++++++++++++++++++++++++++++-------------------
 1 file changed, 38 insertions(+), 25 deletions(-)

diff --git a/tdom/processor.py b/tdom/processor.py
index 1e2528d..ff9b116 100644
--- a/tdom/processor.py
+++ b/tdom/processor.py
@@ -1,13 +1,13 @@
 import sys
 import typing as t
-from collections.abc import Iterable, Sequence
+from collections.abc import Iterable, Sequence, Callable
 from functools import lru_cache
 from string.templatelib import Interpolation, Template
 from dataclasses import dataclass
 
 from markupsafe import Markup
 
-from .callables import get_callable_info
+from .callables import get_callable_info, CallableInfo
 from .format import format_interpolation as base_format_interpolation
 from .format import format_template
 from .nodes import Comment, DocumentType, Element, Fragment, Node, Text
@@ -437,6 +437,39 @@ def _kebab_to_snake(name: str) -> str:
     return name.replace("-", "_").lower()
 
 
+def _prep_component_kwargs(
+    callable_info: CallableInfo,
+    attrs: AttributesDict,
+    system: dict[str, object],
+    kebab_to_snake: Callable[[str], str] = _kebab_to_snake,
+):
+    if callable_info.requires_positional:
+        raise TypeError(
+            "Component callables cannot have required positional arguments."
+        )
+
+    kwargs: AttributesDict = {}
+
+    # Add all supported attributes
+    for attr_name, attr_value in attrs.items():
+        snake_name = kebab_to_snake(attr_name)
+        if snake_name in callable_info.named_params or callable_info.kwargs:
+            kwargs[snake_name] = attr_value
+
+    for attr_name, attr_value in system.items():
+        if attr_name in callable_info.named_params or callable_info.kwargs:
+            kwargs[attr_name] = attr_value
+
+    # Check to make sure we've fully satisfied the callable's requirements
+    missing = callable_info.required_named_params - kwargs.keys()
+    if missing:
+        raise TypeError(
+            f"Missing required parameters for component: {', '.join(missing)}"
+        )
+
+    return kwargs
+
+
 def _invoke_component(
     attrs: AttributesDict,
     children: list[Node],  # TODO: why not TNode, though?
@@ -477,29 +510,9 @@ def _invoke_component(
         )
     callable_info = get_callable_info(value)
 
-    if callable_info.requires_positional:
-        raise TypeError(
-            "Component callables cannot have required positional arguments."
-        )
-
-    kwargs: AttributesDict = {}
-
-    # Add all supported attributes
-    for attr_name, attr_value in attrs.items():
-        snake_name = _kebab_to_snake(attr_name)
-        if snake_name in callable_info.named_params or callable_info.kwargs:
-            kwargs[snake_name] = attr_value
-
-    # Add children if appropriate
-    if "children" in callable_info.named_params or callable_info.kwargs:
-        kwargs["children"] = tuple(children)
-
-    # Check to make sure we've fully satisfied the callable's requirements
-    missing = callable_info.required_named_params - kwargs.keys()
-    if missing:
-        raise TypeError(
-            f"Missing required parameters for component: {', '.join(missing)}"
-        )
+    kwargs = _prep_component_kwargs(
+        callable_info, attrs, system={"children": tuple(children)}
+    )
 
     result = value(**kwargs)
     return _node_from_value(result)

From 9d99422c1d7385f47664a5b38ff12cab28658ea3 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Fri, 16 Jan 2026 22:28:27 -0800
Subject: [PATCH 45/81] Use processor component kwargs prep.

---
 tdom/transformer.py | 44 +++-----------------------------------------
 1 file changed, 3 insertions(+), 41 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 8f8798e..b605bf5 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -35,9 +35,9 @@
 from .processor import (
     _resolve_t_attrs as resolve_dynamic_attrs,
     _resolve_html_attrs as coerce_to_html_attrs,
-    _kebab_to_snake,
     HasHTMLDunder,
     AttributesDict,
+    _prep_component_kwargs,
 )
 from .callables import get_callable_info
 
@@ -134,45 +134,6 @@ def interpolate_attrs(
     bf.append(attrs_str)
 
 
-def _prep_cinfo(
-    component_callable: Callable, attrs: AttributesDict, system: dict[str, object]
-):
-    # @DESIGN: This is lifted from the processor and then grossified.
-    # Not sure this will work out but maybe we'd unify these.
-    callable_info = get_callable_info(component_callable)
-
-    if callable_info.requires_positional:
-        raise TypeError(
-            "Component callables cannot have required positional arguments."
-        )
-
-    kwargs: AttributesDict = {}
-
-    # Inject system kwargs first.
-    if system:
-        if callable_info.kwargs:
-            kwargs.update(system)
-        else:
-            for kw in system:
-                if kw in callable_info.named_params:
-                    kwargs[kw] = system[kw]
-
-    # Plaster attributes in over top of system kwargs.
-    for attr_name, attr_value in attrs.items():
-        snake_name = _kebab_to_snake(attr_name)
-        if snake_name in callable_info.named_params or callable_info.kwargs:
-            kwargs[snake_name] = attr_value
-
-    # Check to make sure we've fully satisfied the callable's requirements
-    missing = callable_info.required_named_params - kwargs.keys()
-    if missing:
-        raise TypeError(
-            f"Missing required parameters for component: {', '.join(missing)}"
-        )
-
-    return kwargs
-
-
 type InterpolateComponentInfo = tuple[str, Sequence[TAttribute], int, int | None, int]
 
 
@@ -211,7 +172,8 @@ def interpolate_component(
         children=children_template  # @DESIGN: children_struct=children_struct_t ?
     )
     # @DESIGN: Determine return signature from callable info (cached inspection) ?
-    kwargs = _prep_cinfo(component_callable, resolved_attrs, system_dict)
+    callable_info = get_callable_info(component_callable)
+    kwargs = _prep_component_kwargs(callable_info, resolved_attrs, system=system_dict)
     res = component_callable(**kwargs)
     # @DESIGN: Determine return signature via runtime inspection?
     if isinstance(res, tuple):

From 285ab75b02e982ee561c8ec6b2fcf9764ce80b09 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 18 Jan 2026 19:00:06 -0800
Subject: [PATCH 46/81] Apply second call to finish invoking class components.

---
 tdom/transformer.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index b605bf5..d616cfd 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -175,6 +175,13 @@ def interpolate_component(
     callable_info = get_callable_info(component_callable)
     kwargs = _prep_component_kwargs(callable_info, resolved_attrs, system=system_dict)
     res = component_callable(**kwargs)
+
+    # @DESIGN: callable or has_attr('__call__') for class components?
+    if callable(res):
+        # Class components are built and returned and then need to be called
+        # to get their template.
+        res = res()
+
     # @DESIGN: Determine return signature via runtime inspection?
     if isinstance(res, tuple):
         result_template, comp_info = res

From 18a7576fff3519a50dc954db53e8e646bdb64877 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 18 Jan 2026 21:58:49 -0800
Subject: [PATCH 47/81] Add class component example and add runtime checks to
 component return value.

---
 tdom/transformer.py      | 41 ++++++++++++++++++++++----
 tdom/transformer_test.py | 62 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+), 5 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index d616cfd..96ffa71 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -174,6 +174,16 @@ def interpolate_component(
     # @DESIGN: Determine return signature from callable info (cached inspection) ?
     callable_info = get_callable_info(component_callable)
     kwargs = _prep_component_kwargs(callable_info, resolved_attrs, system=system_dict)
+
+    # @DESIGN: We can try to wrap this type resolution up but it is
+    # hard to tell component authors what should be returned if we have this
+    # union, and this is actually the simplified one without iterable, bool or
+    # Node.
+
+    # Component() ->
+    # None | Template | tuple[None | Template, dict[str, object]] |
+    # Callable[[], None | Template | tuple[None | Template, dict[str, object]]]
+
     res = component_callable(**kwargs)
 
     # @DESIGN: callable or has_attr('__call__') for class components?
@@ -184,17 +194,34 @@ def interpolate_component(
 
     # @DESIGN: Determine return signature via runtime inspection?
     if isinstance(res, tuple):
-        result_template, comp_info = res
+        if len(res) != 2:
+            raise ValueError(
+                f"Tuple form of component return value must be len() 2, not: {len(res)}"
+            )
+        else:
+            result_template, comp_info = res
+
+        # @DESIGN: Use open-ended dict for opt-in second return argument?
         context_values = comp_info.get("context_values", ()) if comp_info else ()
+        for entry in context_values:
+            if not isinstance(entry, tuple):
+                raise ValueError(
+                    f"Entries for context_values must be 2-tuples but found type: {type(entry)}."
+                )
+            elif len(entry) != 2:
+                raise ValueError(
+                    f"Entries for context_values must be 2-tuples but found len(): {len(entry)}."
+                )
+            elif not isinstance(entry[0], ContextVar):
+                raise ValueError(
+                    f"Invalid context variable in component return value: {type(entry[0])}"
+                )
     else:
         result_template = res
         comp_info = None
         context_values = ()
 
-    # @DESIGN: Use open-ended dict for opt-in second return argument?
-    context_values = comp_info.get("context_values", ()) if comp_info else ()
-
-    if result_template:
+    if isinstance(result_template, Template):
         result_struct = render_api.transform_api.transform_template(result_template)
         if context_values:
             walker = render_api.walk_template_with_context(
@@ -203,6 +230,10 @@ def interpolate_component(
         else:
             walker = render_api.walk_template(bf, result_template, result_struct)
         return (container_tag, iter(walker))
+    elif result_template is None:
+        pass
+    else:
+        raise ValueError(f"Unknown component return value: {type(result_template)}")
 
 
 type InterpolateRawTextInfo = tuple[str, Template]
diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 589b743..0699fc5 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -3,6 +3,9 @@
 from markupsafe import Markup, escape as markupsafe_escape
 import typing as t
 import pytest
+from dataclasses import dataclass
+from collections.abc import Callable
+from itertools import chain
 
 from .transformer import (
     render_service_factory,
@@ -340,3 +343,62 @@ def test_escape_structured_text():
         render_api.render_template(content_t)
         == f"<div>{LT}script{GT}console.log({DQ}123!{DQ});{LT}/script{GT}</div>"
     )
+
+
+@dataclass
+class Pager:
+    left_pages: tuple = ()
+    page: int = 0
+    right_pages: tuple = ()
+    prev_page: int | None = None
+    next_page: int | None = None
+
+
+@dataclass
+class PagerDisplay:
+    pager: Pager
+    paginate_url: Callable[[int], str]
+    root_classes: tuple[str, ...] = ("cb", "tc", "w-100")
+    part_classes: tuple[str, ...] = ("dib", "pa1")
+
+    def __call__(self) -> Template:
+        parts = [t"<div class={self.root_classes}>"]
+        if self.pager.prev_page:
+            parts.append(
+                t"<a class={self.part_classes} href={self.paginate_url(self.pager.prev_page)}>Prev</a>"
+            )
+        for left_page in self.pager.left_pages:
+            parts.append(
+                t'<a class={self.part_classes} href="{self.paginate_url(left_page)}">{left_page}</a>'
+            )
+        parts.append(t"<span class={self.part_classes}>{self.pager.page}</span>")
+        for right_page in self.pager.right_pages:
+            parts.append(
+                t'<a class={self.part_classes} href="{self.paginate_url(right_page)}">{right_page}</a>'
+            )
+        if self.pager.next_page:
+            parts.append(
+                t"<a class={self.part_classes} href={self.paginate_url(self.pager.next_page)}>Next</a>"
+            )
+        parts.append(t"</div>")
+        return Template(*chain.from_iterable(parts))
+
+
+def test_class_component():
+    def paginate_url(page):
+        return f"/pages?{page}"
+
+    def Footer(pager, paginate_url, footer_classes=("footer",)):
+        return t"<div class={footer_classes}><{PagerDisplay} pager={pager} paginate_url={paginate_url} /></div>"
+
+    pager = Pager(
+        left_pages=(1, 2), page=3, right_pages=(4, 5), next_page=6, prev_page=None
+    )
+    content_t = t"<{Footer} pager={pager} paginate_url={paginate_url} />"
+    render_api = render_service_factory()
+    res = render_api.render_template(content_t)
+    print(res)
+    assert (
+        res
+        == '<div class="footer"><div class="cb tc w-100"><a href="/pages?1" class="dib pa1">1</a><a href="/pages?2" class="dib pa1">2</a><span class="dib pa1">3</span><a href="/pages?4" class="dib pa1">4</a><a href="/pages?5" class="dib pa1">5</a><a href="/pages?6" class="dib pa1">Next</a></div></div>'
+    )

From ef6b0df5d41946e48da49006216f4a23e2486b02 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 18 Jan 2026 23:07:14 -0800
Subject: [PATCH 48/81] Fix url in test example.

---
 tdom/transformer_test.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 0699fc5..2b2dd57 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -385,10 +385,10 @@ def __call__(self) -> Template:
 
 
 def test_class_component():
-    def paginate_url(page):
-        return f"/pages?{page}"
+    def paginate_url(page: int) -> str:
+        return f"/pages?page={page}"
 
-    def Footer(pager, paginate_url, footer_classes=("footer",)):
+    def Footer(pager, paginate_url, footer_classes=("footer",)) -> Template:
         return t"<div class={footer_classes}><{PagerDisplay} pager={pager} paginate_url={paginate_url} /></div>"
 
     pager = Pager(
@@ -400,5 +400,5 @@ def Footer(pager, paginate_url, footer_classes=("footer",)):
     print(res)
     assert (
         res
-        == '<div class="footer"><div class="cb tc w-100"><a href="/pages?1" class="dib pa1">1</a><a href="/pages?2" class="dib pa1">2</a><span class="dib pa1">3</span><a href="/pages?4" class="dib pa1">4</a><a href="/pages?5" class="dib pa1">5</a><a href="/pages?6" class="dib pa1">Next</a></div></div>'
+        == '<div class="footer"><div class="cb tc w-100"><a href="/pages?page=1" class="dib pa1">1</a><a href="/pages?page=2" class="dib pa1">2</a><span class="dib pa1">3</span><a href="/pages?page=4" class="dib pa1">4</a><a href="/pages?page=5" class="dib pa1">5</a><a href="/pages?page=6" class="dib pa1">Next</a></div></div>'
     )

From 47ea44ae03b08bb6958a360d72fd9713db803357 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Mon, 19 Jan 2026 14:14:57 -0800
Subject: [PATCH 49/81] Use inspect.is_class to build then call class
 components.

---
 tdom/transformer.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 96ffa71..376475e 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -7,6 +7,7 @@
 from contextvars import ContextVar, Token
 import functools
 from markupsafe import Markup
+import inspect
 
 from .format import format_interpolation
 from .parser import TemplateParser, HTMLAttributesDict
@@ -184,13 +185,12 @@ def interpolate_component(
     # None | Template | tuple[None | Template, dict[str, object]] |
     # Callable[[], None | Template | tuple[None | Template, dict[str, object]]]
 
-    res = component_callable(**kwargs)
-
-    # @DESIGN: callable or has_attr('__call__') for class components?
-    if callable(res):
+    if inspect.isclass(component_callable):
         # Class components are built and returned and then need to be called
         # to get their template.
-        res = res()
+        res = component_callable(**kwargs)()
+    else:
+        res = component_callable(**kwargs)
 
     # @DESIGN: Determine return signature via runtime inspection?
     if isinstance(res, tuple):

From 1b5d8b206aa8367d9e0e24f02c4632f6a339ff10 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Mon, 19 Jan 2026 14:21:14 -0800
Subject: [PATCH 50/81] Document component return value.

---
 tdom/transformer.py | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 376475e..192d57c 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -136,6 +136,12 @@ def interpolate_attrs(
 
 
 type InterpolateComponentInfo = tuple[str, Sequence[TAttribute], int, int | None, int]
+type ComponentReturnValueSimple = None | Template
+type ComponentReturnConfig = dict[str, object]
+type ComponentReturnValue = (
+    ComponentReturnValueSimple
+    | tuple[ComponentReturnValueSimple, ComponentReturnConfig]
+)
 
 
 def interpolate_component(
@@ -188,9 +194,9 @@ def interpolate_component(
     if inspect.isclass(component_callable):
         # Class components are built and returned and then need to be called
         # to get their template.
-        res = component_callable(**kwargs)()
+        res = t.cast(ComponentReturnValue, component_callable(**kwargs)())
     else:
-        res = component_callable(**kwargs)
+        res = t.cast(ComponentReturnValue, component_callable(**kwargs))
 
     # @DESIGN: Determine return signature via runtime inspection?
     if isinstance(res, tuple):
@@ -203,6 +209,10 @@ def interpolate_component(
 
         # @DESIGN: Use open-ended dict for opt-in second return argument?
         context_values = comp_info.get("context_values", ()) if comp_info else ()
+        if not isinstance(context_values, tuple):
+            raise TypeError(
+                f"Context values must be a tuple, found {type(context_values)}."
+            )
         for entry in context_values:
             if not isinstance(entry, tuple):
                 raise ValueError(

From 08d543a03f4dc49bfcce0b4102afb5ca3ee2350b Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Mon, 19 Jan 2026 14:37:31 -0800
Subject: [PATCH 51/81] Make context_values typing work with uv.

---
 tdom/transformer.py | 49 ++++++++++++++++++++++++++-------------------
 1 file changed, 28 insertions(+), 21 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 192d57c..0f9e2ab 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -206,29 +206,36 @@ def interpolate_component(
             )
         else:
             result_template, comp_info = res
-
-        # @DESIGN: Use open-ended dict for opt-in second return argument?
-        context_values = comp_info.get("context_values", ()) if comp_info else ()
-        if not isinstance(context_values, tuple):
-            raise TypeError(
-                f"Context values must be a tuple, found {type(context_values)}."
-            )
-        for entry in context_values:
-            if not isinstance(entry, tuple):
-                raise ValueError(
-                    f"Entries for context_values must be 2-tuples but found type: {type(entry)}."
-                )
-            elif len(entry) != 2:
-                raise ValueError(
-                    f"Entries for context_values must be 2-tuples but found len(): {len(entry)}."
-                )
-            elif not isinstance(entry[0], ContextVar):
-                raise ValueError(
-                    f"Invalid context variable in component return value: {type(entry[0])}"
+            # @DESIGN: Use open-ended dict for opt-in second return argument?
+            context_values = comp_info.get("context_values", ())
+            if not isinstance(context_values, tuple):
+                raise TypeError(
+                    f"Context values must be a tuple, found {type(context_values)}."
                 )
+            # @TYPING: We need runtime checks for typing but uv does not
+            # pick them up so we put each item back into a list and then back into a
+            # tuple and for some reason that works...
+            cvs = []
+            for entry in context_values:
+                if not isinstance(entry, tuple):
+                    raise ValueError(
+                        f"Entries for context_values must be 2-tuples but found type: {type(entry)}."
+                    )
+                elif len(entry) != 2:
+                    raise ValueError(
+                        f"Entries for context_values must be 2-tuples but found len(): {len(entry)}."
+                    )
+                elif not isinstance(entry[0], ContextVar):
+                    raise ValueError(
+                        f"Invalid context variable in component return value: {type(entry[0])}"
+                    )
+                else:
+                    # @TYPING: See below
+                    cvs.append(entry)
+            # @TYPING: Hack to make uv pickup runtime type checks, pyright seems to work ok without.
+            context_values = tuple(cvs)
     else:
         result_template = res
-        comp_info = None
         context_values = ()
 
     if isinstance(result_template, Template):
@@ -720,7 +727,7 @@ def walk_template_with_context(
         bf: list[str],
         template: Template,
         struct_t: Template,
-        context_values: tuple[tuple[ContextVar, object]] | None = None,
+        context_values: tuple[tuple[ContextVar, object], ...] = (),
     ) -> Iterable[tuple[InterpolatorProto, Template, InterpolateInfo]]:
         if context_values:
             cm = ContextVarSetter(context_values=context_values)

From 32adb685b5994439eba7eac41776de54e10957f5 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Tue, 20 Jan 2026 22:15:29 -0800
Subject: [PATCH 52/81] Make name more consistent.

---
 tdom/processor.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/tdom/processor.py b/tdom/processor.py
index ff9b116..9bb055d 100644
--- a/tdom/processor.py
+++ b/tdom/processor.py
@@ -440,7 +440,7 @@ def _kebab_to_snake(name: str) -> str:
 def _prep_component_kwargs(
     callable_info: CallableInfo,
     attrs: AttributesDict,
-    system: dict[str, object],
+    system_kwargs: dict[str, object],
     kebab_to_snake: Callable[[str], str] = _kebab_to_snake,
 ):
     if callable_info.requires_positional:
@@ -456,7 +456,7 @@ def _prep_component_kwargs(
         if snake_name in callable_info.named_params or callable_info.kwargs:
             kwargs[snake_name] = attr_value
 
-    for attr_name, attr_value in system.items():
+    for attr_name, attr_value in system_kwargs.items():
         if attr_name in callable_info.named_params or callable_info.kwargs:
             kwargs[attr_name] = attr_value
 
@@ -511,7 +511,7 @@ def _invoke_component(
     callable_info = get_callable_info(value)
 
     kwargs = _prep_component_kwargs(
-        callable_info, attrs, system={"children": tuple(children)}
+        callable_info, attrs, system_kwargs={"children": tuple(children)}
     )
 
     result = value(**kwargs)

From e2662d55cb5cf62382b52b330d904253a002e073 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Tue, 20 Jan 2026 22:21:15 -0800
Subject: [PATCH 53/81] Try to refactor a unified invoke component.

---
 tdom/transformer.py | 190 ++++++++++++++++++++++++--------------------
 1 file changed, 104 insertions(+), 86 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 0f9e2ab..8152ef7 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -144,56 +144,12 @@ def interpolate_attrs(
 )
 
 
-def interpolate_component(
-    render_api: RenderService,
-    bf: list[str],
-    last_container_tag: str | None,
-    template: Template,
-    ip_info: InterpolateInfo,
-) -> RenderQueueItem | None:
-    (container_tag, attrs, start_i_index, end_i_index, body_start_s_index) = t.cast(
-        InterpolateComponentInfo, ip_info
-    )
-    if start_i_index != end_i_index and end_i_index is not None:
-        # @DESIGN: We extract the children template from the original outer template.
-        children_template = render_api.transform_api.extract_children_template(
-            template, body_start_s_index, end_i_index
-        )
-    else:
-        children_template = Template("")
-    # @DESIGN: children_struct_t = render_api.transform_api.transform_template(children_template) ?
-    resolved_attrs = render_api.resolve_attrs(attrs, template)
-    start_i = template.interpolations[start_i_index]
-    component_callable = start_i.value
-    if (
-        start_i_index != end_i_index
-        and end_i_index is not None
-        and component_callable != template.interpolations[end_i_index].value
-    ):
-        raise TypeError(
-            "Component callable in start tag must match component callable in end tag."
-        )
-
-    # @DESIGN: Inject system vars via manager?
-    system_dict = render_api.get_system(
-        children=children_template  # @DESIGN: children_struct=children_struct_t ?
-    )
-    # @DESIGN: Determine return signature from callable info (cached inspection) ?
-    callable_info = get_callable_info(component_callable)
-    kwargs = _prep_component_kwargs(callable_info, resolved_attrs, system=system_dict)
-
-    # @DESIGN: We can try to wrap this type resolution up but it is
-    # hard to tell component authors what should be returned if we have this
-    # union, and this is actually the simplified one without iterable, bool or
-    # Node.
-
-    # Component() ->
-    # None | Template | tuple[None | Template, dict[str, object]] |
-    # Callable[[], None | Template | tuple[None | Template, dict[str, object]]]
-
+def invoke_component(
+    component_callable: Callable[..., ComponentReturnValue] | Callable[..., Callable[[], ComponentReturnValue]],
+    kwargs: dict[str, object],
+) -> tuple[ComponentReturnValueSimple, ComponentReturnConfig]:
+    # @DESIGN: Can we just solve this before calling in here?  
     if inspect.isclass(component_callable):
-        # Class components are built and returned and then need to be called
-        # to get their template.
         res = t.cast(ComponentReturnValue, component_callable(**kwargs)())
     else:
         res = t.cast(ComponentReturnValue, component_callable(**kwargs))
@@ -238,7 +194,54 @@ def interpolate_component(
         result_template = res
         context_values = ()
 
+    return result_template, context_values
+
+
+def interpolate_component(
+    render_api: RenderService,
+    bf: list[str],
+    last_container_tag: str | None,
+    template: Template,
+    ip_info: InterpolateInfo,
+) -> RenderQueueItem | None:
+    (container_tag, attrs, start_i_index, end_i_index, body_start_s_index) = t.cast(
+        InterpolateComponentInfo, ip_info
+    )
+    start_i = template.interpolations[start_i_index]
+    component_callable = start_i.value
+    if start_i_index != end_i_index and end_i_index is not None:
+        # @DESIGN: We extract the children template from the original outer template.
+        children_template = extract_embedded_template(
+            template, body_start_s_index, end_i_index
+        )
+        if component_callable != template.interpolations[end_i_index].value:
+            raise TypeError(
+                "Component callable in start tag must match component callable in end tag."
+                )
+    else:
+        children_template = Template("")
+
+    # @DESIGN: Inject system vars via manager?
+    system_kwargs = render_api.get_system(
+        children=children_template  # @DESIGN: children_struct=children_struct_t ?
+    )
+
+    if not callable(component_callable):
+        raise TypeError('Component callable must be callable.')
+
+    kwargs = _prep_component_kwargs(
+        get_callable_info(component_callable),
+        resolve_dynamic_attrs(attrs, template.interpolations),
+        system_kwargs=system_kwargs)
+
+    result_template, context_values = invoke_component(
+        component_callable,
+        kwargs)
+
     if isinstance(result_template, Template):
+        if result_template.strings == ('',):
+            # DO NOTHING
+            return
         result_struct = render_api.transform_api.transform_template(result_template)
         if context_values:
             walker = render_api.walk_template_with_context(
@@ -248,7 +251,8 @@ def interpolate_component(
             walker = render_api.walk_template(bf, result_template, result_struct)
         return (container_tag, iter(walker))
     elif result_template is None:
-        pass
+        # DO NOTHING
+        return
     else:
         raise ValueError(f"Unknown component return value: {type(result_template)}")
 
@@ -568,45 +572,59 @@ def has_dynamic_attrs(self, attrs: t.Sequence[TAttribute]) -> bool:
                 return True
         return False
 
-    def extract_children_template(
-        self, template: Template, body_start_s_index: int, end_i_index: int
-    ) -> Template:
-        """
-        Extract the template parts exclusively from start tag to end tag.
 
-        Note that interpolations INSIDE the start tag make this more complex
-        than just "the `s_index` after the component callable's `i_index`".
+def determine_body_start_s_index(tcomp):
+    """
+    Calculate the strings index when the embedded template starts after a component start tag.
 
-        Example:
-        ```python
-        template = (
-            t'<{comp} attr={attr}>'
-                t'<div>{content} <span>{footer}</span></div>'
-            t'</{comp}>'
-        )
-        assert self.extract_children_template(template, 2, 4) == (
+    This doesn't actually know or care if the component has a body it just
+    counts past the dynamic (non-literal) attributes and returns the first strings index
+    offset by interpolation index for the component callable itself.
+    """
+    return (tcomp.start_i_index
+            + 1
+            + len([1 for attr in tcomp.attrs if not isinstance(attr, TLiteralAttribute)])
+            )
+
+
+def extract_embedded_template(template: Template, body_start_s_index: int, end_i_index: int) -> Template:
+    """
+    Extract the template parts exclusively from start tag to end tag.
+
+    Note that interpolations INSIDE the start tag make this more complex
+    than just "the `s_index` after the component callable's `i_index`".
+
+    Example:
+    ```python
+    template = (
+        t'<{comp} attr={attr}>'
             t'<div>{content} <span>{footer}</span></div>'
-        )
-        starttag = t'<{comp} attr={attr}>'
-        endtag = t'</{comp}>'
-        assert template == starttag + self.extract_children_template(template, 2, 4) + endtag
-        ```
-        @DESIGN: "There must be a better way."
-        """
-        # Copy the parts out of the containing template.
-        index = body_start_s_index
-        last_s_index = end_i_index
-        parts = []
-        while index <= last_s_index:
-            parts.append(template.strings[index])
-            if index != last_s_index:
-                parts.append(template.interpolations[index])
-            index += 1
-        # Now trim the first part to the end of the opening tag.
-        parts[0] = parts[0][parts[0].find(">") + 1 :]
-        # Now trim the last part (could also be the first) to the start of the closing tag.
-        parts[-1] = parts[-1][: parts[-1].rfind("<")]
-        return Template(*parts)
+        t'</{comp}>'
+    )
+    assert extract_children_template(template, 2, 4) == (
+        t'<div>{content} <span>{footer}</span></div>'
+    )
+    starttag = t'<{comp} attr={attr}>'
+    endtag = t'</{comp}>'
+    assert template == starttag + extract_children_template(template, 2, 4) + endtag
+    ```
+    @DESIGN: "There must be a better way."
+    """
+    # Copy the parts out of the containing template.
+    index = body_start_s_index
+    last_s_index = end_i_index
+    parts = []
+    while index <= last_s_index:
+        parts.append(template.strings[index])
+        if index != last_s_index:
+            parts.append(template.interpolations[index])
+        index += 1
+    # Now trim the first part to the end of the opening tag.
+    parts[0] = parts[0][parts[0].find(">") + 1 :]
+    # Now trim the last part (could also be the first) to the start of the closing tag.
+    parts[-1] = parts[-1][: parts[-1].rfind("<")]
+    return Template(*parts)
+
 
 
 @dataclass(frozen=True)

From 591a15faea984b1dd72e9bc2d00eb9c4d2e66657 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Tue, 20 Jan 2026 22:30:23 -0800
Subject: [PATCH 54/81] Fix typing.

---
 tdom/transformer.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 8152ef7..fc3b732 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -145,9 +145,9 @@ def interpolate_attrs(
 
 
 def invoke_component(
-    component_callable: Callable[..., ComponentReturnValue] | Callable[..., Callable[[], ComponentReturnValue]],
+    component_callable: Callable, #@TODO: Callable[..., ComponentReturnValue] | Callable[..., Callable[[], ComponentReturnValue]],
     kwargs: dict[str, object],
-) -> tuple[ComponentReturnValueSimple, ComponentReturnConfig]:
+) -> tuple[ComponentReturnValueSimple, tuple[tuple[ContextVar, object], ...]]:
     # @DESIGN: Can we just solve this before calling in here?  
     if inspect.isclass(component_callable):
         res = t.cast(ComponentReturnValue, component_callable(**kwargs)())

From 0fe98bd8409bd5724cc28d0a567d75fc7de8c5e4 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Tue, 20 Jan 2026 22:31:21 -0800
Subject: [PATCH 55/81] Format.

---
 tdom/transformer.py | 30 ++++++++++++++++--------------
 1 file changed, 16 insertions(+), 14 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index fc3b732..ef837d5 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -145,10 +145,10 @@ def interpolate_attrs(
 
 
 def invoke_component(
-    component_callable: Callable, #@TODO: Callable[..., ComponentReturnValue] | Callable[..., Callable[[], ComponentReturnValue]],
+    component_callable: Callable,  # @TODO: Callable[..., ComponentReturnValue] | Callable[..., Callable[[], ComponentReturnValue]],
     kwargs: dict[str, object],
 ) -> tuple[ComponentReturnValueSimple, tuple[tuple[ContextVar, object], ...]]:
-    # @DESIGN: Can we just solve this before calling in here?  
+    # @DESIGN: Can we just solve this before calling in here?
     if inspect.isclass(component_callable):
         res = t.cast(ComponentReturnValue, component_callable(**kwargs)())
     else:
@@ -217,7 +217,7 @@ def interpolate_component(
         if component_callable != template.interpolations[end_i_index].value:
             raise TypeError(
                 "Component callable in start tag must match component callable in end tag."
-                )
+            )
     else:
         children_template = Template("")
 
@@ -227,19 +227,18 @@ def interpolate_component(
     )
 
     if not callable(component_callable):
-        raise TypeError('Component callable must be callable.')
+        raise TypeError("Component callable must be callable.")
 
     kwargs = _prep_component_kwargs(
         get_callable_info(component_callable),
         resolve_dynamic_attrs(attrs, template.interpolations),
-        system_kwargs=system_kwargs)
+        system_kwargs=system_kwargs,
+    )
 
-    result_template, context_values = invoke_component(
-        component_callable,
-        kwargs)
+    result_template, context_values = invoke_component(component_callable, kwargs)
 
     if isinstance(result_template, Template):
-        if result_template.strings == ('',):
+        if result_template.strings == ("",):
             # DO NOTHING
             return
         result_struct = render_api.transform_api.transform_template(result_template)
@@ -581,13 +580,16 @@ def determine_body_start_s_index(tcomp):
     counts past the dynamic (non-literal) attributes and returns the first strings index
     offset by interpolation index for the component callable itself.
     """
-    return (tcomp.start_i_index
-            + 1
-            + len([1 for attr in tcomp.attrs if not isinstance(attr, TLiteralAttribute)])
-            )
+    return (
+        tcomp.start_i_index
+        + 1
+        + len([1 for attr in tcomp.attrs if not isinstance(attr, TLiteralAttribute)])
+    )
 
 
-def extract_embedded_template(template: Template, body_start_s_index: int, end_i_index: int) -> Template:
+def extract_embedded_template(
+    template: Template, body_start_s_index: int, end_i_index: int
+) -> Template:
     """
     Extract the template parts exclusively from start tag to end tag.
 

From 5e3025007ef6ea2ca7ba9780f67ce4b8a9431e41 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 22 Jan 2026 22:44:56 -0800
Subject: [PATCH 56/81] Use resolve_text_without_recursion as top-level
 function.

---
 tdom/transformer.py | 119 +++++++++++++++++++++++---------------------
 1 file changed, 63 insertions(+), 56 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index ef837d5..3052932 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -112,7 +112,7 @@ def interpolate_comment(
     assert container_tag == "<!--"
     bf.append(
         render_api.escape_html_comment(
-            render_api.resolve_text_without_recursion(
+            resolve_text_without_recursion(
                 template, container_tag, comment_t
             )
         )
@@ -270,7 +270,7 @@ def interpolate_raw_text(
     bf.append(
         render_api.escape_html_content_in_tag(
             container_tag,
-            render_api.resolve_text_without_recursion(
+            resolve_text_without_recursion(
                 template, container_tag, content_t
             ),
         )
@@ -290,7 +290,7 @@ def interpolate_escapable_raw_text(
     container_tag, content_t = t.cast(InterpolateEscapableRawTextInfo, ip_info)
     bf.append(
         render_api.escape_html_text(
-            render_api.resolve_text_without_recursion(
+            resolve_text_without_recursion(
                 template, container_tag, content_t
             )
         )
@@ -572,6 +572,66 @@ def has_dynamic_attrs(self, attrs: t.Sequence[TAttribute]) -> bool:
         return False
 
 
+def resolve_text_without_recursion(
+    template: Template, container_tag: str, content_t: Template
+) -> str | None:
+    """
+    Resolve the text in the given template without recursing into more structured text.
+
+    This can be bypassed by interpolating an exact match with an object with `__html__()`.
+
+    A non-exact match is not allowed because we cannot process escaping
+    across the boundary between other content and the pass-through content.
+    """
+    # @TODO: We should use formatting but not in a way that
+    # auto-interpolates structured values.
+
+    if len(content_t.interpolations) == 1 and content_t.strings == ("", ""):
+        i_index = t.cast(int, content_t.interpolations[0].value)
+        value = template.interpolations[i_index].value
+        if value is None:
+            return None
+        elif type(value) == str: #type() check to avoid subclasses, probably something smarter here
+            return value
+        elif hasattr(value, "__html__"):
+            return Markup(value.__html__())
+        elif not isinstance(value, str) and isinstance(value, (Template, Iterable)):
+            raise ValueError(
+                f"Recursive includes are not supported within {container_tag}"
+            )
+        else:
+            return str(value)
+    else:
+        text = []
+        for part in content_t:
+            if isinstance(part, str):
+                if part:
+                    text.append(part)
+                continue
+            value = template.interpolations[part.value].value
+            if value is None:
+                continue
+            elif type(value) == str: #type() check to avoid subclasses, probably something smarter here
+                if value:
+                    text.append(value)
+            elif not isinstance(value, str) and isinstance(value, (Template, Iterable)):
+                raise ValueError(
+                    f"Recursive includes are not supported within {container_tag}"
+                )
+            elif hasattr(value, "__html__"):
+                raise ValueError(
+                    f"Non-exact trusted interpolations are not supported within {container_tag}"
+                )
+            else:
+                value_str = str(value)
+                if value_str:
+                    text.append(value_str)
+        if text:
+            return "".join(text)
+        else:
+            return None
+
+
 def determine_body_start_s_index(tcomp):
     """
     Calculate the strings index when the embedded template starts after a component start tag.
@@ -684,59 +744,6 @@ def render_template(
                     break
         return "".join(bf)
 
-    def resolve_text_without_recursion(
-        self, template: Template, container_tag: str, content_t: Template
-    ) -> str:
-        """
-        Resolve the text in the given template without recursing into more structured text.
-
-        This can be bypassed by interpolating an exact match with an object with `__html__()`.
-
-        A non-exact match is not allowed because we cannot process escaping
-        across the boundary between other content and the pass-through content.
-        """
-        if len(content_t.interpolations) == 1 and content_t.strings == ("", ""):
-            i_index = t.cast(int, content_t.interpolations[0].value)
-            value = template.interpolations[i_index].value
-            if value is None or value is False:
-                return ""
-            elif isinstance(value, str):
-                return value
-            elif hasattr(value, "__html__"):
-                return Markup(value.__html__())
-            elif isinstance(value, (Template, Iterable)):
-                raise ValueError(
-                    f"Recursive includes are not supported within {container_tag}"
-                )
-            else:
-                return str(value)
-        else:
-            text = []
-            for part in content_t:
-                if isinstance(part, str):
-                    if part:
-                        text.append(part)
-                    continue
-                value = template.interpolations[part.value].value
-                if value is None or value is False:
-                    continue
-                elif isinstance(value, str):
-                    if value:
-                        text.append(value)
-                elif isinstance(value, (Template, Iterable)):
-                    raise ValueError(
-                        f"Recursive includes are not supported within {container_tag}"
-                    )
-                elif hasattr(value, "__html__"):
-                    raise ValueError(
-                        f"Non-exact trusted interpolations are not supported within {container_tag}"
-                    )
-                else:
-                    value_str = str(value)
-                    if value_str:
-                        text.append(value_str)
-            return "".join(text)
-
     def resolve_attrs(
         self, attrs: t.Sequence[TAttribute], template: Template
     ) -> AttributesDict:

From c7b7185ad21666565575068e749265a440b7dcbc Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Thu, 22 Jan 2026 23:09:51 -0800
Subject: [PATCH 57/81] Formatting.

---
 tdom/transformer.py | 20 +++++++++-----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 3052932..826e554 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -112,9 +112,7 @@ def interpolate_comment(
     assert container_tag == "<!--"
     bf.append(
         render_api.escape_html_comment(
-            resolve_text_without_recursion(
-                template, container_tag, comment_t
-            )
+            resolve_text_without_recursion(template, container_tag, comment_t)
         )
     )
 
@@ -270,9 +268,7 @@ def interpolate_raw_text(
     bf.append(
         render_api.escape_html_content_in_tag(
             container_tag,
-            resolve_text_without_recursion(
-                template, container_tag, content_t
-            ),
+            resolve_text_without_recursion(template, container_tag, content_t),
         )
     )
 
@@ -290,9 +286,7 @@ def interpolate_escapable_raw_text(
     container_tag, content_t = t.cast(InterpolateEscapableRawTextInfo, ip_info)
     bf.append(
         render_api.escape_html_text(
-            resolve_text_without_recursion(
-                template, container_tag, content_t
-            )
+            resolve_text_without_recursion(template, container_tag, content_t)
         )
     )
 
@@ -591,7 +585,9 @@ def resolve_text_without_recursion(
         value = template.interpolations[i_index].value
         if value is None:
             return None
-        elif type(value) == str: #type() check to avoid subclasses, probably something smarter here
+        elif (
+            type(value) is str
+        ):  # type() check to avoid subclasses, probably something smarter here
             return value
         elif hasattr(value, "__html__"):
             return Markup(value.__html__())
@@ -611,7 +607,9 @@ def resolve_text_without_recursion(
             value = template.interpolations[part.value].value
             if value is None:
                 continue
-            elif type(value) == str: #type() check to avoid subclasses, probably something smarter here
+            elif (
+                type(value) is str
+            ):  # type() check to avoid subclasses, probably something smarter here
                 if value:
                     text.append(value)
             elif not isinstance(value, str) and isinstance(value, (Template, Iterable)):

From cae1a5072edc544a89c71f9498cebf9020cda81a Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sat, 24 Jan 2026 00:18:45 -0800
Subject: [PATCH 58/81] Handle edge cases around html pedantry.

---
 tdom/transformer.py | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 826e554..462b3ef 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -405,6 +405,7 @@ class TransformService:
     escape_html_text: Callable = default_escape_html_text
 
     slash_void: bool = False  # Apply a xhtml-style slash to void html elements.
+    uppercase_doctype: bool = False  # DOCTYPE vs doctype
 
     def transform_template(self, template: Template) -> Template:
         """Transform the given template into a template for rendering."""
@@ -486,7 +487,10 @@ def streamer(
                 case EndTag(end_tag):
                     yield end_tag
                 case TDocumentType(text):
-                    yield f"<!doctype {text}>"
+                    if self.uppercase_doctype:
+                        yield f"<!DOCTYPE {text}>"
+                    else:
+                        yield f"<!doctype {text}>"
                 case TComment(ref):
                     text_t = Template(
                         *[
@@ -807,12 +811,12 @@ def __exit__(self, exc_type, exc_value, traceback):
             var_value[0].reset(self.tokens[idx])
 
 
-def render_service_factory():
-    return RenderService(transform_api=TransformService())
+def render_service_factory(transform_api_kwargs=None):
+    return RenderService(transform_api=TransformService(**(transform_api_kwargs or {})))
 
 
-def cached_render_service_factory():
-    return RenderService(transform_api=CachedTransformService())
+def cached_render_service_factory(transform_api_kwargs=None):
+    return RenderService(transform_api=CachedTransformService(**(transform_api_kwargs or {})))
 
 
 #

From b4448b38a5fff8cd49ad216916e4c36b900c7976 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sat, 24 Jan 2026 00:19:25 -0800
Subject: [PATCH 59/81] Format

---
 tdom/transformer.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 462b3ef..4224bc0 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -816,7 +816,9 @@ def render_service_factory(transform_api_kwargs=None):
 
 
 def cached_render_service_factory(transform_api_kwargs=None):
-    return RenderService(transform_api=CachedTransformService(**(transform_api_kwargs or {})))
+    return RenderService(
+        transform_api=CachedTransformService(**(transform_api_kwargs or {}))
+    )
 
 
 #

From 1df9b584b98791191b43364a7dd18c438f16c2f8 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 25 Jan 2026 00:13:17 -0800
Subject: [PATCH 60/81] Split invoke by strategy to try to cleanup typing.

---
 tdom/transformer.py | 43 +++++++++++++++++++++++++++++++++----------
 1 file changed, 33 insertions(+), 10 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 4224bc0..2e198a2 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -133,7 +133,6 @@ def interpolate_attrs(
     bf.append(attrs_str)
 
 
-type InterpolateComponentInfo = tuple[str, Sequence[TAttribute], int, int | None, int]
 type ComponentReturnValueSimple = None | Template
 type ComponentReturnConfig = dict[str, object]
 type ComponentReturnValue = (
@@ -142,16 +141,29 @@ def interpolate_attrs(
 )
 
 
-def invoke_component(
-    component_callable: Callable,  # @TODO: Callable[..., ComponentReturnValue] | Callable[..., Callable[[], ComponentReturnValue]],
+type ComponentClassSig = Callable[..., Callable[[], ComponentReturnValue]]
+
+
+def invoke_component_class(
+    component_callable: ComponentClassSig,
     kwargs: dict[str, object],
 ) -> tuple[ComponentReturnValueSimple, tuple[tuple[ContextVar, object], ...]]:
-    # @DESIGN: Can we just solve this before calling in here?
-    if inspect.isclass(component_callable):
-        res = t.cast(ComponentReturnValue, component_callable(**kwargs)())
-    else:
-        res = t.cast(ComponentReturnValue, component_callable(**kwargs))
+    return process_component_return_value(component_callable(**kwargs)())
+
+
+type ComponentFunctionSig = Callable[..., ComponentReturnValue]
+
+
+def invoke_component_function(
+    component_callable: ComponentFunctionSig,
+    kwargs: dict[str, object],
+) -> tuple[ComponentReturnValueSimple, tuple[tuple[ContextVar, object], ...]]:
+    return process_component_return_value(component_callable(**kwargs))
 
+
+def process_component_return_value(
+    res: ComponentReturnValue,
+) -> tuple[ComponentReturnValueSimple, tuple[tuple[ContextVar, object], ...]]:
     # @DESIGN: Determine return signature via runtime inspection?
     if isinstance(res, tuple):
         if len(res) != 2:
@@ -195,6 +207,9 @@ def invoke_component(
     return result_template, context_values
 
 
+type InterpolateComponentInfo = tuple[str, Sequence[TAttribute], int, int | None, int]
+
+
 def interpolate_component(
     render_api: RenderService,
     bf: list[str],
@@ -233,7 +248,16 @@ def interpolate_component(
         system_kwargs=system_kwargs,
     )
 
-    result_template, context_values = invoke_component(component_callable, kwargs)
+    if inspect.isclass(component_callable):
+        component_callable = t.cast(ComponentClassSig, component_callable)
+        result_template, context_values = invoke_component_class(
+            component_callable, kwargs
+        )
+    else:
+        component_callable = t.cast(ComponentFunctionSig, component_callable)
+        result_template, context_values = invoke_component_function(
+            component_callable, kwargs
+        )
 
     if isinstance(result_template, Template):
         if result_template.strings == ("",):
@@ -690,7 +714,6 @@ def extract_embedded_template(
     return Template(*parts)
 
 
-
 @dataclass(frozen=True)
 class RenderService:
     transform_api: TransformService

From 747cbcaa2b4863930e4a54ff9f6e512fb52204b2 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 25 Jan 2026 17:39:52 -0800
Subject: [PATCH 61/81] Remove unused import.

---
 tdom/transformer.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 2e198a2..a249c86 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -36,7 +36,6 @@
 from .processor import (
     _resolve_t_attrs as resolve_dynamic_attrs,
     _resolve_html_attrs as coerce_to_html_attrs,
-    HasHTMLDunder,
     AttributesDict,
     _prep_component_kwargs,
 )

From a93f73228592b504e676f1cfeeae8ae226029897 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 25 Jan 2026 17:41:27 -0800
Subject: [PATCH 62/81] Make text within certain tags more explicit.

---
 tdom/transformer.py | 224 ++++++++++++++++++++++++++++----------------
 1 file changed, 143 insertions(+), 81 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index a249c86..44313ad 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -277,17 +277,22 @@ def interpolate_component(
         raise ValueError(f"Unknown component return value: {type(result_template)}")
 
 
-type InterpolateRawTextInfo = tuple[str, Template]
+type InterpolateRawTextsFromTemplateInfo = tuple[str, Template]
 
 
-def interpolate_raw_text(
+def interpolate_raw_texts_from_template(
     render_api: RenderService,
     bf: list[str],
     last_container_tag: str | None,
     template: Template,
     ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    container_tag, content_t = t.cast(InterpolateRawTextInfo, ip_info)
+    """
+    Interpolate and join a template of raw texts together and escape them.
+
+    @NOTE: This interpolator expects a Template.
+    """
+    container_tag, content_t = t.cast(InterpolateRawTextsFromTemplateInfo, ip_info)
     bf.append(
         render_api.escape_html_content_in_tag(
             container_tag,
@@ -296,17 +301,24 @@ def interpolate_raw_text(
     )
 
 
-type InterpolateEscapableRawTextInfo = tuple[str, Template]
+type InterpolateEscapableRawTextsFromTemplateInfo = tuple[str, Template]
 
 
-def interpolate_escapable_raw_text(
+def interpolate_escapable_raw_texts_from_template(
     render_api: RenderService,
     bf: list[str],
     last_container_tag: str | None,
     template: Template,
     ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    container_tag, content_t = t.cast(InterpolateEscapableRawTextInfo, ip_info)
+    """
+    Interpolate and join a template of escapable raw texts together and escape them.
+
+    @NOTE: This interpolator expects a Template.
+    """
+    container_tag, content_t = t.cast(
+        InterpolateEscapableRawTextsFromTemplateInfo, ip_info
+    )
     bf.append(
         render_api.escape_html_text(
             resolve_text_without_recursion(template, container_tag, content_t)
@@ -314,104 +326,128 @@ def interpolate_escapable_raw_text(
     )
 
 
-type InterpolateStructTextInfo = tuple[str, int]
+type InterpolateNormalTextInfo = tuple[str, int]
 
 
-def interpolate_struct_text(
+def interpolate_normal_text_from_interpolation(
     render_api: RenderService,
     bf: list[str],
     last_container_tag: str | None,
     template: Template,
     ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    container_tag, ip_index = t.cast(InterpolateStructTextInfo, ip_info)
+    """
+    Interpolate a single normal text either into structured content or an escaped string.
+
+    @NOTE: This expects a SINGLE interpolation referenced via i_index.
+    """
+    container_tag, ip_index = t.cast(InterpolateNormalTextInfo, ip_info)
     value = format_interpolation(template.interpolations[ip_index])
-    return interpolate_text(
+    return interpolate_normal_text_from_value(
         render_api, bf, last_container_tag, template, (container_tag, value)
     )
 
 
-# @TODO: can we coerce this to still use typing even if we just str() everything ? -- `| object`
-type UserTextValueItem = None | str | Template | HasHTMLDunder
-# @TODO: See above about `| object`
-type UserTextValue = (
-    UserTextValueItem | Sequence[UserTextValueItem] | t.Iterable[UserTextValueItem]
-)
+type InterpolateNormalTextValueInfo = tuple[str | None, object]
 
 
-def interpolate_user_text(
+def interpolate_normal_text_from_value(
     render_api: RenderService,
     bf: list[str],
     last_container_tag: str | None,
     template: Template,
     ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    return interpolate_text(render_api, bf, last_container_tag, template, ip_info)
+    """
+    Resolve a single text value interpolated within a normal element.
+
+    @NOTE: This could be a str(), None, Iterable, Template or HasHTMLDunder.
+    """
+    container_tag, value = t.cast(InterpolateNormalTextValueInfo, ip_info)
+    if container_tag is None:
+        container_tag = last_container_tag
 
+    if isinstance(value, str):
+        # @NOTE: Must be subclass of str, if you want __html__ to work you need
+        # to wrap that object in markupsafe.Markup.
+        bf.append(render_api.escape_html_text(value))
+    elif isinstance(value, Template):
+        return (
+            container_tag,
+            iter(
+                render_api.walk_template(
+                    bf, value, render_api.transform_api.transform_template(value)
+                )
+            ),
+        )
+    elif isinstance(value, Iterable):
+        # If we don't guard against str instances then str subclasses will be
+        # treated as a sequence/iterable of chars.
+        return (
+            container_tag,
+            (
+                (
+                    interpolate_normal_text_from_value,
+                    template,
+                    (container_tag, v if v is not None else None),
+                )
+                for v in t.cast(Iterable, value)
+            ),
+        )
+    elif value is None:
+        # @DESIGN: Ignore None.
+        return
+    else:
+        # @DESIGN: Everything that isn't an object we recognize is
+        # coerced to a str() and emitted.
+        bf.append(render_api.escape_html_text(str(value)))
 
-type InterpolateTextInfo = tuple[str, object]
 
+type InterpolateDynamicTextsFromTemplateInfo = tuple[None, Template]
 
-def interpolate_text(
+
+def interpolate_dynamic_texts_from_template(
     render_api: RenderService,
     bf: list[str],
     last_container_tag: str | None,
     template: Template,
     ip_info: InterpolateInfo,
 ) -> RenderQueueItem | None:
-    container_tag, value = t.cast(InterpolateTextInfo, ip_info)
+    container_tag, text_t = t.cast(InterpolateDynamicTextsFromTemplateInfo, ip_info)
+    # Try to use the dynamic container if possible.
     if container_tag is None:
         container_tag = last_container_tag
-
-    if type(value) is str:  # ONLY native strings, not Markup/__html__, etc.
-        if container_tag not in ("style", "script", "title", "textarea", "<!--"):
-            bf.append(render_api.escape_html_text(value))
-        else:
-            # @TODO: How could this happen?
-            raise ValueError(
-                f"We cannot escape text within {container_tag} when multiple interpolations could occur."
-            )
-            # bf.append(render_api.escape_html_content_in_tag(container_tag, str(value)))
+    if container_tag is None:
+        raise NotImplementedError(
+            "We cannot interpolate texts without knowing what tag they are contained in."
+        )
+    elif container_tag in CDATA_CONTENT_ELEMENTS:
+        return interpolate_raw_texts_from_template(
+            render_api, bf, last_container_tag, template, (container_tag, text_t)
+        )
+    elif container_tag in RCDATA_CONTENT_ELEMENTS:
+        return interpolate_escapable_raw_texts_from_template(
+            render_api, bf, last_container_tag, template, (container_tag, text_t)
+        )
     else:
-        if isinstance(value, Template):
-            return (
-                container_tag,
-                iter(
-                    render_api.walk_template(
-                        bf, value, render_api.transform_api.transform_template(value)
-                    )
-                ),
-            )
-        elif not isinstance(value, str) and (
-            isinstance(value, t.Sequence) or hasattr(value, "__iter__")
-        ):
-            # If we don't guard against str instances then str subclasses will be
-            # treated as a sequence/iterable of chars.
-            return (
-                container_tag,
-                (
-                    (
-                        interpolate_user_text,
-                        template,
-                        (container_tag, v if v is not None else None),
-                    )
-                    for v in t.cast(Iterable, value)
-                ),
-            )
-        elif value is None:
-            # @DESIGN: Ignore None.
-            return
+        return (
+            container_tag,
+            iter(walk_dynamic_template(bf, template, text_t, container_tag)),
+        )
+
+
+def walk_dynamic_template(
+    bf: list[str], template: Template, text_t: Template, container_tag: str
+) -> t.Iterable[tuple[InterpolatorProto, Template, InterpolateInfo]]:
+    """
+    Walk a text template when we determine we can at runtime.
+    """
+    for part in text_t:
+        if isinstance(part, str):
+            bf.append(part)
         else:
-            if container_tag not in ("style", "script", "title", "textarea", "<!--"):
-                if hasattr(value, "__html__"):
-                    value = t.cast(HasHTMLDunder, value)
-                    bf.append(value.__html__())
-                else:
-                    # @DESIGN: Everything that isn't an object we recognize is
-                    # coerced to a str() and emitted.
-                    bf.append(render_api.escape_html_text(str(value)))
-            else:
-                raise NotImplementedError("We cannot handle text escaping here.")
+            ip_info = (container_tag, part.value)
+            yield (interpolate_normal_text_from_interpolation, template, ip_info)
 
 
 @dataclass(frozen=True)
@@ -474,27 +510,45 @@ def _stream_component_interpolation(
         )
         return Interpolation((interpolate_component, info), "", None, "tdom_component")
 
-    def _stream_raw_text_interpolation(self, last_container_tag, text_t):
+    def _stream_raw_texts_interpolation(
+        self, last_container_tag: str, text_t: Template
+    ):
         info = (last_container_tag, text_t)
         return Interpolation(
-            (interpolate_raw_text, info), "", None, "html_raw_text_template"
+            (interpolate_raw_texts_from_template, info), "", None, "html_raw_texts"
         )
 
-    def _stream_escapable_raw_text_interpolation(self, last_container_tag, text_t):
+    def _stream_escapable_raw_texts_interpolation(
+        self, last_container_tag: str, text_t: Template
+    ):
         info = (last_container_tag, text_t)
         return Interpolation(
-            (interpolate_escapable_raw_text, info),
+            (interpolate_escapable_raw_texts_from_template, info),
             "",
             None,
-            "html_escapable_raw_text_template",
+            "html_escapable_raw_texts",
         )
 
-    def _stream_text_interpolation(
-        self, last_container_tag: str | None, values_index: int
+    def _stream_normal_text_interpolation(
+        self, last_container_tag: str, values_index: int
     ):
         info = (last_container_tag, values_index)
         return Interpolation(
-            (interpolate_struct_text, info), "", None, "html_normal_interpolation"
+            (interpolate_normal_text_from_interpolation, info),
+            "",
+            None,
+            "html_normal_text",
+        )
+
+    def _stream_dynamic_texts_interpolation(
+        self, last_container_tag: None, text_t: Template
+    ):
+        info = (last_container_tag, text_t)
+        return Interpolation(
+            (interpolate_dynamic_texts_from_template, info),
+            "",
+            None,
+            "html_dynamic_text",
         )
 
     def streamer(
@@ -563,14 +617,22 @@ def streamer(
                             for part in iter(ref)
                         ]
                     )
-                    if last_container_tag in CDATA_CONTENT_ELEMENTS:
+                    if ref.is_literal:
+                        yield ref.strings[0]  # Trust literals.
+                    elif last_container_tag is None:
+                        # We can't know how to handle this right now, so wait until render time and if
+                        # we still cannot know then probably fail.
+                        yield self._stream_dynamic_texts_interpolation(
+                            last_container_tag, text_t
+                        )
+                    elif last_container_tag in CDATA_CONTENT_ELEMENTS:
                         # Must be handled all at once.
-                        yield self._stream_raw_text_interpolation(
+                        yield self._stream_raw_texts_interpolation(
                             last_container_tag, text_t
                         )
                     elif last_container_tag in RCDATA_CONTENT_ELEMENTS:
                         # We can handle all at once because there are no non-text children and everything must be string-ified.
-                        yield self._stream_escapable_raw_text_interpolation(
+                        yield self._stream_escapable_raw_texts_interpolation(
                             last_container_tag, text_t
                         )
                     else:
@@ -580,7 +642,7 @@ def streamer(
                             if isinstance(part, str):
                                 yield part
                             else:
-                                yield self._stream_text_interpolation(
+                                yield self._stream_normal_text_interpolation(
                                     last_container_tag, part.value
                                 )
                 case _:

From 645588949b31ee84ad90a70f7bc5b068f13e7e9c Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 25 Jan 2026 18:41:39 -0800
Subject: [PATCH 63/81] Add docstring.

---
 tdom/transformer.py | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 44313ad..6d420f2 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -440,7 +440,19 @@ def walk_dynamic_template(
     bf: list[str], template: Template, text_t: Template, container_tag: str
 ) -> t.Iterable[tuple[InterpolatorProto, Template, InterpolateInfo]]:
     """
-    Walk a text template when we determine we can at runtime.
+    Walk a `Text()` template that we determined was usable at runtime.
+
+    This happens when a container tag isn't resolvable at parse time and we
+    have to discover it at runtime.
+
+    bf:
+      The buffer to write strings out to.
+    template:
+      The original values template.
+    text_t:
+      A template with i_index references to the original values template.
+    container_tag:
+      The tag of the containing element.
     """
     for part in text_t:
         if isinstance(part, str):

From 442cd97ef1f032e42851450728e494d1a936919d Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 25 Jan 2026 18:46:25 -0800
Subject: [PATCH 64/81] Cleanup more comments.

---
 tdom/transformer.py | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 6d420f2..0c4ba48 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -368,8 +368,7 @@ def interpolate_normal_text_from_value(
         container_tag = last_container_tag
 
     if isinstance(value, str):
-        # @NOTE: Must be subclass of str, if you want __html__ to work you need
-        # to wrap that object in markupsafe.Markup.
+        # @DESIGN: Objects with `__html__` must be wrapped with markupsafe.Markup.
         bf.append(render_api.escape_html_text(value))
     elif isinstance(value, Template):
         return (
@@ -381,8 +380,6 @@ def interpolate_normal_text_from_value(
             ),
         )
     elif isinstance(value, Iterable):
-        # If we don't guard against str instances then str subclasses will be
-        # treated as a sequence/iterable of chars.
         return (
             container_tag,
             (

From cb35ea71df41963071c595d8ae13dbfc106e26b5 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 25 Jan 2026 21:42:04 -0800
Subject: [PATCH 65/81] Add simple foreign element tests to see where things
 are at.

---
 tdom/transformer_test.py | 69 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 2b2dd57..bcac804 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -402,3 +402,72 @@ def Footer(pager, paginate_url, footer_classes=("footer",)) -> Template:
         res
         == '<div class="footer"><div class="cb tc w-100"><a href="/pages?page=1" class="dib pa1">1</a><a href="/pages?page=2" class="dib pa1">2</a><span class="dib pa1">3</span><a href="/pages?page=4" class="dib pa1">4</a><a href="/pages?page=5" class="dib pa1">5</a><a href="/pages?page=6" class="dib pa1">Next</a></div></div>'
     )
+
+
+def test_mathml():
+    num = 1
+    denom = 3
+    mathml_t = t"""<p>
+  The fraction
+  <math>
+    <mfrac>
+      <mn>{num}</mn>
+      <mn>{denom}</mn>
+    </mfrac>
+  </math>
+  is not a decimal number.
+</p>"""
+    render_api = render_service_factory()
+    res = render_api.render_template(mathml_t)
+    assert (
+        str(res)
+        == """<p>
+  The fraction
+  <math>
+    <mfrac>
+      <mn>1</mn>
+      <mn>3</mn>
+    </mfrac>
+  </math>
+  is not a decimal number.
+</p>"""
+    )
+
+
+def test_svg():
+    cx, cy, r, fill = 150, 100, 80, "green"
+    svg_t = t"""<svg version="1.1" width="300" height="200" xmlns="http://www.w3.org/2000/svg">
+  <rect width="100%" height="100%" fill="red" />
+  <circle cx={cx} cy={cy} r={r} fill={fill} />
+  <text x="150" y="125" font-size="60" text-anchor="middle" fill="white">SVG</text>
+</svg>"""
+    render_api = render_service_factory()
+    res = render_api.render_template(svg_t)
+    assert (
+        str(res)
+        == """<svg version="1.1" width="300" height="200" xmlns="http://www.w3.org/2000/svg">
+  <rect width="100%" height="100%" fill="red"></rect>
+  <circle cx="150" cy="100" r="80" fill="green"></circle>
+  <text x="150" y="125" font-size="60" text-anchor="middle" fill="white">SVG</text>
+</svg>"""
+    )
+
+
+@pytest.mark.skip("""Need foreign element mode.  Could work like last container.""")
+def test_svg_self_closing_empty_elements():
+    cx, cy, r, fill = 150, 100, 80, "green"
+    svg_t = t"""<svg width="300" height="200">
+  <rect width="100%" height="100%" fill="red" />
+  <circle cx={cx} cy={cy} r={r} fill={fill} />
+  <text x="150" y="125" font-size="60" text-anchor="middle" fill="white">SVG</text>
+</svg>"""
+    render_api = render_service_factory()
+    res = render_api.render_template(svg_t)
+    assert (
+        str(res)
+        == """<svg width="300" height="200">
+  <rect width="100%" height="100%" fill="red" />
+  <circle cx="150" cy="100" r="80" fill="green" />
+  <text x="150" y="125" font-size="60" text-anchor="middle" fill="white">SVG</text>
+</svg>"""
+    )

From 005b4afb20427c73021da198b88c7aee179d6bf2 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 25 Jan 2026 22:34:53 -0800
Subject: [PATCH 66/81] Minor cleanup.

---
 tdom/transformer.py | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 0c4ba48..3136adb 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -6,9 +6,10 @@
 from contextlib import nullcontext
 from contextvars import ContextVar, Token
 import functools
-from markupsafe import Markup
 import inspect
 
+from markupsafe import Markup
+
 from .format import format_interpolation
 from .parser import TemplateParser, HTMLAttributesDict
 from .tnodes import (
@@ -76,16 +77,14 @@ def __call__(
         ip_info: InterpolateInfo,
     ) -> RenderQueueItem | None:
         """
-        Populates an interpolation or returns iterator to decende into.
-
-        If recursion is required then pushes current iterator.
+        Populates an interpolation or returns iterator to descend into.
 
         render_api
-            The current render api, provides various helper methods to the interpolator.
+            The current render api, provides various helper methods.
         bf
             A list-like output buffer.
         last_container_tag
-            The last HTML tag known for this interpolation, this cannot always be 100% accurate.
+            The last HTML tag known for this interpolation or None if unknown.
         template
             The "values" template that is being used to fulfill interpolations.
         ip_info
@@ -473,6 +472,7 @@ class TransformService:
     escape_html_text: Callable = default_escape_html_text
 
     slash_void: bool = False  # Apply a xhtml-style slash to void html elements.
+
     uppercase_doctype: bool = False  # DOCTYPE vs doctype
 
     def transform_template(self, template: Template) -> Template:
@@ -658,6 +658,12 @@ def streamer(
                     raise ValueError(f"Unrecognized tnode: {tnode}")
 
     def has_dynamic_attrs(self, attrs: t.Sequence[TAttribute]) -> bool:
+        """
+        Determine if any attributes with interpolations are in attrs sequence.
+
+        This is mainly used to tell if we can pre-emptively serialize an
+        element's attributes (or not).
+        """
         for attr in attrs:
             if not isinstance(attr, TLiteralAttribute):
                 return True

From b4077cb66ceccbb3e75e0e445777fa37880f2b61 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sun, 25 Jan 2026 22:36:49 -0800
Subject: [PATCH 67/81] Use pytest parametrize instead of forloop.

---
 tdom/transformer_test.py | 88 ++++++++++++++++++++++------------------
 1 file changed, 48 insertions(+), 40 deletions(-)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index bcac804..27e97d5 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -128,54 +128,62 @@ def get_sample_t(idx, spread_attrs, button_text):
             )
 
 
-def test_render_template_iterables():
-    render_api = render_service_factory()
+def get_select_t_with_list(options, selected_values):
+    return t"""<select>{
+        [
+            t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>"
+            for opt in options
+        ]
+    }</select>"""
 
-    def get_select_t_with_list(options, selected_values):
-        return t"""<select>{
-            [
-                t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>"
-                for opt in options
-            ]
-        }</select>"""
-
-    def get_select_t_with_generator(options, selected_values):
-        return t"""<select>{
-            (
-                t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>"
-                for opt in options
-            )
-        }</select>"""
-
-    def get_select_t_with_concat(options, selected_values):
-        parts = [t"<select>"]
-        parts.extend(
-            [
-                t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>"
-                for opt in options
-            ]
+
+def get_select_t_with_generator(options, selected_values):
+    return t"""<select>{
+        (
+            t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>"
+            for opt in options
         )
-        parts.append(t"</select>")
-        return sum(parts, t"")
+    }</select>"""
+
+
+def get_select_t_with_concat(options, selected_values):
+    parts = [t"<select>"]
+    parts.extend(
+        [
+            t"<option value={opt[0]} selected={opt[0] in selected_values}>{opt[1]}</option>"
+            for opt in options
+        ]
+    )
+    parts.append(t"</select>")
+    return sum(parts, t"")
+
+
+@pytest.mark.parametrize(
+    "provider",
+    (
+        get_select_t_with_list,
+        get_select_t_with_generator,
+        get_select_t_with_concat,
+    ),
+)
+def test_render_template_iterables(provider):
+    render_api = render_service_factory()
 
     def get_color_select_t(selected_values: set, provider: t.Callable) -> Template:
         PRIMARY_COLORS = [("R", "Red"), ("Y", "Yellow"), ("B", "Blue")]
         assert set(selected_values).issubset(set([opt[0] for opt in PRIMARY_COLORS]))
         return provider(PRIMARY_COLORS, selected_values)
 
-    for provider in (
-        get_select_t_with_list,
-        get_select_t_with_generator,
-        get_select_t_with_concat,
-    ):
-        assert (
-            render_api.render_template(get_color_select_t(set(), provider))
-            == '<select><option value="R">Red</option><option value="Y">Yellow</option><option value="B">Blue</option></select>'
-        )
-        assert (
-            render_api.render_template(get_color_select_t({"Y"}, provider))
-            == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'
-        )
+    no_selection_t = get_color_select_t(set(), provider)
+    assert (
+        render_api.render_template(no_selection_t)
+        == '<select><option value="R">Red</option><option value="Y">Yellow</option><option value="B">Blue</option></select>'
+    )
+    selected_yellow_t = get_color_select_t({"Y"}, provider)
+    assert (
+        render_api.render_template(selected_yellow_t)
+        == '<select><option value="R">Red</option><option value="Y" selected>Yellow</option><option value="B">Blue</option></select>'
+    )
 
 
 def test_context_provider_pattern():

From f3fa3a64d91d0cda96564a8f046066c726648fdd Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Mon, 26 Jan 2026 00:00:25 -0800
Subject: [PATCH 68/81] Use markup to optionally bypass script, comment and
 style escape functions.

---
 tdom/escaping.py | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/tdom/escaping.py b/tdom/escaping.py
index 8605968..af34ecd 100644
--- a/tdom/escaping.py
+++ b/tdom/escaping.py
@@ -9,10 +9,16 @@
 LT = "&lt;"
 
 
-def escape_html_comment(text: str) -> str:
+def escape_html_comment(text: str, allow_markup: bool = False) -> str:
     """Escape text injected into an HTML comment."""
     if not text:
         return text
+    elif allow_markup and hasattr(text, "__html__"):
+        return text.__html__()
+    elif not allow_markup and type(text) is not str:
+        # text manipulation triggers regular html escapes on Markup
+        text = str(text)
+
     # - text must not start with the string ">"
     if text[0] == ">":
         text = GT + text[1:]
@@ -39,8 +45,10 @@ def escape_html_comment(text: str) -> str:
 STYLE_RES = ((re.compile("</(?P<tagname>style)>", re.I | re.A), LT + r"/\g<tagname>>"),)
 
 
-def escape_html_style(text: str) -> str:
+def escape_html_style(text: str, allow_markup: bool = False) -> str:
     """Escape text injected into an HTML style element."""
+    if allow_markup and hasattr(text, "__html__"):
+        return text.__html__()
     for matche_re, replace_text in STYLE_RES:
         text = re.sub(matche_re, replace_text, text)
     return text
@@ -62,7 +70,7 @@ def escape_html_style(text: str) -> str:
 )
 
 
-def escape_html_script(text: str) -> str:
+def escape_html_script(text: str, allow_markup: bool = False) -> str:
     """
     Escape text injected into an HTML script element.
 
@@ -75,6 +83,8 @@ def escape_html_script(text: str) -> str:
     - "<script" as "\x3cscript"
     - "</script" as "\x3c/script"`
     """
+    if allow_markup and hasattr(text, "__html__"):
+        return text.__html__()
     for match_re, replace_text in SCRIPT_RES:
         text = re.sub(match_re, replace_text, text)
     return text

From faa15b8eef97fa6c28acf718658e1792bb7604b6 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Mon, 26 Jan 2026 00:00:48 -0800
Subject: [PATCH 69/81] Remove general purpose escape function and use explict
 functions.

---
 tdom/escaping.py | 13 -------------
 1 file changed, 13 deletions(-)

diff --git a/tdom/escaping.py b/tdom/escaping.py
index af34ecd..6eded3b 100644
--- a/tdom/escaping.py
+++ b/tdom/escaping.py
@@ -88,16 +88,3 @@ def escape_html_script(text: str, allow_markup: bool = False) -> str:
     for match_re, replace_text in SCRIPT_RES:
         text = re.sub(match_re, replace_text, text)
     return text
-
-
-def escape_html_content_in_tag(parent_tag, content):
-    parent_tag = parent_tag.lower()
-    if parent_tag == "script":
-        return escape_html_script(content)
-    elif parent_tag == "<!--":
-        return escape_html_comment(content)
-    elif parent_tag == "style":
-        return escape_html_style(content)
-    else:
-        # Fallback to nuclear solution.
-        return escape_html_text(content)

From 0903a0f4048332cb155118487b9c9855d2a31919 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Mon, 26 Jan 2026 00:16:31 -0800
Subject: [PATCH 70/81] Move hasHTMLDunder into protocols.

---
 tdom/processor.py | 6 +-----
 tdom/protocols.py | 6 ++++++
 2 files changed, 7 insertions(+), 5 deletions(-)
 create mode 100644 tdom/protocols.py

diff --git a/tdom/processor.py b/tdom/processor.py
index 9bb055d..538c1ac 100644
--- a/tdom/processor.py
+++ b/tdom/processor.py
@@ -31,11 +31,7 @@
 from .placeholders import TemplateRef
 from .template_utils import template_from_parts
 from .utils import CachableTemplate, LastUpdatedOrderedDict
-
-
-@t.runtime_checkable
-class HasHTMLDunder(t.Protocol):
-    def __html__(self) -> str: ...  # pragma: no cover
+from .protocols import HasHTMLDunder
 
 
 # TODO: in Ian's original PR, this caching was tethered to the
diff --git a/tdom/protocols.py b/tdom/protocols.py
new file mode 100644
index 0000000..bcb8147
--- /dev/null
+++ b/tdom/protocols.py
@@ -0,0 +1,6 @@
+import typing as t
+
+
+@t.runtime_checkable
+class HasHTMLDunder(t.Protocol):
+    def __html__(self) -> str: ...  # pragma: no cover

From 85b9a04f6f822df6a7c15d8f5b4c9c15bdba8261 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Mon, 26 Jan 2026 00:17:08 -0800
Subject: [PATCH 71/81] Use has html protocol instead of hasattr check.

---
 tdom/escaping.py | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/tdom/escaping.py b/tdom/escaping.py
index 6eded3b..726f00c 100644
--- a/tdom/escaping.py
+++ b/tdom/escaping.py
@@ -2,6 +2,9 @@
 
 from markupsafe import escape as markup_escape
 
+from .protocols import HasHTMLDunder
+
+
 escape_html_text = markup_escape  # unify api for test of project
 
 
@@ -13,7 +16,7 @@ def escape_html_comment(text: str, allow_markup: bool = False) -> str:
     """Escape text injected into an HTML comment."""
     if not text:
         return text
-    elif allow_markup and hasattr(text, "__html__"):
+    elif allow_markup and isinstance(text, HasHTMLDunder):
         return text.__html__()
     elif not allow_markup and type(text) is not str:
         # text manipulation triggers regular html escapes on Markup
@@ -47,7 +50,7 @@ def escape_html_comment(text: str, allow_markup: bool = False) -> str:
 
 def escape_html_style(text: str, allow_markup: bool = False) -> str:
     """Escape text injected into an HTML style element."""
-    if allow_markup and hasattr(text, "__html__"):
+    if allow_markup and isinstance(text, HasHTMLDunder):
         return text.__html__()
     for matche_re, replace_text in STYLE_RES:
         text = re.sub(matche_re, replace_text, text)
@@ -83,7 +86,7 @@ def escape_html_script(text: str, allow_markup: bool = False) -> str:
     - "<script" as "\x3cscript"
     - "</script" as "\x3c/script"`
     """
-    if allow_markup and hasattr(text, "__html__"):
+    if allow_markup and isinstance(text, HasHTMLDunder):
         return text.__html__()
     for match_re, replace_text in SCRIPT_RES:
         text = re.sub(match_re, replace_text, text)

From 51e1a6daa73399603bc322a6b10343ed204f76e6 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Mon, 26 Jan 2026 00:17:21 -0800
Subject: [PATCH 72/81] Update tests.

---
 tdom/escaping_test.py | 40 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/tdom/escaping_test.py b/tdom/escaping_test.py
index a6f18cb..a74f8f2 100644
--- a/tdom/escaping_test.py
+++ b/tdom/escaping_test.py
@@ -1,4 +1,15 @@
-from .escaping import escape_html_comment, escape_html_script, escape_html_style
+from markupsafe import Markup
+
+from .escaping import (
+    escape_html_comment,
+    escape_html_script,
+    escape_html_style,
+    escape_html_text,
+)
+
+
+def test_escape_html_text() -> None:
+    assert escape_html_text("<div>") == "&lt;div&gt;"
 
 
 def test_escape_html_comment_empty() -> None:
@@ -27,6 +38,15 @@ def test_escape_html_comment_ends_with_lt_dash() -> None:
     assert escape_html_comment("This is a comment<!-") == "This is a comment&lt;!-"
 
 
+def test_escape_html_comment_markup() -> None:
+    input_text = "-->"
+    escaped_text = "--&gt;"
+    out = escape_html_comment(Markup(input_text), allow_markup=False)
+    assert out != input_text and out == escaped_text
+    out = escape_html_comment(Markup(input_text), allow_markup=True)
+    assert out == input_text and out != escaped_text
+
+
 def test_escape_html_style() -> None:
     input_text = "body { color: red; }</style> p { font-SIZE: 12px; }</STYLE>"
     expected_output = (
@@ -35,6 +55,15 @@ def test_escape_html_style() -> None:
     assert escape_html_style(input_text) == expected_output
 
 
+def test_escape_html_style_markup() -> None:
+    input_text = "</STYLE>"
+    escaped_text = "&lt;/STYLE>"
+    out = escape_html_style(Markup(input_text), allow_markup=False)
+    assert out != input_text and out == escaped_text
+    out = escape_html_style(Markup(input_text), allow_markup=True)
+    assert out == input_text and out != escaped_text
+
+
 def test_escape_html_script() -> None:
     input_text = "<!-- <script>var a = 1;</script> </SCRIPT>"
     expected_output = "\\x3c!-- \\x3cscript>var a = 1;\\x3c/script> \\x3c/SCRIPT>"
@@ -42,3 +71,12 @@ def test_escape_html_script() -> None:
     # Smoketest that escaping is working and we are not just escaping back to the same value.
     for text in ("<script", "</script", "<!--"):
         assert escape_html_script(text) != text
+
+
+def test_escape_html_script_markup() -> None:
+    input_text = "<script>"
+    escaped_text = "\\x3cscript>"
+    out = escape_html_script(Markup(input_text), allow_markup=False)
+    assert out != input_text and out == escaped_text
+    out = escape_html_script(Markup(input_text), allow_markup=True)
+    assert out == input_text and out != escaped_text

From 970538237985710245636b89702da91fbec6f346 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Mon, 26 Jan 2026 00:18:36 -0800
Subject: [PATCH 73/81] Cleanup special case escaping.

---
 tdom/transformer.py | 48 +++++++++++++++++++++++++++++----------------
 1 file changed, 31 insertions(+), 17 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 3136adb..85f902c 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -8,8 +8,6 @@
 import functools
 import inspect
 
-from markupsafe import Markup
-
 from .format import format_interpolation
 from .parser import TemplateParser, HTMLAttributesDict
 from .tnodes import (
@@ -29,7 +27,8 @@
     RCDATA_CONTENT_ELEMENTS,
 )
 from .escaping import (
-    escape_html_content_in_tag as default_escape_html_content_in_tag,
+    escape_html_script as default_escape_html_script,
+    escape_html_style as default_escape_html_style,
     escape_html_text as default_escape_html_text,
     escape_html_comment as default_escape_html_comment,
 )
@@ -110,7 +109,8 @@ def interpolate_comment(
     assert container_tag == "<!--"
     bf.append(
         render_api.escape_html_comment(
-            resolve_text_without_recursion(template, container_tag, comment_t)
+            resolve_text_without_recursion(template, container_tag, comment_t),
+            allow_markup=True,
         )
     )
 
@@ -292,12 +292,25 @@ def interpolate_raw_texts_from_template(
     @NOTE: This interpolator expects a Template.
     """
     container_tag, content_t = t.cast(InterpolateRawTextsFromTemplateInfo, ip_info)
-    bf.append(
-        render_api.escape_html_content_in_tag(
-            container_tag,
-            resolve_text_without_recursion(template, container_tag, content_t),
+    content = resolve_text_without_recursion(template, container_tag, content_t)
+    if container_tag == "script":
+        bf.append(
+            render_api.escape_html_script(
+                container_tag,
+                content,
+                allow_markup=True,
+            )
         )
-    )
+    elif container_tag == "style":
+        bf.append(
+            render_api.escape_html_style(
+                container_tag,
+                content,
+                allow_markup=True,
+            )
+        )
+    else:
+        raise NotImplementedError(f"Container tag {container_tag} is not supported.")
 
 
 type InterpolateEscapableRawTextsFromTemplateInfo = tuple[str, Template]
@@ -318,9 +331,11 @@ def interpolate_escapable_raw_texts_from_template(
     container_tag, content_t = t.cast(
         InterpolateEscapableRawTextsFromTemplateInfo, ip_info
     )
+    assert container_tag == "title" or container_tag == "textarea"
     bf.append(
         render_api.escape_html_text(
-            resolve_text_without_recursion(template, container_tag, content_t)
+            resolve_text_without_recursion(template, container_tag, content_t),
+            allow_markup=True,
         )
     )
 
@@ -689,13 +704,10 @@ def resolve_text_without_recursion(
         value = template.interpolations[i_index].value
         if value is None:
             return None
-        elif (
-            type(value) is str
-        ):  # type() check to avoid subclasses, probably something smarter here
+        elif isinstance(value, str):
+            # @DESIGN: Markup() must be used explicitly if you want __html__ supported.
             return value
-        elif hasattr(value, "__html__"):
-            return Markup(value.__html__())
-        elif not isinstance(value, str) and isinstance(value, (Template, Iterable)):
+        elif isinstance(value, (Template, Iterable)):
             raise ValueError(
                 f"Recursive includes are not supported within {container_tag}"
             )
@@ -798,7 +810,9 @@ class RenderService:
 
     escape_html_comment: Callable = default_escape_html_comment
 
-    escape_html_content_in_tag: Callable = default_escape_html_content_in_tag
+    escape_html_script: Callable = default_escape_html_script
+
+    escape_html_style: Callable = default_escape_html_style
 
     def get_system(self, **kwargs: object):
         # @DESIGN: Maybe inject more here?

From e70e16c7a85fb4f0c5abac43788b6910a5e02fe1 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Tue, 27 Jan 2026 15:40:13 -0800
Subject: [PATCH 74/81] Add system provided context example.

---
 tdom/transformer_test.py | 65 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/tdom/transformer_test.py b/tdom/transformer_test.py
index 27e97d5..c901168 100644
--- a/tdom/transformer_test.py
+++ b/tdom/transformer_test.py
@@ -11,6 +11,8 @@
     render_service_factory,
     cached_render_service_factory,
     CachedTransformService,
+    RenderService,
+    TransformService,
 )
 
 
@@ -479,3 +481,66 @@ def test_svg_self_closing_empty_elements():
   <text x="150" y="125" font-size="60" text-anchor="middle" fill="white">SVG</text>
 </svg>"""
     )
+
+
+@dataclass
+class FakeUser:
+    name: str
+    id: int
+
+
+@dataclass
+class FakeRequest:
+    user: FakeUser | None = None
+
+
+@dataclass(frozen=True)
+class RequestRenderService(RenderService):
+    request: FakeRequest | None = None
+
+    def get_system(self, **kwargs):
+        return {**kwargs, "request": self.request}
+
+
+class UserProto(t.Protocol):
+    name: str
+
+
+class RequestProto(t.Protocol):
+    user: UserProto | None
+
+
+def test_system_context():
+    """Test providing context to components horizontally via *extra* system provided kwargs."""
+
+    def request_render_api(request):
+        return RequestRenderService(request=request, transform_api=TransformService())
+
+    def UserStatus(request: RequestProto, children: Template | None = None) -> Template:
+        user = request.user
+        if user:
+            classes = ("account-online",)
+            status_t = t"<span>Logged in as {user.name}</span>"
+        else:
+            classes = ("account-offline",)
+            status_t = t"<span>Not logged in</span>"
+        return t"<div class=account class={classes}>{children}{status_t}</div>"
+
+    page_t = t"""<!doctype html><html><body><div class=header><{UserStatus}><span class=account-icon>&#x1F464;</span></{UserStatus}></div></body></html>"""
+    render_api = request_render_api(FakeRequest(user=FakeUser(name="Guido", id=1000)))
+    res = render_api.render_template(page_t)
+    assert (
+        res
+        == """<!doctype html><html><body><div class="header"><div class="account account-online"><span class="account-icon">👤</span><span>Logged in as Guido</span></div></div></body></html>"""
+    )
+    render_api = request_render_api(FakeRequest(user=None))
+    res = render_api.render_template(page_t)
+    assert (
+        res
+        == """<!doctype html><html><body><div class="header"><div class="account account-offline"><span class="account-icon">👤</span><span>Not logged in</span></div></div></body></html>"""
+    )
+
+    render_api = RenderService(transform_api=TransformService())
+    with pytest.raises(TypeError) as excinfo:
+        res = render_api.render_template(page_t)
+    assert "Missing required parameters" in str(excinfo.value)

From 40c83e733a00610deea6fe814652e69ad6bf721c Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Tue, 27 Jan 2026 22:07:08 -0800
Subject: [PATCH 75/81] Markup is expected by default.

---
 tdom/transformer.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 85f902c..e156196 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -335,7 +335,6 @@ def interpolate_escapable_raw_texts_from_template(
     bf.append(
         render_api.escape_html_text(
             resolve_text_without_recursion(template, container_tag, content_t),
-            allow_markup=True,
         )
     )
 

From ea8ef58011174c2e072fa188b6f98ea30eefedba Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Wed, 28 Jan 2026 21:05:13 -0800
Subject: [PATCH 76/81] Add callback and cvar formatters.

---
 tdom/format.py         |  4 ++--
 tdom/processor.py      | 25 ++++++++++++++++++++++++-
 tdom/processor_test.py | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+), 3 deletions(-)

diff --git a/tdom/format.py b/tdom/format.py
index fba5539..4ef68c6 100644
--- a/tdom/format.py
+++ b/tdom/format.py
@@ -29,8 +29,8 @@ def convert[T](value: T, conversion: t.Literal["a", "r", "s"] | None) -> T | str
 type FormatMatcher = t.Callable[[str], bool]
 """A predicate function that returns True if a given format specifier matches its criteria."""
 
-type CustomFormatter = t.Callable[[object, str], str]
-"""A function that takes a value and a format specifier and returns a formatted string."""
+type CustomFormatter = t.Callable[[t.Any, str], t.Any]
+"""A function that takes a value and a format specifier and returns a formatted value."""
 
 type MatcherAndFormatter = tuple[str | FormatMatcher, CustomFormatter]
 """
diff --git a/tdom/processor.py b/tdom/processor.py
index 538c1ac..2e4acdd 100644
--- a/tdom/processor.py
+++ b/tdom/processor.py
@@ -4,6 +4,7 @@
 from functools import lru_cache
 from string.templatelib import Interpolation, Template
 from dataclasses import dataclass
+from contextvars import ContextVar
 
 from markupsafe import Markup
 
@@ -65,7 +66,29 @@ def _format_unsafe(value: object, format_spec: str) -> str:
     return str(value)
 
 
-CUSTOM_FORMATTERS = (("safe", _format_safe), ("unsafe", _format_unsafe))
+def format_callback(converted_value: Callable, format_spec: str) -> object:
+    """Call the `convert-value` to get a replacement value."""
+    assert format_spec == "callback"
+    return converted_value()
+
+
+def format_cvar(
+    converted_value: ContextVar | tuple[ContextVar, object], format_spec: str
+) -> object:
+    """Assume the `converted_value` is a `ContextVar` and extract the current value."""
+    assert format_spec == "cvar"
+    if isinstance(converted_value, tuple):
+        return converted_value[0].get(converted_value[1])
+    else:
+        return converted_value.get()
+
+
+CUSTOM_FORMATTERS = (
+    ("safe", _format_safe),
+    ("unsafe", _format_unsafe),
+    ("callback", format_callback),
+    ("cvar", format_cvar),
+)
 
 
 def format_interpolation(interpolation: Interpolation) -> object:
diff --git a/tdom/processor_test.py b/tdom/processor_test.py
index 11b1c4d..0115ac8 100644
--- a/tdom/processor_test.py
+++ b/tdom/processor_test.py
@@ -3,6 +3,7 @@
 from dataclasses import dataclass, field
 from string.templatelib import Interpolation, Template
 from itertools import product
+from contextvars import ContextVar
 
 import pytest
 from markupsafe import Markup
@@ -1485,3 +1486,35 @@ def test_mismatched_component_closing_tag_fails():
         _ = html(
             t"<{FunctionComponent} first=1 second={99} third-arg='comp1'>Hello</{ClassComponent}>"
         )
+
+
+# -----------------------
+# Formatter tests.
+# -----------------------
+
+
+def test_formatter_callback():
+    state = {"count": 15}
+
+    def get_count():
+        return state["count"]
+
+    count_t = t"<div>{get_count:callback}</div>"
+    assert str(html(count_t)) == "<div>15</div>"
+    state["count"] = 1
+    assert str(html(count_t)) == "<div>1</div>", (
+        "Check that we are actually calling the function each run."
+    )
+
+
+COUNT_CTX = ContextVar("COUNT_CTX", default="1")
+
+
+def test_formatter_cvar():
+    count_t = t"<div>{COUNT_CTX:cvar}</div>"
+    assert str(html(count_t)) == "<div>1</div>"
+    with COUNT_CTX.set("15"):
+        assert str(html(count_t)) == "<div>15</div>"
+    assert str(html(count_t)) == "<div>1</div>", (
+        "Check that we check the ContextVar each run."
+    )

From e8af7d6e5e8408405f1f3fc1a8d60e4ccafe285e Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Wed, 28 Jan 2026 21:05:33 -0800
Subject: [PATCH 77/81] Use processor function to use shared formatters.

---
 tdom/transformer.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index e156196..a0d3eb2 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -8,7 +8,6 @@
 import functools
 import inspect
 
-from .format import format_interpolation
 from .parser import TemplateParser, HTMLAttributesDict
 from .tnodes import (
     TNode,
@@ -38,6 +37,7 @@
     _resolve_html_attrs as coerce_to_html_attrs,
     AttributesDict,
     _prep_component_kwargs,
+    format_interpolation,
 )
 from .callables import get_callable_info
 

From 57693c5e30663e13ed59637c0e37c16b3b88d6a7 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sat, 31 Jan 2026 22:00:02 -0800
Subject: [PATCH 78/81] Use actual t-string.

---
 tdom/transformer.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index a0d3eb2..700bf7f 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -230,7 +230,7 @@ def interpolate_component(
                 "Component callable in start tag must match component callable in end tag."
             )
     else:
-        children_template = Template("")
+        children_template = t""
 
     # @DESIGN: Inject system vars via manager?
     system_kwargs = render_api.get_system(

From aa366d117f78ca40e2c1d6560f1abe9a0e061ae3 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sat, 31 Jan 2026 22:07:23 -0800
Subject: [PATCH 79/81] Wrap RenderQueueItem creation for readability and
 possibly tracking.

---
 tdom/transformer.py | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 700bf7f..678af6d 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -268,7 +268,7 @@ def interpolate_component(
             )
         else:
             walker = render_api.walk_template(bf, result_template, result_struct)
-        return (container_tag, iter(walker))
+        return render_api.make_render_queue_item(container_tag, iter(walker))
     elif result_template is None:
         # DO NOTHING
         return
@@ -384,7 +384,7 @@ def interpolate_normal_text_from_value(
         # @DESIGN: Objects with `__html__` must be wrapped with markupsafe.Markup.
         bf.append(render_api.escape_html_text(value))
     elif isinstance(value, Template):
-        return (
+        return render_api.make_render_queue_item(
             container_tag,
             iter(
                 render_api.walk_template(
@@ -393,7 +393,7 @@ def interpolate_normal_text_from_value(
             ),
         )
     elif isinstance(value, Iterable):
-        return (
+        return render_api.make_render_queue_item(
             container_tag,
             (
                 (
@@ -440,7 +440,7 @@ def interpolate_dynamic_texts_from_template(
             render_api, bf, last_container_tag, template, (container_tag, text_t)
         )
     else:
-        return (
+        return render_api.make_render_queue_item(
             container_tag,
             iter(walk_dynamic_template(bf, template, text_t, container_tag)),
         )
@@ -817,6 +817,18 @@ def get_system(self, **kwargs: object):
         # @DESIGN: Maybe inject more here?
         return {**kwargs}
 
+    def make_render_queue_item(
+        self,
+        last_container_tag: str | None,
+        it: t.Iterable[tuple[InterpolatorProto, Template, InterpolateInfo]],
+    ) -> RenderQueueItem:
+        """
+        Coerce args into standard structure.
+
+        This is almost only here for tracking and readability.
+        """
+        return (last_container_tag, it)
+
     def render_template(
         self, template: Template, last_container_tag: str | None = None
     ) -> str:

From 898ba0fb5f0897794d3a52264424f0a4662dd432 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sat, 31 Jan 2026 22:08:34 -0800
Subject: [PATCH 80/81] Slightly improve error to get by until we get better
 error reporting.

---
 tdom/parser.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/tdom/parser.py b/tdom/parser.py
index 82de290..75763c6 100644
--- a/tdom/parser.py
+++ b/tdom/parser.py
@@ -288,7 +288,9 @@ def reset(self):
 
     def close(self) -> None:
         if self.stack:
-            raise ValueError("Invalid HTML structure: unclosed tags remain.")
+            raise ValueError(
+                f"Invalid HTML structure: unclosed tags remain: {self.stack[-1]}"
+            )
         if not self.placeholders.is_empty:
             raise ValueError("Some placeholders were never resolved.")
         super().close()

From 4b133444d5d83aac20279f50d5d8cfc961370836 Mon Sep 17 00:00:00 2001
From: Ian Wilson <ian@gardentheory.com>
Date: Sat, 31 Jan 2026 22:10:41 -0800
Subject: [PATCH 81/81] Move dynamic template walker in alongside other
 template walker(s).

---
 tdom/transformer.py | 59 ++++++++++++++++++++++++---------------------
 1 file changed, 32 insertions(+), 27 deletions(-)

diff --git a/tdom/transformer.py b/tdom/transformer.py
index 678af6d..510e0c7 100644
--- a/tdom/transformer.py
+++ b/tdom/transformer.py
@@ -442,36 +442,10 @@ def interpolate_dynamic_texts_from_template(
     else:
         return render_api.make_render_queue_item(
             container_tag,
-            iter(walk_dynamic_template(bf, template, text_t, container_tag)),
+            iter(render_api.walk_dynamic_template(bf, template, text_t, container_tag)),
         )
 
 
-def walk_dynamic_template(
-    bf: list[str], template: Template, text_t: Template, container_tag: str
-) -> t.Iterable[tuple[InterpolatorProto, Template, InterpolateInfo]]:
-    """
-    Walk a `Text()` template that we determined was usable at runtime.
-
-    This happens when a container tag isn't resolvable at parse time and we
-    have to discover it at runtime.
-
-    bf:
-      The buffer to write strings out to.
-    template:
-      The original values template.
-    text_t:
-      A template with i_index references to the original values template.
-    container_tag:
-      The tag of the containing element.
-    """
-    for part in text_t:
-        if isinstance(part, str):
-            bf.append(part)
-        else:
-            ip_info = (container_tag, part.value)
-            yield (interpolate_normal_text_from_interpolation, template, ip_info)
-
-
 @dataclass(frozen=True)
 class TransformService:
     """
@@ -906,6 +880,37 @@ def walk_template(
         if strings[idx]:
             bf.append(strings[idx])
 
+    def walk_dynamic_template(
+        self, bf: list[str], template: Template, text_t: Template, container_tag: str
+    ) -> t.Iterable[tuple[InterpolatorProto, Template, InterpolateInfo]]:
+        """
+        Walk a `Text()` template that we determined was usable at runtime.
+
+        This happens when a container tag isn't resolvable at parse time and we
+        have to discover it at runtime.
+
+        bf:
+          The buffer to write strings out to.
+        template:
+          The original values template.
+        text_t:
+          A template with i_index references to the original values template.
+        container_tag:
+          The tag of the containing element.
+        """
+        strings = text_t.strings
+        ips = text_t.interpolations
+        last_s_index = len(strings) - 1
+        idx = 0
+        while idx < last_s_index:
+            if strings[idx]:
+                bf.append(strings[idx])
+            ip_info = (container_tag, ips[idx].value)
+            yield (interpolate_normal_text_from_interpolation, template, ip_info)
+            idx += 1
+        if strings[idx]:
+            bf.append(strings[idx])
+
 
 class ContextVarSetter:
     """