@barefootjs/jinja 0.1.0

package/python/tests/test_helper_vectors.py

@@ -0,0 +1,288 @@
+"""Golden helper-vector conformance, ported from
+packages/adapter-perl/t/helper_vectors.t.
+
+Runs `packages/adapter-tests/vectors/vectors.json` -- generated from
+the JS reference implementations (spec/template-helpers.md) -- against this
+package's `BarefootJS` runtime. One binding per canonical helper id in the
+spec catalogue, bound to the exact code shape a compiled Jinja template
+would execute (a `bf.<method>(...)` call, or the native Python operator the
+adapter emits for `add`/`sub`/`mul`/`div`/`neg`, mirroring how
+`helper_vectors.t` binds those to native Perl operators).
+
+Per spec/template-helpers.md's "Adapter status model", this backend's
+divergences from the JS-normative expect live in
+`tests/vector-divergences.json` (package-local, next to this file) -- keyed
+by `fn/note`, mirroring the Perl harness's `%DIVERGENCES` table exactly in
+spirit (values differ where Python's actual behaviour differs from Perl's).
+This harness still fails on stale or dead declarations in that file.
+
+Skipped everywhere the golden vectors file isn't available (i.e. outside a
+monorepo checkout), matching the Perl/Go harnesses' `skip_all` policy.
+"""
+
+from __future__ import annotations
+
+import builtins
+import json
+import math
+import os
+import unittest
+
+from barefootjs import BarefootJS
+from barefootjs.backend_jinja import default_json_encoder
+
+VECTORS_PATH = os.path.join(
+    os.path.dirname(__file__), "..", "..", "..", "adapter-tests", "vectors", "vectors.json"
+)
+DIVERGENCES_PATH = os.path.join(os.path.dirname(__file__), "vector-divergences.json")
+
+
+class _PureBackend:
+    """Pure-Python backend (no Jinja Environment needed) -- `json` is the
+    only helper that reaches the backend."""
+
+    def encode_json(self, data):
+        return default_json_encoder(data)
+
+    def mark_raw(self, s):
+        return s
+
+    def materialize(self, value):
+        return value() if callable(value) else value
+
+    def render_named(self, *args, **kwargs):
+        return ""
+
+
+bf = BarefootJS(None, {"backend": _PureBackend()})
+
+
+def _truthy_pred(field):
+    return lambda item: item.get(field) if isinstance(item, dict) else None
+
+
+def _field_eq_pred(field, value):
+    # Python's `==` already distinguishes JS-typed operands correctly
+    # (int 2 != str "2"), unlike Perl's `eq`-based approach which needed a
+    # looks_like_number dispatch to fake the distinction -- see the
+    # runtime.py module docstring's `includes` divergence note.
+    return lambda item: isinstance(item, dict) and item.get(field) == value
+
+
+def _bind_sort(recv, *spec):
+    keys = []
+    spec = list(spec)
+    while len(spec) >= 4:
+        kind, name, compare_type, direction = spec[:4]
+        spec = spec[4:]
+        keys.append(
+            {"key_kind": kind, "key": name, "compare_type": compare_type, "direction": direction}
+        )
+    return bf.sort(recv, {"keys": keys})
+
+
+def _bind_reduce(recv, op, key_kind, key, rtype, init, direction):
+    seed = float(init) if rtype == "numeric" else init
+    return bf.reduce(
+        recv,
+        {"op": op, "key_kind": key_kind, "key": key, "type": rtype, "init": seed, "direction": direction},
+    )
+
+
+def _bind_flat_map_tuple(recv, *flat):
+    flat = list(flat)
+    specs = []
+    while len(flat) >= 2:
+        specs.append((flat[0], flat[1]))
+        flat = flat[2:]
+    return bf.flat_map_tuple(recv, *specs)
+
+
+# One binding per canonical helper id. `add`/`sub`/`mul`/`div`/`neg` are not
+# BarefootJS methods (matching the Perl port -- the adapter lowers JS
+# `+`/`-`/`*`/`/`/unary `-` to the native template-language operator, not a
+# `bf.` call); `mod` DOES route through `bf.mod` since the plan requires the
+# Jinja emitter to use `bf.mod` for JS `%` (Python `%` differs from JS `%` on
+# negative operands, unlike native `+`/`-`/`*`/`/`).
+BINDINGS = {
+    "add": lambda a, b: a + b,
+    "sub": lambda a, b: a - b,
+    "mul": lambda a, b: a * b,
+    "div": lambda a, b: a / b,
+    "mod": lambda a, b: bf.mod(a, b),
+    "neg": lambda a: -a,
+    "string": bf.string,
+    "json": bf.json,
+    "number": bf.number,
+    "floor": bf.floor,
+    "ceil": bf.ceil,
+    "round": bf.round,
+    "to_fixed": lambda *a: bf.to_fixed(*a),
+    "lower": bf.lc,
+    "upper": bf.uc,
+    "trim": bf.trim,
+    "starts_with": lambda *a: bf.starts_with(*a),
+    "ends_with": lambda *a: bf.ends_with(*a),
+    "replace": lambda *a: bf.replace(*a),
+    "repeat": lambda *a: bf.repeat(*a),
+    "pad_start": lambda *a: bf.pad_start(*a),
+    "pad_end": lambda *a: bf.pad_end(*a),
+    "split": lambda *a: bf.split(*a),
+    "len": bf.length,
+    "at": lambda *a: bf.at(*a),
+    "includes": lambda *a: bf.includes(*a),
+    "index_of": lambda *a: bf.index_of(*a),
+    "last_index_of": lambda *a: bf.last_index_of(*a),
+    "concat": lambda a, b: bf.concat(a, b),
+    # The adapters always pass three value args (None for an absent end) --
+    # mirror that exact shape, like helper_vectors.t does.
+    "slice": lambda recv, start, end=None: bf.slice(recv, start, end),
+    "reverse": bf.reverse,
+    "flat": lambda *a: bf.flat(*a),
+    "flat_dynamic": lambda *a: bf.flat_dynamic(*a),
+    "join": lambda *a: bf.join(*a),
+    "arr": lambda *a: list(a),
+    # Mirrors the JS `arr.filter(Boolean)` lowering, using JS truthiness.
+    "filter_truthy": lambda arr: [x for x in arr if bf.truthy(x)],
+    "search_params_get": lambda q, k: BarefootJS.search_params(q).get(k),
+    "query": lambda *a: bf.query(*a),
+    # Higher-order entries arrive in the canonical projection form (spec:
+    # items + field [+ value]); rebuild the predicate the adapter compiles.
+    "every": lambda items, field: bf.every(items, _truthy_pred(field)),
+    "some": lambda items, field: bf.some(items, _truthy_pred(field)),
+    "filter": lambda items, field, value: bf.filter(items, _field_eq_pred(field, value)),
+    "find": lambda items, field, value: bf.find(items, _field_eq_pred(field, value)),
+    "find_index": lambda items, field, value: bf.find_index(items, _field_eq_pred(field, value)),
+    "find_last": lambda items, field, value: bf.find_last(items, _field_eq_pred(field, value)),
+    "find_last_index": lambda items, field, value: bf.find_last_index(
+        items, _field_eq_pred(field, value)
+    ),
+    "sort": _bind_sort,
+    "reduce": _bind_reduce,
+    "flat_map": lambda *a: bf.flat_map(*a),
+    "flat_map_tuple": _bind_flat_map_tuple,
+}
+
+# Per-backend status declarations (spec/template-helpers.md "Adapter status
+# model"), loaded from tests/vector-divergences.json (package-local, always
+# present regardless of whether the golden vectors themselves are available
+# outside the monorepo checkout). Forms:
+#   {"expect": <value>}                  assert the pinned value (exact, no
+#                                         numeric coercion -- deliberately
+#                                         stricter than the spec's
+#                                         value-compat `_match` so an
+#                                         int-vs-float rounding accident
+#                                         can't hide behind the comparison)
+#   {"expect": {"$num": "NaN"}}          assert a real NaN result
+#   {"throws": true, "exception": <n>}   assert the call raises the named
+#                                         builtin exception (default
+#                                         `Exception` if `exception` absent)
+with open(DIVERGENCES_PATH, encoding="utf-8") as _fh:
+    _divergences_doc = json.load(_fh)
+DIVERGENCES = _divergences_doc["divergences"]
+UNSUPPORTED = _divergences_doc["unsupported"]
+
+
+def _match(got, expect):
+    """Spec value-compat comparison against a JSON-decoded expect --
+    sentinel hashes, booleans by truthiness, numbers numerically,
+    arrays/hashes recursively."""
+    if expect is None:
+        return got is None
+    if isinstance(expect, dict) and "$num" in expect:
+        kind = expect["$num"]
+        if isinstance(got, bool) or not isinstance(got, (int, float)):
+            return False
+        g = float(got)
+        if kind == "NaN":
+            return g != g
+        inf = float("inf")
+        return g == (inf if kind == "Infinity" else -inf)
+    if isinstance(expect, bool):
+        return bool(got) == expect
+    if isinstance(expect, list):
+        if not isinstance(got, list) or len(got) != len(expect):
+            return False
+        return all(_match(g, e) for g, e in zip(got, expect))
+    if isinstance(expect, dict):
+        if not isinstance(got, dict) or len(got) != len(expect):
+            return False
+        return all(k in got and _match(got[k], v) for k, v in expect.items())
+    if got is None or isinstance(got, (list, dict)):
+        return False
+    if isinstance(expect, (int, float)) and not isinstance(expect, bool):
+        if isinstance(got, bool) or not isinstance(got, (int, float)):
+            return False
+        # Exact comparison when both are Python `int` (JSON-integral values
+        # decode to `int`): a float() cast would silently round a huge
+        # integer to its nearest float64 and could mask a genuine mismatch
+        # (e.g. the safe-integer-edge divergence, where the wrong exact int
+        # happens to float-round to the right answer).
+        if isinstance(got, int) and isinstance(expect, int):
+            return got == expect
+        return float(got) == float(expect)
+    return got == expect
+
+
+@unittest.skipUnless(os.path.exists(VECTORS_PATH), "golden vectors not available outside the monorepo checkout")
+class HelperVectorsTest(unittest.TestCase):
+    def test_vectors(self):
+        with open(VECTORS_PATH, encoding="utf-8") as fh:
+            doc = json.load(fh)
+
+        self.assertTrue(doc["cases"], "vectors.json contains no cases")
+        seen_declarations = set()
+
+        for case in doc["cases"]:
+            fn, note, args, expect = case["fn"], case["note"], case["args"], case["expect"]
+            key = f"{fn}/{note}"
+            with self.subTest(key=key):
+                if fn in UNSUPPORTED:
+                    self.skipTest(f"unsupported on this backend: {UNSUPPORTED[fn]}")
+                    continue
+                bind = BINDINGS.get(fn)
+                self.assertIsNotNone(bind, f"no Python binding for helper '{fn}' -- add it to BINDINGS")
+
+                divergence = DIVERGENCES.get(key)
+                if divergence and divergence.get("throws"):
+                    seen_declarations.add(key)
+                    exception_name = divergence.get("exception")
+                    exception_cls = getattr(builtins, exception_name) if exception_name else Exception
+                    with self.assertRaises(
+                        exception_cls,
+                        msg=f"{key} (declared divergence: {divergence['reason']})",
+                    ):
+                        bind(*args)
+                    continue
+
+                try:
+                    got = bind(*args)
+                except Exception as exc:  # noqa: BLE001
+                    self.fail(f"{key} raised unexpectedly: {exc!r}")
+                    continue
+
+                if divergence:
+                    seen_declarations.add(key)
+                    label = f"{key} (declared divergence: {divergence['reason']})"
+                    self.assertFalse(
+                        _match(got, expect),
+                        f"stale divergence declaration for '{key}' -- the backend now matches JS; remove it",
+                    )
+                    want = divergence["expect"]
+                    if isinstance(want, dict) and want.get("$num") == "NaN":
+                        self.assertTrue(
+                            isinstance(got, float) and got != got,
+                            f"{label}: got {got!r}, wanted real NaN",
+                        )
+                    else:
+                        self.assertEqual(got, want, label)
+                    continue
+
+                self.assertTrue(_match(got, expect), f"{key}: got {got!r}, want {expect!r}")
+
+        stale = [k for k in DIVERGENCES if k not in seen_declarations]
+        self.assertEqual(stale, [], f"divergence declarations match no vector case -- renamed note? {stale}")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/tests/test_omit.py

@@ -0,0 +1,62 @@
+"""`BarefootJS.omit` -- the object-rest `.map()` destructure residual-object
+helper (#2087 Phase B). Companion to `test_spread_attrs.py`: `omit` builds
+the TRUE residual dict (`{ id, title, ...rest }` -> `bf.omit(item, ['id',
+'title'])`) that `rest.flag` member reads and `bf.spread_attrs(rest)`
+forwarding both read from.
+"""
+
+from __future__ import annotations
+
+import unittest
+
+from barefootjs import BarefootJS
+
+
+class _PureBackend:
+    def mark_raw(self, s):
+        return s
+
+
+def run(recv, keys):
+    bf = BarefootJS(None, {"backend": _PureBackend()})
+    return bf.omit(recv, keys)
+
+
+class OmitTest(unittest.TestCase):
+    def test_basic_shape(self):
+        self.assertEqual(
+            run({"id": "t1", "title": "one", "flag": "a"}, ["id", "title"]),
+            {"flag": "a"},
+        )
+
+    def test_no_keys_excluded(self):
+        self.assertEqual(run({"a": 1, "b": 2}, []), {"a": 1, "b": 2})
+
+    def test_all_keys_excluded(self):
+        self.assertEqual(run({"a": 1, "b": 2}, ["a", "b"]), {})
+
+    def test_non_identifier_key(self):
+        # The rest-spread fixture's residual carries a non-identifier
+        # sibling key (`data-priority`) through untouched.
+        self.assertEqual(
+            run(
+                {"id": "t1", "title": "one", "data-priority": "high", "tag": "urgent"},
+                ["id", "title"],
+            ),
+            {"data-priority": "high", "tag": "urgent"},
+        )
+
+    def test_non_dict_input(self):
+        self.assertEqual(run(None, ["id"]), {})
+        self.assertEqual(run("not a dict", ["id"]), {})
+        self.assertEqual(run([1, 2, 3], ["id"]), {})
+
+    def test_key_not_present_is_noop(self):
+        self.assertEqual(run({"a": 1}, ["missing"]), {"a": 1})
+
+    def test_empty_keys_arg(self):
+        self.assertEqual(run({"a": 1}, None), {"a": 1})
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/tests/test_props_attr.py

@@ -0,0 +1,54 @@
+"""`BarefootJS.props_attr` -- the `bf-p` hydration-payload attribute.
+
+The encoded JSON is embedded in a SINGLE-quoted attribute, so it must be
+attribute-escaped: a raw `'` inside a string value (e.g. a blog paragraph)
+terminates the attribute early and the client hydrates from truncated JSON
+(empty island text; found via the shared blog-ssr e2e). Same fix across the
+Perl, Python, Ruby, and Rust runtimes -- keep the four tests in sync.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import unittest
+
+from barefootjs import BarefootJS
+
+
+class _PureBackend:
+    def encode_json(self, value):
+        return json.dumps(value, sort_keys=True, separators=(",", ":"))
+
+
+def bf_with(props):
+    bf = BarefootJS(None, {"backend": _PureBackend()})
+    if props is not None:
+        bf._props(props)
+    return bf
+
+
+class PropsAttrTest(unittest.TestCase):
+    def test_empty_props_emit_nothing(self):
+        self.assertEqual(bf_with(None).props_attr(), "")
+        self.assertEqual(bf_with({}).props_attr(), "")
+
+    def test_json_is_attribute_escaped(self):
+        attr = bf_with({"note": "it's <b> & co"}).props_attr()
+        self.assertEqual(attr, " bf-p='{&#34;note&#34;:&#34;it&#39;s &lt;b&gt; &amp; co&#34;}'")
+
+    def test_attribute_round_trips_through_entity_decoding(self):
+        attr = bf_with({"note": "it's <b> & co"}).props_attr()
+        value = re.search(r"bf-p='([^']*)'", attr).group(1)
+        decoded = (
+            value.replace("&#34;", '"')
+            .replace("&#39;", "'")
+            .replace("&lt;", "<")
+            .replace("&gt;", ">")
+            .replace("&amp;", "&")
+        )
+        self.assertEqual(json.loads(decoded), {"note": "it's <b> & co"})
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/tests/test_query.py

@@ -0,0 +1,41 @@
+"""`BarefootJS.query` -- ported from packages/adapter-perl/t/query.t.
+
+The full CROSS-BACKEND behaviour (control flow + form-encoding parity with
+the browser's URLSearchParams) is defined ONCE in the shared golden helper
+vectors and run by `test_helper_vectors.py`. This file keeps a few
+representative cases for always-on coverage plus the Python-runtime-SPECIFIC
+defensive behaviour the golden vectors can't express: a `None` value (JSON
+has no `undefined`; a JSON `null` stringifies to "null" under JS `String()`,
+so it can't be a shared vector -- this runtime coerces `None` to '' and omits
+the empty pair, mirroring the Perl port's documented `undef` handling)."""
+
+from __future__ import annotations
+
+import unittest
+
+from barefootjs import BarefootJS
+
+
+class QueryTest(unittest.TestCase):
+    def setUp(self):
+        self.bf = BarefootJS(None, {"backend": None})
+
+    def test_order_preserved_repeated_key_overwrites_at_first_position(self):
+        self.assertEqual(
+            self.bf.query("/blog", True, "sort", "title", True, "tag", "go", True, "sort", "date"),
+            "/blog?sort=date&tag=go",
+        )
+
+    def test_form_encoding_tilde_star_space(self):
+        self.assertEqual(self.bf.query("/s", True, "t", "a~b *c"), "/s?t=a%7Eb+*c")
+
+    def test_array_value_appends_pair_per_nonempty_member(self):
+        self.assertEqual(self.bf.query("/list", True, "tag", ["a", "", "b"]), "/list?tag=a&tag=b")
+
+    def test_none_value_coerced_to_empty_and_omitted(self):
+        self.assertEqual(self.bf.query("/list", True, "tag", None), "/list")
+        self.assertEqual(self.bf.query("/list", True, "tag", None, True, "keep", "me"), "/list?keep=me")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/tests/test_render.py

@@ -0,0 +1,102 @@
+"""Jinja2 end-to-end render test, modeled on
+packages/adapter-xslate/t/render.t.
+
+Writes a `.jinja` template equivalent to what the `@barefootjs/jinja`
+compile-time adapter emits, then renders it through the runtime + the Jinja
+backend. Exercises scope markers, hydration attrs, text slots via HTML
+comment markers, autoescaping, and `spread_attrs`.
+
+Jinja idiom note: helpers that return already-safe HTML syntax but are NOT
+wrapped by the backend's `mark_raw` (`scope_attr`, `hydration_attrs`,
+`text_start`, `text_end`, `comment`, `scope_comment`) need an explicit
+`| safe` filter at the call site -- the Jinja-syntax equivalent of Kolon's
+`| mark_raw` pipe seen in the Perl port's `render.t`. `spread_attrs` already
+returns a `markupsafe.Markup` value (via `backend.mark_raw`), so it needs no
+filter, matching the Perl template's call site exactly.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from barefootjs import BarefootJS
+from barefootjs.backend_jinja import JinjaBackend
+
+WIDGET_TEMPLATE = (
+    '<div bf-s="{{ bf.scope_attr() }}" {{ bf.hydration_attrs() | safe }}>'
+    "count: {{ bf.text_start('s0') | safe }}{{ count }}{{ bf.text_end() | safe }} "
+    "<span {{ bf.spread_attrs(attrs) }}>{{ label }}</span>"
+    "</div>"
+)
+
+
+class RenderTest(unittest.TestCase):
+    def setUp(self):
+        self._tmpdir = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmpdir.cleanup)
+        template_dir = Path(self._tmpdir.name)
+        (template_dir / "widget.jinja").write_text(WIDGET_TEMPLATE, encoding="utf-8")
+        self.backend = JinjaBackend(paths=[str(template_dir)])
+        self.bf = BarefootJS(None, {"backend": self.backend})
+        self.bf._scope_id("Widget_test")
+
+    def test_scope_and_hydration_markers(self):
+        out = self.backend.render_named(
+            "widget", self.bf, {"count": 7, "label": "<x>", "attrs": {"id": "n", "class": "c"}}
+        )
+        self.assertIn('bf-s="Widget_test" bf-r=""', out)
+
+    def test_reactive_text_slot_with_comment_markers(self):
+        out = self.backend.render_named(
+            "widget", self.bf, {"count": 7, "label": "<x>", "attrs": {"id": "n", "class": "c"}}
+        )
+        self.assertIn("count: <!--bf:s0-->7<!--/-->", out)
+
+    def test_plain_interpolation_is_autoescaped(self):
+        out = self.backend.render_named(
+            "widget", self.bf, {"count": 7, "label": "<x>", "attrs": {"id": "n", "class": "c"}}
+        )
+        self.assertIn("&lt;x&gt;", out)
+
+    def test_spread_attrs_renders_raw_with_sorted_keys(self):
+        out = self.backend.render_named(
+            "widget", self.bf, {"count": 7, "label": "<x>", "attrs": {"id": "n", "class": "c"}}
+        )
+        self.assertIn('<span class="c" id="n">', out)
+
+    def test_backend_unit_operations(self):
+        self.assertEqual(self.backend.materialize("plain"), "plain")
+        self.assertEqual(self.backend.materialize(lambda: "lazy"), "lazy")
+        encoded = self.backend.encode_json({"b": 2, "a": 1})
+        self.assertEqual(encoded, '{"a":1,"b":2}')  # canonical (sorted) key order
+
+    def test_render_named_mangles_reserved_word_props(self):
+        template_dir = Path(self._tmpdir.name)
+        (template_dir / "kw.jinja").write_text("{{ class_ }}-{{ for_ }}", encoding="utf-8")
+        out = self.backend.render_named("kw", self.bf, {"class": "X", "for": "Y"})
+        self.assertEqual(out, "X-Y")
+
+    def test_render_child_end_to_end(self):
+        """A parent template renders a registered child via `bf.render_child`,
+        exercising `render_child` -> renderer -> `render_named` end-to-end,
+        including keyword mangling flowing through both hops."""
+        template_dir = Path(self._tmpdir.name)
+        (template_dir / "parent.jinja").write_text(
+            "parent:{{ bf.render_child('child', class='c1', label='hi') }}", encoding="utf-8"
+        )
+        (template_dir / "child.jinja").write_text("[{{ class_ }}:{{ label }}]", encoding="utf-8")
+
+        def child_renderer(props, caller):
+            child_bf = BarefootJS(None, {"backend": self.backend})
+            return self.backend.render_named("child", child_bf, props)
+
+        self.bf.register_child_renderer("child", child_renderer)
+        out = self.backend.render_named("parent", self.bf, {})
+        self.assertEqual(out, "parent:[c1:hi]")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/tests/test_render_child.py

@@ -0,0 +1,96 @@
+"""`render_child` renderer-invocation contract, ported from
+packages/adapter-perl/t/render_child.t.
+
+Renderer contract (#1897): the renderer is invoked with `(props, invoking_bf)`
+so nested renders can chain scope/slot identity off the caller, not the
+registrant.
+"""
+
+from __future__ import annotations
+
+import unittest
+
+from barefootjs import BarefootJS
+
+
+class _StubBackend:
+    def materialize(self, value):
+        return value() if callable(value) else value
+
+
+def new_bf():
+    return BarefootJS(None, {"backend": _StubBackend()})
+
+
+class RenderChildTest(unittest.TestCase):
+    def test_renderer_receives_invoking_instance(self):
+        bf = new_bf()
+        bf._scope_id("Root_test")
+
+        seen = {}
+
+        def probe(props, caller):
+            seen["props"] = props
+            seen["caller"] = caller
+            return "ok"
+
+        bf.register_child_renderer("probe", probe)
+
+        self.assertEqual(bf.render_child("probe", value=1), "ok")
+        self.assertEqual(seen["props"]["value"], 1)
+        self.assertIs(seen["caller"], bf)
+
+        # A nested invocation from a different instance passes THAT instance.
+        child = new_bf()
+        child._scope_id("Root_test_s0")
+        child._child_renderers(bf._child_renderers())
+        child.render_child("probe")
+        self.assertIs(seen["caller"], child)
+
+    def test_renderer_exceptions_propagate(self):
+        bf = new_bf()
+
+        def boom(props, caller):
+            raise RuntimeError("renderer exploded")
+
+        bf.register_child_renderer("boom", boom)
+
+        with self.assertRaisesRegex(RuntimeError, "renderer exploded"):
+            bf.render_child("boom")
+
+    def test_single_dict_form(self):
+        # Mirrors the Perl port's hashref form for callers that can't splat
+        # a hash into positional/keyword args.
+        bf = new_bf()
+        seen = {}
+
+        def probe(props, caller):
+            seen["props"] = props
+            return "ok"
+
+        bf.register_child_renderer("probe", probe)
+        bf.render_child("probe", {"value": 42})
+        self.assertEqual(seen["props"]["value"], 42)
+
+    def test_missing_renderer_raises(self):
+        bf = new_bf()
+        with self.assertRaises(RuntimeError):
+            bf.render_child("missing")
+
+    def test_reserved_word_prop_is_mangled(self):
+        bf = new_bf()
+        seen = {}
+
+        def probe(props, caller):
+            seen["props"] = props
+            return "ok"
+
+        bf.register_child_renderer("probe", probe)
+        bf.render_child("probe", {"class": "x", "id": "y"})
+        self.assertEqual(seen["props"]["class_"], "x")
+        self.assertEqual(seen["props"]["id"], "y")
+        self.assertNotIn("class", seen["props"])
+
+
+if __name__ == "__main__":
+    unittest.main()