From a527b2653a15d0cc19481ee6ed09a358d95068e7 Mon Sep 17 00:00:00 2001
From: Lawrence Lane <llane@nvidia.com>
Date: Fri, 15 May 2026 21:34:25 -0400
Subject: [PATCH 1/7] feat: add structured undefined diagnostics

---
 src/kida/exceptions.py             | 205 ++++++++++++++++++++++++++---
 tests/test_diagnostics_contract.py |  47 ++++++-
 2 files changed, 233 insertions(+), 19 deletions(-)

diff --git a/src/kida/exceptions.py b/src/kida/exceptions.py
index a63693b..9668d21 100644
--- a/src/kida/exceptions.py
+++ b/src/kida/exceptions.py
@@ -35,6 +35,7 @@
 
 from dataclasses import dataclass
 from enum import Enum
+from html import escape as html_escape
 from typing import Any, final
 
 
@@ -295,6 +296,125 @@ def format(self) -> str:
         return "\n".join(parts)
 
 
+@final
+@dataclass(frozen=True, slots=True)
+class DiagnosticLocation:
+    """Surface-neutral template location for exception renderers."""
+
+    template: str
+    line: int | None = None
+    column: int | None = None
+    filename: str | None = None
+
+    def format(self) -> str:
+        """Return ``template[:line[:column]]`` without terminal styling."""
+        location = self.template
+        if self.line:
+            location += f":{self.line}"
+            if self.column is not None:
+                location += f":{self.column}"
+        return location
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class DiagnosticFrame:
+    """Surface-neutral stack frame for template/component diagnostics."""
+
+    template: str
+    line: int
+    name: str | None = None
+
+    def format(self) -> str:
+        """Return a plain frame label."""
+        location = f"{self.template}:{self.line}"
+        if self.name:
+            return f"{location} -> {self.name}()"
+        return location
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class TemplateDiagnostic:
+    """Structured diagnostic data for downstream renderers.
+
+    This payload intentionally stores plain strings and immutable tuples only.
+    HTML, markdown, and terminal escaping/styling belongs to the renderer that
+    consumes it.
+    """
+
+    code: str | None
+    title: str
+    message: str
+    kind: str
+    location: DiagnosticLocation
+    source_snippet: SourceSnippet | None = None
+    hints: tuple[str, ...] = ()
+    docs_url: str | None = None
+    suggestion: str | None = None
+    template_stack: tuple[DiagnosticFrame, ...] = ()
+    component_stack: tuple[DiagnosticFrame, ...] = ()
+    metadata: tuple[tuple[str, str], ...] = ()
+
+    def metadata_dict(self) -> dict[str, str]:
+        """Return metadata as a regular dict for consumers that prefer mapping APIs."""
+        return dict(self.metadata)
+
+    def format_html_fragment(self) -> str:
+        """Render a dependency-free escaped HTML diagnostic fragment.
+
+        This is intentionally compact and unstyled so framework debug pages can
+        wrap it in their own chrome without inheriting terminal formatting.
+        """
+
+        code = (
+            f'<span class="kida-error-code">{html_escape(self.code)}</span> ' if self.code else ""
+        )
+        parts = [
+            '<section class="kida-diagnostic" data-kida-diagnostic="true">',
+            f"<h1>{code}{html_escape(self.title)}</h1>",
+            f'<p class="kida-diagnostic-message">{html_escape(self.message)}</p>',
+            '<dl class="kida-diagnostic-facts">',
+            f"<dt>Location</dt><dd>{html_escape(self.location.format())}</dd>",
+        ]
+        if self.suggestion:
+            parts.append(f"<dt>Suggestion</dt><dd>{html_escape(self.suggestion)}</dd>")
+        parts.append("</dl>")
+
+        if self.source_snippet:
+            parts.append('<pre class="kida-source-snippet"><code>')
+            for lineno, content in self.source_snippet.lines:
+                marker = ">" if lineno == self.source_snippet.error_line else " "
+                parts.append(f"{marker}{lineno:4} | {html_escape(content)}\n")
+            if self.source_snippet.column is not None:
+                caret = " " * self.source_snippet.column + "^"
+                parts.append(f"     | {html_escape(caret)}\n")
+            parts.append("</code></pre>")
+
+        if self.hints:
+            parts.append('<ol class="kida-diagnostic-hints">')
+            parts.extend(f"<li>{html_escape(hint)}</li>" for hint in self.hints)
+            parts.append("</ol>")
+
+        if self.component_stack:
+            parts.append("<h2>Component stack</h2><ol>")
+            parts.extend(
+                f"<li>{html_escape(frame.format())}</li>" for frame in self.component_stack
+            )
+            parts.append("</ol>")
+        if self.template_stack:
+            parts.append("<h2>Template stack</h2><ol>")
+            parts.extend(f"<li>{html_escape(frame.format())}</li>" for frame in self.template_stack)
+            parts.append("</ol>")
+        if self.docs_url:
+            parts.append(
+                f'<p class="kida-diagnostic-docs"><a href="{html_escape(self.docs_url)}">'
+                "Documentation</a></p>"
+            )
+        parts.append("</section>")
+        return "".join(parts)
+
+
 def build_source_snippet(
     source: str,
     error_line: int,
@@ -743,18 +863,31 @@ def __init__(
         self.name = name
         self.template = template or "<template>"
         self.lineno = lineno
-        self._available_names = available_names
+        self.available_names = frozenset(available_names or ())
+        self._available_names = self.available_names or None
         self.source_snippet = source_snippet
-        self.template_stack = template_stack or []
-        self.component_stack = component_stack or []
+        self.template_stack = list(template_stack or [])
+        self.component_stack = list(component_stack or [])
+        self.kind = kind
         self._kind = kind
         # Top-level {% def %} / {% region %} names declared by the current
         # template. When ``self.name`` is one of these, the error swaps the
         # generic ``| default('')`` hint for a directed message pointing the
         # user at the missing top-level declaration. See _hint_text().
-        self._declared_definitions = declared_definitions or frozenset()
+        self.declared_definitions = frozenset(declared_definitions or ())
+        self._declared_definitions = self.declared_definitions
+        self.suggestion = self._closest_available_name()
         super().__init__(self._format_message())
 
+    def _closest_available_name(self) -> str | None:
+        """Return the best fuzzy match from available names, if any."""
+        if not self._available_names:
+            return None
+        from difflib import get_close_matches
+
+        matches = get_close_matches(self.name, list(self._available_names), n=1, cutoff=0.6)
+        return matches[0] if matches else None
+
     def _hint_text(self) -> str:
         """Return the hint line shown after the error message.
 
@@ -800,13 +933,9 @@ def _format_message(self) -> str:
         msg = f"Undefined {self._kind} '{self.name}' in {terminal.location(location)}"
 
         # "Did you mean?" suggestion via fuzzy matching
-        if self._available_names:
-            from difflib import get_close_matches
-
-            matches = get_close_matches(self.name, list(self._available_names), n=1, cutoff=0.6)
-            if matches:
-                suggested = terminal.suggestion(matches[0])
-                msg += f". Did you mean '{suggested}'?"
+        if self.suggestion:
+            suggested = terminal.suggestion(self.suggestion)
+            msg += f". Did you mean '{suggested}'?"
 
         # Source snippet (shows the template line where error occurred)
         if self.source_snippet:
@@ -827,6 +956,50 @@ def _format_message(self) -> str:
             msg += f"\n  {terminal.hint('Hint:')} {nullsafe}"
         return msg
 
+    def diagnostic_hints(self) -> tuple[str, ...]:
+        """Return ordered plain-text hints for structured renderers."""
+        hints: list[str] = []
+        if self.suggestion:
+            hints.append(f"Did you mean '{self.suggestion}'?")
+        nullsafe = self._nullsafe_hint_text()
+        if nullsafe:
+            hints.append(nullsafe)
+        hints.append(self._hint_text())
+        return tuple(hints)
+
+    def to_diagnostic(self) -> TemplateDiagnostic:
+        """Return a surface-neutral diagnostic payload for this error."""
+        location = DiagnosticLocation(
+            template=self.template,
+            line=self.lineno,
+            column=self.source_snippet.column if self.source_snippet else None,
+        )
+        message = f"Undefined {self.kind} '{self.name}' in {location.format()}"
+        metadata = (
+            ("name", self.name),
+            ("kind", self.kind),
+        )
+        return TemplateDiagnostic(
+            code=self.code.value if self.code else None,
+            title=f"Undefined {self.kind}",
+            message=message,
+            kind=self.kind,
+            location=location,
+            source_snippet=self.source_snippet,
+            hints=self.diagnostic_hints(),
+            docs_url=self.code.docs_url if self.code else None,
+            suggestion=self.suggestion,
+            template_stack=tuple(
+                DiagnosticFrame(template=template, line=line)
+                for template, line in self.template_stack
+            ),
+            component_stack=tuple(
+                DiagnosticFrame(template=template, line=line, name=name)
+                for template, line, name in self.component_stack
+            ),
+            metadata=metadata,
+        )
+
     def format_compact(self) -> str:
         """Format undefined variable error as structured terminal diagnostic."""
         terminal = _terminal()
@@ -842,13 +1015,9 @@ def format_compact(self) -> str:
         )
 
         # "Did you mean?" suggestion
-        if self._available_names:
-            from difflib import get_close_matches
-
-            matches = get_close_matches(self.name, list(self._available_names), n=1, cutoff=0.6)
-            if matches:
-                suggested = terminal.suggestion(matches[0])
-                msg += f". Did you mean '{suggested}'?"
+        if self.suggestion:
+            suggested = terminal.suggestion(self.suggestion)
+            msg += f". Did you mean '{suggested}'?"
         parts.append(msg)
 
         # Source snippet
diff --git a/tests/test_diagnostics_contract.py b/tests/test_diagnostics_contract.py
index c98eb92..454196a 100644
--- a/tests/test_diagnostics_contract.py
+++ b/tests/test_diagnostics_contract.py
@@ -6,7 +6,9 @@
 import warnings
 from pathlib import Path
 
-from kida import Environment, ErrorCode
+import pytest
+
+from kida import Environment, ErrorCode, FileSystemLoader, UndefinedError
 from kida.cli import main
 
 
@@ -121,3 +123,46 @@ def test_component_warning_format_snapshot() -> None:
         "  Hint: Check the component's {% def %} signature and rename, add, "
         "or remove arguments."
     ]
+
+
+def test_undefined_error_structured_diagnostic_for_framework_views(tmp_path: Path) -> None:
+    """UndefinedError exposes plain data so HTML views do not parse terminal text."""
+    (tmp_path / "page.html").write_text(
+        "\n".join(
+            [
+                "<main>",
+                "  <script>{{ usernme }}</script>",
+                "</main>",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    env = Environment(loader=FileSystemLoader(str(tmp_path)), fstring_coalescing=False)
+    template = env.get_template("page.html")
+
+    with pytest.raises(UndefinedError) as exc_info:
+        template.render(username="Ada")
+
+    exc = exc_info.value
+    diagnostic = exc.to_diagnostic()
+
+    assert diagnostic.code == "K-RUN-001"
+    assert diagnostic.kind == "variable"
+    assert diagnostic.location.template == "page.html"
+    assert diagnostic.location.line == 2
+    assert diagnostic.suggestion == "username"
+    assert "Did you mean 'username'?" in diagnostic.hints
+    assert diagnostic.docs_url == ErrorCode.UNDEFINED_VARIABLE.docs_url
+    assert diagnostic.metadata_dict() == {
+        "name": "usernme",
+        "kind": "variable",
+    }
+    assert diagnostic.source_snippet is not None
+    assert diagnostic.source_snippet.error_line == 2
+
+    html = diagnostic.format_html_fragment()
+    assert "&lt;script&gt;{{ usernme }}&lt;/script&gt;" in html
+    assert "<script>{{ usernme }}</script>" not in html
+    assert "K-RUN-001" in html
+    assert "page.html:2" in html

From 3e667ea2ed13ca99d36cf7cb8594ad2e375a7728 Mon Sep 17 00:00:00 2001
From: Lawrence Lane <llane@nvidia.com>
Date: Fri, 15 May 2026 21:40:00 -0400
Subject: [PATCH 2/7] fix: preserve undefined error attribution

---
 src/kida/compiler/coalescing.py           |  11 +-
 src/kida/compiler/statements/functions.py | 182 +++++++++++++++++++---
 src/kida/render_context.py                |  23 ++-
 src/kida/template/core.py                 |  80 ++++++----
 src/kida/template/helpers.py              |  15 ++
 src/kida/template/render_helpers.py       |   6 +
 tests/test_diagnostics_contract.py        |  93 +++++++++++
 7 files changed, 362 insertions(+), 48 deletions(-)

diff --git a/src/kida/compiler/coalescing.py b/src/kida/compiler/coalescing.py
index c6c24f1..3c15323 100644
--- a/src/kida/compiler/coalescing.py
+++ b/src/kida/compiler/coalescing.py
@@ -308,7 +308,16 @@ def _compile_body_with_coalescing(self, nodes: list[Any]) -> list[ast.stmt]:
                 i += 1
 
             if len(coalesceable) >= COALESCE_MIN_NODES:
-                # Generate single f-string append
+                # Generate single f-string append, preserving the first risky
+                # output line for UndefinedError/source-snippet attribution.
+                from kida.nodes import Output
+
+                first_output = next(
+                    (node for node in coalesceable if isinstance(node, Output)),
+                    None,
+                )
+                if first_output is not None:
+                    stmts.append(self._make_line_marker(first_output.lineno))
                 stmts.append(self._compile_coalesced_output(coalesceable))
             elif coalesceable:
                 # Single node - use normal compilation
diff --git a/src/kida/compiler/statements/functions.py b/src/kida/compiler/statements/functions.py
index cd753b4..2ad5f0a 100644
--- a/src/kida/compiler/statements/functions.py
+++ b/src/kida/compiler/statements/functions.py
@@ -301,7 +301,45 @@ def _def_name(arg1, arg2=default, *, _caller=None, _outer_ctx=ctx):
         )
 
         # Component call stack: push frame on entry (Sprint 1.3)
-        # _rc.component_stack.append((_rc.template_name or '', _rc.line, 'def_name'))
+        # Imported macro wrappers set component_call_* so this frame points to
+        # the caller site while template_name/source still point at the def.
+        component_template_expr = ast.BoolOp(
+            op=ast.Or(),
+            values=[
+                ast.Attribute(
+                    value=ast.Name(id="_rc", ctx=ast.Load()),
+                    attr="component_call_template",
+                    ctx=ast.Load(),
+                ),
+                ast.Attribute(
+                    value=ast.Name(id="_rc", ctx=ast.Load()),
+                    attr="template_name",
+                    ctx=ast.Load(),
+                ),
+                ast.Constant(value=""),
+            ],
+        )
+        component_line_expr = ast.IfExp(
+            test=ast.Compare(
+                left=ast.Attribute(
+                    value=ast.Name(id="_rc", ctx=ast.Load()),
+                    attr="component_call_line",
+                    ctx=ast.Load(),
+                ),
+                ops=[ast.IsNot()],
+                comparators=[ast.Constant(value=None)],
+            ),
+            body=ast.Attribute(
+                value=ast.Name(id="_rc", ctx=ast.Load()),
+                attr="component_call_line",
+                ctx=ast.Load(),
+            ),
+            orelse=ast.Attribute(
+                value=ast.Name(id="_rc", ctx=ast.Load()),
+                attr="line",
+                ctx=ast.Load(),
+            ),
+        )
         func_body.append(
             ast.Expr(
                 value=ast.Call(
@@ -317,22 +355,8 @@ def _def_name(arg1, arg2=default, *, _caller=None, _outer_ctx=ctx):
                     args=[
                         ast.Tuple(
                             elts=[
-                                ast.BoolOp(
-                                    op=ast.Or(),
-                                    values=[
-                                        ast.Attribute(
-                                            value=ast.Name(id="_rc", ctx=ast.Load()),
-                                            attr="template_name",
-                                            ctx=ast.Load(),
-                                        ),
-                                        ast.Constant(value=""),
-                                    ],
-                                ),
-                                ast.Attribute(
-                                    value=ast.Name(id="_rc", ctx=ast.Load()),
-                                    attr="line",
-                                    ctx=ast.Load(),
-                                ),
+                                component_template_expr,
+                                component_line_expr,
                                 ast.Constant(value=def_name),
                             ],
                             ctx=ast.Load(),
@@ -632,7 +656,7 @@ def _compile_call_block(self, node: CallBlock) -> list[ast.stmt]:
         # def _caller_wrapper(_scope_stack, slot="default", **_slot_kwargs):
         #     f = _caller_slots.get(slot)
         #     return f(_scope_stack, **_slot_kwargs) if f else _Markup("")
-        wrapper_body: list[ast.stmt] = [
+        wrapper_call_body: list[ast.stmt] = [
             ast.Assign(
                 targets=[ast.Name(id="_f", ctx=ast.Store())],
                 value=ast.Call(
@@ -666,6 +690,113 @@ def _compile_call_block(self, node: CallBlock) -> list[ast.stmt]:
                 ),
             ),
         ]
+        wrapper_body: list[ast.stmt] = [
+            ast.Assign(
+                targets=[ast.Name(id="_rc", ctx=ast.Store())],
+                value=ast.BoolOp(
+                    op=ast.Or(),
+                    values=[
+                        ast.Call(
+                            func=ast.Name(id="_get_render_ctx", ctx=ast.Load()),
+                            args=[],
+                            keywords=[],
+                        ),
+                        ast.Name(id="_null_rc", ctx=ast.Load()),
+                    ],
+                ),
+            ),
+            ast.Assign(
+                targets=[ast.Name(id="_prev_template_name", ctx=ast.Store())],
+                value=ast.Attribute(
+                    value=ast.Name(id="_rc", ctx=ast.Load()),
+                    attr="template_name",
+                    ctx=ast.Load(),
+                ),
+            ),
+            ast.Assign(
+                targets=[ast.Name(id="_prev_source", ctx=ast.Store())],
+                value=ast.Attribute(
+                    value=ast.Name(id="_rc", ctx=ast.Load()),
+                    attr="source",
+                    ctx=ast.Load(),
+                ),
+            ),
+            ast.Assign(
+                targets=[ast.Name(id="_prev_line", ctx=ast.Store())],
+                value=ast.Attribute(
+                    value=ast.Name(id="_rc", ctx=ast.Load()),
+                    attr="line",
+                    ctx=ast.Load(),
+                ),
+            ),
+            ast.Assign(
+                targets=[
+                    ast.Attribute(
+                        value=ast.Name(id="_rc", ctx=ast.Load()),
+                        attr="template_name",
+                        ctx=ast.Store(),
+                    )
+                ],
+                value=ast.Name(id="_caller_template_name", ctx=ast.Load()),
+            ),
+            ast.Assign(
+                targets=[
+                    ast.Attribute(
+                        value=ast.Name(id="_rc", ctx=ast.Load()),
+                        attr="source",
+                        ctx=ast.Store(),
+                    )
+                ],
+                value=ast.Name(id="_caller_source", ctx=ast.Load()),
+            ),
+            ast.Assign(
+                targets=[
+                    ast.Attribute(
+                        value=ast.Name(id="_rc", ctx=ast.Load()),
+                        attr="line",
+                        ctx=ast.Store(),
+                    )
+                ],
+                value=ast.Name(id="_caller_line", ctx=ast.Load()),
+            ),
+            ast.Try(
+                body=wrapper_call_body,
+                handlers=[],
+                orelse=[],
+                finalbody=[
+                    ast.Assign(
+                        targets=[
+                            ast.Attribute(
+                                value=ast.Name(id="_rc", ctx=ast.Load()),
+                                attr="template_name",
+                                ctx=ast.Store(),
+                            )
+                        ],
+                        value=ast.Name(id="_prev_template_name", ctx=ast.Load()),
+                    ),
+                    ast.Assign(
+                        targets=[
+                            ast.Attribute(
+                                value=ast.Name(id="_rc", ctx=ast.Load()),
+                                attr="source",
+                                ctx=ast.Store(),
+                            )
+                        ],
+                        value=ast.Name(id="_prev_source", ctx=ast.Load()),
+                    ),
+                    ast.Assign(
+                        targets=[
+                            ast.Attribute(
+                                value=ast.Name(id="_rc", ctx=ast.Load()),
+                                attr="line",
+                                ctx=ast.Store(),
+                            )
+                        ],
+                        value=ast.Name(id="_prev_line", ctx=ast.Load()),
+                    ),
+                ],
+            ),
+        ]
         stmts.append(
             ast.Assign(
                 targets=[ast.Name(id="_caller_slots", ctx=ast.Store())],
@@ -675,6 +806,21 @@ def _compile_call_block(self, node: CallBlock) -> list[ast.stmt]:
                 ),
             )
         )
+        for attr, local_name in (
+            ("template_name", "_caller_template_name"),
+            ("source", "_caller_source"),
+            ("line", "_caller_line"),
+        ):
+            stmts.append(
+                ast.Assign(
+                    targets=[ast.Name(id=local_name, ctx=ast.Store())],
+                    value=ast.Attribute(
+                        value=ast.Name(id="_rc", ctx=ast.Load()),
+                        attr=attr,
+                        ctx=ast.Load(),
+                    ),
+                )
+            )
         # Use _caller_wrapper to avoid shadowing the def's _caller parameter
         # (which would cause UnboundLocalError when _def_caller = _caller runs)
         # Wrapper takes (_scope_stack, slot, **_slot_kwargs) so slot functions get
diff --git a/src/kida/render_context.py b/src/kida/render_context.py
index e2715a8..13c3161 100644
--- a/src/kida/render_context.py
+++ b/src/kida/render_context.py
@@ -42,12 +42,22 @@ class _NullRenderContext:
     generated def code that pushes/pops component stack frames.
     """
 
-    __slots__ = ("component_stack", "line", "template_name")
+    __slots__ = (
+        "component_call_line",
+        "component_call_template",
+        "component_stack",
+        "line",
+        "source",
+        "template_name",
+    )
 
     def __init__(self) -> None:
         self.line = 0
         self.component_stack: list[tuple[str, int, str]] = []
         self.template_name: str | None = None
+        self.source: str | None = None
+        self.component_call_template: str | None = None
+        self.component_call_line: int | None = None
 
 
 # Module-level singleton — used as fallback in generated code preambles.
@@ -116,6 +126,13 @@ class RenderContext:
     # Pushed on def entry, popped on def exit. Shows "in card() called from page.html:14".
     component_stack: list[tuple[str, int, str]] = field(default_factory=list)
 
+    # Optional call-site override used by imported macros. During an imported
+    # def call, template_name/source switch to the defining template so errors
+    # inside the def get the right source snippet, but the component stack frame
+    # should still name the caller's template line.
+    component_call_template: str | None = None
+    component_call_line: int | None = None
+
     # Block caching (RFC: kida-template-introspection)
     cached_blocks: dict[str, str] = field(default_factory=dict)
     cached_block_names: frozenset[str] = field(default_factory=frozenset)
@@ -312,6 +329,8 @@ def child_context(
             _meta=self._meta,  # Share metadata with child templates
             template_stack=new_stack,  # Pass stack to child
             component_stack=self.component_stack,  # Share component stack with child
+            component_call_template=self.component_call_template,
+            component_call_line=self.component_call_line,
             # declared_definitions is per-template; the include/extends path
             # overrides this on the child context once the child template
             # has been resolved (see Template._render_scaffold and
@@ -356,6 +375,8 @@ def child_context_for_extends(
             _meta=self._meta,
             template_stack=new_stack,
             component_stack=self.component_stack,  # Share component stack with parent
+            component_call_template=self.component_call_template,
+            component_call_line=self.component_call_line,
         )
 
 
diff --git a/src/kida/template/core.py b/src/kida/template/core.py
index 6dd9eb0..7c2e205 100644
--- a/src/kida/template/core.py
+++ b/src/kida/template/core.py
@@ -876,9 +876,11 @@ def render_stream(self, *args: Any, **kwargs: Any) -> Iterator[str]:
                 suggestion="Ensure the template was compiled with streaming support.",
             )
 
-        with self._render_scaffold(
-            args, kwargs, "render_stream", use_cached_blocks=True, enhance_errors=False
-        ) as (ctx, _render_ctx, blocks_arg):
+        with self._render_scaffold(args, kwargs, "render_stream", use_cached_blocks=True) as (
+            ctx,
+            _render_ctx,
+            blocks_arg,
+        ):
             for chunk in stream_func(ctx, blocks_arg):
                 if chunk is not None:
                     yield chunk
@@ -971,22 +973,33 @@ async def render_stream_async(self, *args: Any, **kwargs: Any) -> AsyncIterator[
                         stats=render_ctx.cache_stats,
                     )
 
-            if async_func is not None:
-                async for chunk in async_func(ctx, blocks_arg):
-                    if chunk is not None:
-                        yield chunk
-            elif sync_func is not None:
-                # Wrap sync stream for API compatibility
-                for chunk in sync_func(ctx, blocks_arg):
-                    if chunk is not None:
-                        yield chunk
-            else:
-                raise TemplateRuntimeError(
-                    f"Template '{self._name or '(inline)'}' has no render_stream function",
-                    template_name=self._name,
-                    code=ErrorCode.NOT_COMPILED,
-                    suggestion="Ensure the template was compiled with streaming support.",
-                )
+            try:
+                if async_func is not None:
+                    async for chunk in async_func(ctx, blocks_arg):
+                        if chunk is not None:
+                            yield chunk
+                elif sync_func is not None:
+                    # Wrap sync stream for API compatibility
+                    for chunk in sync_func(ctx, blocks_arg):
+                        if chunk is not None:
+                            yield chunk
+                else:
+                    raise TemplateRuntimeError(
+                        f"Template '{self._name or '(inline)'}' has no render_stream function",
+                        template_name=self._name,
+                        code=ErrorCode.NOT_COMPILED,
+                        suggestion="Ensure the template was compiled with streaming support.",
+                    )
+            except TemplateRuntimeError:
+                raise
+            except Exception as e:
+                from kida.sandbox import SecurityError
+
+                if isinstance(
+                    e, (UndefinedError, TemplateNotFoundError, TemplateSyntaxError, SecurityError)
+                ):
+                    raise
+                raise enhance_template_error(e, render_ctx, self._source) from e
 
     async def render_block_stream_async(
         self, block_name: str, *args: Any, **kwargs: Any
@@ -1017,16 +1030,27 @@ async def render_block_stream_async(
 
         async with self._fragment_scaffold_async(args, kwargs, "render_block_stream_async") as (
             ctx,
-            _render_ctx,
+            render_ctx,
         ):
-            if inspect.isasyncgenfunction(block_func):
-                async for chunk in block_func(ctx, effective):
-                    if chunk is not None:
-                        yield chunk
-            else:
-                for chunk in block_func(ctx, effective):
-                    if chunk is not None:
-                        yield chunk
+            try:
+                if inspect.isasyncgenfunction(block_func):
+                    async for chunk in block_func(ctx, effective):
+                        if chunk is not None:
+                            yield chunk
+                else:
+                    for chunk in block_func(ctx, effective):
+                        if chunk is not None:
+                            yield chunk
+            except TemplateRuntimeError:
+                raise
+            except Exception as e:
+                from kida.sandbox import SecurityError
+
+                if isinstance(
+                    e, (UndefinedError, TemplateNotFoundError, TemplateSyntaxError, SecurityError)
+                ):
+                    raise
+                raise enhance_template_error(e, render_ctx, self._source) from e
 
     def __repr__(self) -> str:
         return f"<Template {self._name or '(inline)'}>"
diff --git a/src/kida/template/helpers.py b/src/kida/template/helpers.py
index 8795d56..96de221 100644
--- a/src/kida/template/helpers.py
+++ b/src/kida/template/helpers.py
@@ -226,16 +226,31 @@ def _raise_undefined_attr(obj: object, name: str, *, preserve_none: bool = False
     lineno = render_ctx.line if render_ctx else None
     source = render_ctx.source if render_ctx else None
     snippet = build_source_snippet(source, lineno) if source and lineno else None
+    template_stack = list(render_ctx.template_stack) if render_ctx else []
+    component_stack = list(render_ctx.component_stack) if render_ctx else []
+    declared = render_ctx.declared_definitions if render_ctx else None
 
     obj_type = type(obj).__name__
     qual_name = name if obj is None else f"{obj_type}.{name}"
+    if isinstance(obj, Mapping):
+        available_names = frozenset(f"{obj_type}.{key}" for key in obj if isinstance(key, str))
+    elif obj is None:
+        available_names = frozenset()
+    else:
+        available_names = frozenset(
+            f"{obj_type}.{attr}" for attr in dir(obj) if not attr.startswith("_")
+        )
 
     raise UndefinedError(
         qual_name,
         template_name,
         lineno,
+        available_names=available_names,
         source_snippet=snippet,
+        template_stack=template_stack,
+        component_stack=component_stack,
         kind="attribute/key",
+        declared_definitions=declared,
     ) from None
 
 
diff --git a/src/kida/template/render_helpers.py b/src/kida/template/render_helpers.py
index d265efc..b934968 100644
--- a/src/kida/template/render_helpers.py
+++ b/src/kida/template/render_helpers.py
@@ -119,9 +119,13 @@ def __call__(self, *args: object, **kwargs: object) -> object:
         prev_name = render_ctx.template_name
         prev_line = render_ctx.line
         prev_source = render_ctx.source
+        prev_component_call_template = render_ctx.component_call_template
+        prev_component_call_line = render_ctx.component_call_line
         render_ctx.template_name = self._kida_source_template
         render_ctx.line = 0
         render_ctx.source = self._source
+        render_ctx.component_call_template = caller_name
+        render_ctx.component_call_line = caller_line
         if self._needs_outer_ctx:
             kwargs_to_use = {**kwargs, "_outer_ctx": self._defining_namespace}
         else:
@@ -133,6 +137,8 @@ def __call__(self, *args: object, **kwargs: object) -> object:
             render_ctx.template_name = prev_name
             render_ctx.line = prev_line
             render_ctx.source = prev_source
+            render_ctx.component_call_template = prev_component_call_template
+            render_ctx.component_call_line = prev_component_call_line
 
     def __iter__(self) -> Iterator[object]:
         """Raise helpful error when a macro is used in a for loop.
diff --git a/tests/test_diagnostics_contract.py b/tests/test_diagnostics_contract.py
index 454196a..33b4fca 100644
--- a/tests/test_diagnostics_contract.py
+++ b/tests/test_diagnostics_contract.py
@@ -166,3 +166,96 @@ def test_undefined_error_structured_diagnostic_for_framework_views(tmp_path: Pat
     assert "<script>{{ usernme }}</script>" not in html
     assert "K-RUN-001" in html
     assert "page.html:2" in html
+
+
+def test_coalesced_output_preserves_undefined_source_line(tmp_path: Path) -> None:
+    """F-string coalescing must not erase the line used by diagnostics."""
+    (tmp_path / "page.html").write_text(
+        "\n".join(
+            [
+                "<main>",
+                "  <script>{{ usernme }}</script>",
+                "</main>",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    env = Environment(loader=FileSystemLoader(str(tmp_path)))
+
+    with pytest.raises(UndefinedError) as exc_info:
+        env.get_template("page.html").render(username="Ada")
+
+    diagnostic = exc_info.value.to_diagnostic()
+    assert diagnostic.location.line == 2
+    assert diagnostic.source_snippet is not None
+    assert diagnostic.source_snippet.error_line == 2
+
+
+def test_attribute_undefined_diagnostic_keeps_component_stack() -> None:
+    """Attribute/key misses carry the same stack context as variable misses."""
+
+    class User:
+        name = "Ada"
+
+    template = Environment().from_string(
+        "{% def card(user) %}{{ user.nmae }}{% end %}{{ card(user) }}",
+        name="page.html",
+    )
+
+    with pytest.raises(UndefinedError) as exc_info:
+        template.render(user=User())
+
+    diagnostic = exc_info.value.to_diagnostic()
+    assert diagnostic.kind == "attribute/key"
+    assert diagnostic.suggestion == "User.name"
+    assert diagnostic.component_stack
+    assert diagnostic.component_stack[0].template == "page.html"
+    assert diagnostic.component_stack[0].line == 1
+    assert diagnostic.component_stack[0].name == "card"
+
+
+def test_imported_macro_slot_error_points_to_caller_template(tmp_path: Path) -> None:
+    """Slot bodies from imported components report the caller source."""
+    (tmp_path / "components.html").write_text(
+        "{% def card() %}<section>{% slot %}</section>{% end %}",
+        encoding="utf-8",
+    )
+    (tmp_path / "page.html").write_text(
+        "\n".join(
+            [
+                '{% from "components.html" import card %}',
+                "{% call card() %}",
+                "  {{ missing_in_slot }}",
+                "{% end %}",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    env = Environment(loader=FileSystemLoader(str(tmp_path)))
+
+    with pytest.raises(UndefinedError) as exc_info:
+        env.get_template("page.html").render()
+
+    diagnostic = exc_info.value.to_diagnostic()
+    assert diagnostic.location.template == "page.html"
+    assert diagnostic.location.line == 3
+    assert diagnostic.component_stack
+    assert diagnostic.component_stack[0].template == "page.html"
+    assert diagnostic.component_stack[0].line == 2
+    assert all(frame.line > 0 for frame in diagnostic.component_stack)
+
+
+def test_render_stream_enhances_generic_runtime_errors() -> None:
+    """Streaming diagnostics match render() for generic runtime exceptions."""
+    template = Environment().from_string("{{ 1 / zero }}", name="calc.html")
+
+    with pytest.raises(Exception) as exc_info:
+        list(template.render_stream(zero=0))
+
+    exc = exc_info.value
+    assert exc.__class__.__name__ == "TemplateRuntimeError"
+    assert isinstance(exc.__cause__, ZeroDivisionError)
+    assert exc.template_name == "calc.html"
+    assert exc.lineno == 1

From d1342b92c5a7399715e8b4bd6dccd4bdf54913d3 Mon Sep 17 00:00:00 2001
From: Lawrence Lane <llane@nvidia.com>
Date: Fri, 15 May 2026 21:41:27 -0400
Subject: [PATCH 3/7] feat: align diagnostic render surfaces

---
 src/kida/exceptions.py             | 70 ++++++++++++++++++++++--------
 tests/test_diagnostics_contract.py | 30 +++++++++++++
 2 files changed, 82 insertions(+), 18 deletions(-)

diff --git a/src/kida/exceptions.py b/src/kida/exceptions.py
index 9668d21..805cb3b 100644
--- a/src/kida/exceptions.py
+++ b/src/kida/exceptions.py
@@ -414,6 +414,42 @@ def format_html_fragment(self) -> str:
         parts.append("</section>")
         return "".join(parts)
 
+    def format_markdown(self) -> str:
+        """Render a GitHub-flavored Markdown diagnostic from plain fields."""
+        from kida.utils.markdown_escape import markdown_escape
+
+        heading = f"### {markdown_escape(self.code)}: {markdown_escape(self.title)}"
+        if not self.code:
+            heading = f"### {markdown_escape(self.title)}"
+        parts = [
+            heading,
+            "",
+            markdown_escape(self.message),
+            "",
+            f"**Location:** `{markdown_escape(self.location.format())}`",
+        ]
+        if self.source_snippet:
+            parts.extend(["", "```text"])
+            for lineno, content in self.source_snippet.lines:
+                marker = ">" if lineno == self.source_snippet.error_line else " "
+                parts.append(f"{marker}{lineno:4} | {content}")
+            if self.source_snippet.column is not None:
+                caret = " " * self.source_snippet.column + "^"
+                parts.append(f"     | {caret}")
+            parts.append("```")
+        if self.hints:
+            parts.extend(["", "**Hints:**"])
+            parts.extend(f"- {markdown_escape(hint)}" for hint in self.hints)
+        if self.component_stack:
+            parts.extend(["", "**Component stack:**"])
+            parts.extend(f"- `{markdown_escape(frame.format())}`" for frame in self.component_stack)
+        if self.template_stack:
+            parts.extend(["", "**Template stack:**"])
+            parts.extend(f"- `{markdown_escape(frame.format())}`" for frame in self.template_stack)
+        if self.docs_url:
+            parts.extend(["", f"[Documentation]({self.docs_url})"])
+        return "\n".join(parts)
+
 
 def build_source_snippet(
     source: str,
@@ -1003,46 +1039,44 @@ def to_diagnostic(self) -> TemplateDiagnostic:
     def format_compact(self) -> str:
         """Format undefined variable error as structured terminal diagnostic."""
         terminal = _terminal()
+        diagnostic = self.to_diagnostic()
         parts: list[str] = []
 
         # Header: code + message
-        location = self.template
-        if self.lineno:
-            location += f":{self.lineno}"
         msg = terminal.format_error_header(
-            self.code.value if self.code else None,
-            f"Undefined variable '{self.name}' in {terminal.location(location)}",
+            diagnostic.code,
+            f"Undefined {diagnostic.kind} '{self.name}' in "
+            f"{terminal.location(diagnostic.location.format())}",
         )
 
         # "Did you mean?" suggestion
-        if self.suggestion:
-            suggested = terminal.suggestion(self.suggestion)
+        if diagnostic.suggestion:
+            suggested = terminal.suggestion(diagnostic.suggestion)
             msg += f". Did you mean '{suggested}'?"
         parts.append(msg)
 
         # Source snippet
-        if self.source_snippet:
-            parts.append(self.source_snippet.format())
+        if diagnostic.source_snippet:
+            parts.append(diagnostic.source_snippet.format())
 
         # Component stack trace (Sprint 1.3)
-        if self.component_stack:
+        if diagnostic.component_stack:
             parts.append("")
             parts.append(format_component_stack(self.component_stack))
 
         # Template stack trace (Feature 2.1)
-        if self.template_stack:
+        if diagnostic.template_stack:
             parts.append("")
             parts.append(format_template_stack(self.template_stack))
 
         # Hint
-        hint_text = self._hint_text()
-        parts.append(f"  {terminal.hint('Hint:')} {hint_text}")
-        nullsafe = self._nullsafe_hint_text()
-        if nullsafe:
-            parts.append(f"  {terminal.hint('Hint:')} {nullsafe}")
+        for hint in diagnostic.hints:
+            if hint.startswith("Did you mean "):
+                continue
+            parts.append(f"  {terminal.hint('Hint:')} {hint}")
 
         # Docs URL
-        if self.code:
-            parts.append(f"  {terminal.dim_text('Docs:')} {terminal.docs_url(self.code.docs_url)}")
+        if diagnostic.docs_url:
+            parts.append(f"  {terminal.dim_text('Docs:')} {terminal.docs_url(diagnostic.docs_url)}")
 
         return "\n".join(parts)
diff --git a/tests/test_diagnostics_contract.py b/tests/test_diagnostics_contract.py
index 33b4fca..d7944b9 100644
--- a/tests/test_diagnostics_contract.py
+++ b/tests/test_diagnostics_contract.py
@@ -259,3 +259,33 @@ def test_render_stream_enhances_generic_runtime_errors() -> None:
     assert isinstance(exc.__cause__, ZeroDivisionError)
     assert exc.template_name == "calc.html"
     assert exc.lineno == 1
+
+
+def test_undefined_diagnostic_markdown_escapes_surrounding_text(tmp_path: Path) -> None:
+    """Markdown diagnostics share the same data without escaping code fences twice."""
+    (tmp_path / "page.html").write_text(
+        "## heading\n{{ missing_value }} | @here",
+        encoding="utf-8",
+    )
+
+    env = Environment(loader=FileSystemLoader(str(tmp_path)), fstring_coalescing=False)
+
+    with pytest.raises(UndefinedError) as exc_info:
+        env.get_template("page.html").render()
+
+    markdown = exc_info.value.to_diagnostic().format_markdown()
+    assert "### K-RUN-001: Undefined variable" in markdown
+    assert "**Location:** `page.html:2`" in markdown
+    assert "```text" in markdown
+    assert ">   2 | {{ missing_value }} | @here" in markdown
+    assert "\\#\\# heading" not in markdown
+
+
+def test_format_compact_uses_structured_kind() -> None:
+    """Terminal compact output stays aligned with diagnostic kind."""
+    err = UndefinedError("dict.nickname", kind="attribute/key")
+
+    compact = err.format_compact()
+
+    assert "Undefined attribute/key" in compact
+    assert "x?.y" in compact

From 134110b3f7034b6b62d5a54c72a70081bfdc2564 Mon Sep 17 00:00:00 2001
From: Lawrence Lane <llane@nvidia.com>
Date: Fri, 15 May 2026 21:42:43 -0400
Subject: [PATCH 4/7] feat: add standalone diagnostic html page

---
 src/kida/exceptions.py             | 91 ++++++++++++++++++++++++++++++
 tests/test_diagnostics_contract.py | 23 ++++++++
 2 files changed, 114 insertions(+)

diff --git a/src/kida/exceptions.py b/src/kida/exceptions.py
index 805cb3b..8e75edc 100644
--- a/src/kida/exceptions.py
+++ b/src/kida/exceptions.py
@@ -414,6 +414,97 @@ def format_html_fragment(self) -> str:
         parts.append("</section>")
         return "".join(parts)
 
+    def format_html_page(self, *, page_title: str = "Kida Template Error") -> str:
+        """Render a standalone escaped HTML diagnostic page."""
+        summary_items = [
+            ("Error", self.title),
+            ("Location", self.location.format()),
+        ]
+        if self.suggestion:
+            summary_items.append(("Closest name", self.suggestion))
+        summary_items.extend((key.replace("_", " ").title(), value) for key, value in self.metadata)
+
+        summary = "".join(
+            "<div><dt>" + html_escape(label) + "</dt><dd>" + html_escape(value) + "</dd></div>"
+            for label, value in summary_items
+        )
+        primary_hint = self.hints[0] if self.hints else "Inspect the template location above."
+        css = "".join(
+            [
+                "*{box-sizing:border-box}",
+                "body{margin:0;background:#10141f;color:#d8dee9;",
+                "font:14px/1.55 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}",
+                ".wrap{max-width:1120px;margin:0 auto;padding:32px}",
+                ".hero{border:1px solid #384258;background:#171d2b;border-radius:8px;padding:20px}",
+                ".code{color:#ff7b93;font-weight:700}",
+                ".message{color:#f2cc8f;margin:12px 0 0;white-space:pre-wrap}",
+                ".fix{margin-top:16px;padding:12px 14px;background:#10291d;",
+                "border:1px solid #2d6a4f;border-radius:6px;color:#b7f7c9}",
+                ".facts{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));",
+                "gap:10px;margin:18px 0 0}",
+                ".facts div{border:1px solid #30394d;border-radius:6px;",
+                "padding:10px;background:#111827}",
+                ".facts dt{color:#8ea4c8;font-size:12px;text-transform:uppercase}",
+                ".facts dd{margin:4px 0 0;word-break:break-word}",
+                ".panel{margin-top:20px;border:1px solid #30394d;border-radius:8px;",
+                "background:#121827;overflow:hidden}",
+                ".panel h2{font-size:14px;margin:0;padding:10px 14px;",
+                "background:#192235;color:#9cc4ff}",
+                ".panel pre{margin:0;padding:14px;overflow:auto}",
+                ".panel ol{margin:0;padding:12px 14px 12px 34px}",
+                ".panel li{margin:4px 0}",
+                ".docs a{color:#9cc4ff}",
+                ".trace-note{color:#8ea4c8;margin-top:18px}",
+            ]
+        )
+        parts = [
+            "<!doctype html>",
+            '<html lang="en"><head><meta charset="utf-8">',
+            '<meta name="viewport" content="width=device-width, initial-scale=1">',
+            f"<title>{html_escape(page_title)}</title>",
+            f'<style>{css}</style></head><body><main class="wrap">',
+            '<section class="hero">',
+            f'<div class="code">{html_escape(self.code or "Kida")}</div>',
+            f"<h1>{html_escape(self.title)}</h1>",
+            f'<p class="message">{html_escape(self.message)}</p>',
+            f'<div class="fix"><strong>First fix:</strong> {html_escape(primary_hint)}</div>',
+            f'<dl class="facts">{summary}</dl>',
+            "</section>",
+        ]
+        if self.source_snippet:
+            parts.append('<section class="panel"><h2>Template Source</h2><pre><code>')
+            for lineno, content in self.source_snippet.lines:
+                marker = ">" if lineno == self.source_snippet.error_line else " "
+                parts.append(f"{marker}{lineno:4} | {html_escape(content)}\n")
+            if self.source_snippet.column is not None:
+                caret = " " * self.source_snippet.column + "^"
+                parts.append(f"     | {html_escape(caret)}\n")
+            parts.append("</code></pre></section>")
+        if len(self.hints) > 1:
+            parts.append('<section class="panel"><h2>Other Fix Options</h2><ol>')
+            parts.extend(f"<li>{html_escape(hint)}</li>" for hint in self.hints[1:])
+            parts.append("</ol></section>")
+        if self.component_stack:
+            parts.append('<section class="panel"><h2>Component Path</h2><ol>')
+            parts.extend(
+                f"<li>{html_escape(frame.format())}</li>" for frame in self.component_stack
+            )
+            parts.append("</ol></section>")
+        if self.template_stack:
+            parts.append('<section class="panel"><h2>Template Path</h2><ol>')
+            parts.extend(f"<li>{html_escape(frame.format())}</li>" for frame in self.template_stack)
+            parts.append("</ol></section>")
+        parts.append(
+            '<p class="trace-note">Python traceback frames are secondary for Kida template errors; '
+            "the template location above is authoritative.</p>"
+        )
+        if self.docs_url:
+            parts.append(
+                f'<p class="docs"><a href="{html_escape(self.docs_url)}">Kida error documentation</a></p>'
+            )
+        parts.append("</main></body></html>")
+        return "".join(parts)
+
     def format_markdown(self) -> str:
         """Render a GitHub-flavored Markdown diagnostic from plain fields."""
         from kida.utils.markdown_escape import markdown_escape
diff --git a/tests/test_diagnostics_contract.py b/tests/test_diagnostics_contract.py
index d7944b9..15feb4f 100644
--- a/tests/test_diagnostics_contract.py
+++ b/tests/test_diagnostics_contract.py
@@ -289,3 +289,26 @@ def test_format_compact_uses_structured_kind() -> None:
 
     assert "Undefined attribute/key" in compact
     assert "x?.y" in compact
+
+
+def test_undefined_diagnostic_html_page_leads_with_fix(tmp_path: Path) -> None:
+    """Standalone HTML page keeps the actionable diagnostic before traceback copy."""
+    (tmp_path / "page.html").write_text(
+        "<main>{{ usernme }}</main>",
+        encoding="utf-8",
+    )
+    env = Environment(loader=FileSystemLoader(str(tmp_path)), fstring_coalescing=False)
+
+    with pytest.raises(UndefinedError) as exc_info:
+        env.get_template("page.html").render(username="Ada")
+
+    page = exc_info.value.to_diagnostic().format_html_page()
+
+    assert page.startswith("<!doctype html>")
+    assert "First fix:" in page
+    assert "Did you mean &#x27;username&#x27;?" in page
+    assert "Template Source" in page
+    assert "&lt;main&gt;{{ usernme }}&lt;/main&gt;" in page
+    assert "<main>{{ usernme }}</main>" not in page
+    assert page.index("First fix:") < page.index("Template Source")
+    assert page.index("Template Source") < page.index("Python traceback frames are secondary")

From 25b7ee7382e3516687498bcd26a577396ae08bda Mon Sep 17 00:00:00 2001
From: Lawrence Lane <llane@nvidia.com>
Date: Fri, 15 May 2026 21:44:01 -0400
Subject: [PATCH 5/7] docs: document structured error diagnostics

---
 .../troubleshooting/undefined-variable.md     | 26 ++++++++++++++
 site/content/docs/usage/error-handling.md     | 35 +++++++++++++++++--
 .../docs/usage/framework-integration.md       | 24 +++++++++++++
 3 files changed, 82 insertions(+), 3 deletions(-)

diff --git a/site/content/docs/troubleshooting/undefined-variable.md b/site/content/docs/troubleshooting/undefined-variable.md
index 814b6c7..b5d742a 100644
--- a/site/content/docs/troubleshooting/undefined-variable.md
+++ b/site/content/docs/troubleshooting/undefined-variable.md
@@ -29,6 +29,13 @@ Debug `UndefinedError` exceptions.
 UndefinedError: Undefined variable 'usre' in page.html:5
 ```
 
+Recent Kida diagnostics also carry structured fields for frameworks:
+
+- `to_diagnostic().location` — template name, line, and optional column
+- `to_diagnostic().source_snippet` — surrounding source lines
+- `to_diagnostic().hints` — ordered next actions
+- `to_diagnostic().template_stack` and `.component_stack` — render path context
+
 ## Common Causes
 
 :::{dropdown} Typo in variable name
@@ -73,6 +80,22 @@ Ensure all template variables are passed in `render()`.
 Verify object attributes match your code.
 :::
 
+:::{dropdown} Imported component slot uses a missing caller value
+:icon: layers
+
+```kida
+{% from "components/card.html" import card %}
+
+{% call card() %}
+  {{ missing_in_slot }}
+{% end %}
+```
+
+Kida reports this against the caller template line that owns the slot body, not
+the imported component file. Use the component stack to see which component was
+rendering when the slot failed.
+:::
+
 :::{dropdown} Nested object is None or missing
 :icon: layers
 
@@ -94,6 +117,9 @@ Under strict mode (the default), `{% if page.parent %}` alone raises if `parent`
 
 ## Solutions
 
+Hints are ordered by confidence. A close typo match appears first; optional
+value patterns such as `default(...)`, `??`, or null-safe access follow.
+
 ### Use default Filter
 
 ```kida
diff --git a/site/content/docs/usage/error-handling.md b/site/content/docs/usage/error-handling.md
index 5e5ff6c..e6a7079 100644
--- a/site/content/docs/usage/error-handling.md
+++ b/site/content/docs/usage/error-handling.md
@@ -267,7 +267,23 @@ The compact format includes:
 - **Hint** with suggestions (typo corrections, `default` filter usage)
 - **Docs link** to the relevant error code documentation
 
-This is the recommended format for frameworks that wrap Kida errors (like Chirp and Bengal).
+Use `format_compact()` for terminal output and logs. Framework debug pages should
+prefer `UndefinedError.to_diagnostic()` so they can render the same code,
+location, source snippet, hints, documentation URL, template stack, and component
+stack without parsing terminal text.
+
+```python
+from kida import UndefinedError
+
+try:
+    template.render()
+except UndefinedError as exc:
+    diagnostic = exc.to_diagnostic()
+    html = diagnostic.format_html_page()
+```
+
+The diagnostic payload stores plain strings. HTML, Markdown, and terminal
+escaping happen only in the final renderer.
 
 ## Source Snippets
 
@@ -283,7 +299,8 @@ except UndefinedError as e:
     if snippet:
         print(snippet.lines)       # List of (line_number, line_text) tuples
         print(snippet.error_line)  # The line number with the error
-        print(snippet.filename)    # Template filename
+        print(e.template)          # Template name
+        print(e.lineno)            # Error line
 ```
 
 You can also build snippets manually with `build_source_snippet()`:
@@ -307,11 +324,23 @@ Fix: Check for typos, ensure variable is passed to render().
 ### Attribute Error
 
 ```
-UndefinedError: 'dict' object has no attribute 'nmae'
+UndefinedError: Undefined attribute/key 'User.nmae' in page.html:5
 ```
 
 Fix: Check attribute spelling, verify object type.
 
+## Reading Template and Component Stacks
+
+`template_stack` explains how rendering reached another template through
+`include`, `extends`, or imported macros. `component_stack` explains which
+`{% def %}` components were active. In an HTML error view, show the source
+location first, then these stacks as supporting context. Python traceback frames
+from generated code are secondary.
+
+For imported components with slots, Kida reports slot-body errors against the
+caller template while still keeping the imported component path in the component
+stack.
+
 ### Type Error in Filter
 
 ```
diff --git a/site/content/docs/usage/framework-integration.md b/site/content/docs/usage/framework-integration.md
index 627023d..1b4faa4 100644
--- a/site/content/docs/usage/framework-integration.md
+++ b/site/content/docs/usage/framework-integration.md
@@ -208,6 +208,30 @@ class KidaAdapter:
 
 [Chirp](https://github.com/lbliii/chirp) uses this pattern in `KidaAdapter`.
 
+## Framework Error Views
+
+Frameworks should render Kida diagnostics from structured exception data, not by
+scraping `str(exc)` or terminal-oriented `format_compact()` output.
+
+```python
+from kida import TemplateError, UndefinedError
+
+try:
+    html = template.render(context)
+except UndefinedError as exc:
+    diagnostic = exc.to_diagnostic()
+    html = diagnostic.format_html_page()
+except TemplateError as exc:
+    html = f"<pre>{exc.format_compact()}</pre>"
+```
+
+For `UndefinedError`, the diagnostic payload includes the error code, kind,
+missing name, template location, source snippet, ordered hints, documentation
+URL, template stack, and component stack. The built-in HTML and Markdown
+renderers escape source text and names at the final surface. If a framework
+builds its own page, it should keep the Kida template location as authoritative
+and collapse generated Python traceback frames by default.
+
 ## Case Studies
 
 ### Bengal (Static Site Generator)

From 216e221d6c3b4d6feb2938b3527ec0ad8eb709ed Mon Sep 17 00:00:00 2001
From: Lawrence Lane <llane@nvidia.com>
Date: Fri, 15 May 2026 21:44:52 -0400
Subject: [PATCH 6/7] fix: declare coalescing line marker contract

---
 src/kida/compiler/coalescing.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/kida/compiler/coalescing.py b/src/kida/compiler/coalescing.py
index 3c15323..1b9d970 100644
--- a/src/kida/compiler/coalescing.py
+++ b/src/kida/compiler/coalescing.py
@@ -71,6 +71,8 @@ def _compile_node(self, node: Node) -> list[ast.stmt]: ...
         # From Compiler core
         def _emit_output(self, value_expr: ast.expr) -> ast.stmt: ...
 
+        def _make_line_marker(self, lineno: int) -> ast.stmt: ...
+
         # From BasicStatementMixin
         @staticmethod
         def _expr_may_produce_none(node: Expr) -> bool: ...

From 604a1cc1f40bcba3832bd845fe75c04750290c6e Mon Sep 17 00:00:00 2001
From: Lawrence Lane <llane@nvidia.com>
Date: Fri, 22 May 2026 08:40:26 -0400
Subject: [PATCH 7/7] fix: restore async stream exception contract

---
 src/kida/template/core.py            | 72 ++++++++++------------------
 tests/test_compiler_expr_dispatch.py | 10 ++--
 2 files changed, 30 insertions(+), 52 deletions(-)

diff --git a/src/kida/template/core.py b/src/kida/template/core.py
index 7c2e205..363e751 100644
--- a/src/kida/template/core.py
+++ b/src/kida/template/core.py
@@ -973,33 +973,22 @@ async def render_stream_async(self, *args: Any, **kwargs: Any) -> AsyncIterator[
                         stats=render_ctx.cache_stats,
                     )
 
-            try:
-                if async_func is not None:
-                    async for chunk in async_func(ctx, blocks_arg):
-                        if chunk is not None:
-                            yield chunk
-                elif sync_func is not None:
-                    # Wrap sync stream for API compatibility
-                    for chunk in sync_func(ctx, blocks_arg):
-                        if chunk is not None:
-                            yield chunk
-                else:
-                    raise TemplateRuntimeError(
-                        f"Template '{self._name or '(inline)'}' has no render_stream function",
-                        template_name=self._name,
-                        code=ErrorCode.NOT_COMPILED,
-                        suggestion="Ensure the template was compiled with streaming support.",
-                    )
-            except TemplateRuntimeError:
-                raise
-            except Exception as e:
-                from kida.sandbox import SecurityError
-
-                if isinstance(
-                    e, (UndefinedError, TemplateNotFoundError, TemplateSyntaxError, SecurityError)
-                ):
-                    raise
-                raise enhance_template_error(e, render_ctx, self._source) from e
+            if async_func is not None:
+                async for chunk in async_func(ctx, blocks_arg):
+                    if chunk is not None:
+                        yield chunk
+            elif sync_func is not None:
+                # Wrap sync stream for API compatibility
+                for chunk in sync_func(ctx, blocks_arg):
+                    if chunk is not None:
+                        yield chunk
+            else:
+                raise TemplateRuntimeError(
+                    f"Template '{self._name or '(inline)'}' has no render_stream function",
+                    template_name=self._name,
+                    code=ErrorCode.NOT_COMPILED,
+                    suggestion="Ensure the template was compiled with streaming support.",
+                )
 
     async def render_block_stream_async(
         self, block_name: str, *args: Any, **kwargs: Any
@@ -1030,27 +1019,16 @@ async def render_block_stream_async(
 
         async with self._fragment_scaffold_async(args, kwargs, "render_block_stream_async") as (
             ctx,
-            render_ctx,
+            _render_ctx,
         ):
-            try:
-                if inspect.isasyncgenfunction(block_func):
-                    async for chunk in block_func(ctx, effective):
-                        if chunk is not None:
-                            yield chunk
-                else:
-                    for chunk in block_func(ctx, effective):
-                        if chunk is not None:
-                            yield chunk
-            except TemplateRuntimeError:
-                raise
-            except Exception as e:
-                from kida.sandbox import SecurityError
-
-                if isinstance(
-                    e, (UndefinedError, TemplateNotFoundError, TemplateSyntaxError, SecurityError)
-                ):
-                    raise
-                raise enhance_template_error(e, render_ctx, self._source) from e
+            if inspect.isasyncgenfunction(block_func):
+                async for chunk in block_func(ctx, effective):
+                    if chunk is not None:
+                        yield chunk
+            else:
+                for chunk in block_func(ctx, effective):
+                    if chunk is not None:
+                        yield chunk
 
     def __repr__(self) -> str:
         return f"<Template {self._name or '(inline)'}>"
diff --git a/tests/test_compiler_expr_dispatch.py b/tests/test_compiler_expr_dispatch.py
index f96ec86..34ac505 100644
--- a/tests/test_compiler_expr_dispatch.py
+++ b/tests/test_compiler_expr_dispatch.py
@@ -181,21 +181,21 @@ def test_dispatch_table_methods_exist():
 # with --update-snapshots (not implemented) or copy hashes from the
 # failure output.
 _EXPECTED_AST_HASHES: dict[str, str] = {
-    "access": "71fc549f50efb593",
+    "access": "2cf0aa9eb1ed33d7",
     "binop": "c44d54e6197f759f",
     "child": "7866afbc6d92b913",
-    "const_and_name": "eb85c44d327fe665",
+    "const_and_name": "fcbe869b0bc9b79f",
     "containers": "4aeb3987abfd6e5a",
-    "def_and_call": "fcf2611c427b1fc3",
+    "def_and_call": "93ed61715906e362",
     "default_filter": "24396f574facd156",
-    "filters": "619237bf9d159a10",
+    "filters": "78c311f2539e4bc1",
     "for_loop": "62fb937187a114fd",
     "funccall": "2893731dd74f67e9",
     "listcomp": "265b0ac499dde785",
     "nested": "b375919b692f1c7f",
     "null_coalesce": "7c595473ee6e6efa",
     "operators": "88521c06e38ee0ce",
-    "optional_access": "a65a5bfb9bf29f48",
+    "optional_access": "71d13f8b4a699496",
     "optional_filter": "2cd7710940fb25b6",
     "range_literal": "9e1252f82c695e77",
     "safe_pipeline": "e488e7f6739b692d",