@barefootjs/perl 0.13.0 → 0.15.0

package/lib/BarefootJS/DevReload.pm

@@ -1,5 +1,5 @@
 package BarefootJS::DevReload;
-our $VERSION = "0.10.1";
+our $VERSION = "0.14.0";
 use strict;
 use warnings;
 use feature 'signatures';

package/lib/BarefootJS/SearchParams.pm

@@ -0,0 +1,71 @@
+package BarefootJS::SearchParams;
+our $VERSION = "0.14.0";
+use strict;
+use warnings;
+use utf8;
+use feature 'signatures';
+no warnings 'experimental::signatures';
+
+# Request-scoped SSR view of the query string behind the reactive
+# `searchParams()` environment signal (router v0.5, #1922). The framework
+# integration builds one per request from the request URL and threads it into
+# the template scope as `$searchParams` (the camelCase JS name the adapters
+# keep, like every other signal/prop var); the compiled template reads it via
+# `$searchParams->get('key')` (Mojo) / `$searchParams.get('key')` (Xslate).
+#
+# This runtime is template-engine- and framework-agnostic (core Perl only),
+# matching the rest of BarefootJS.pm, so it can ship in the standalone
+# @barefootjs/perl distribution.
+#
+# Semantics mirror the browser's URLSearchParams.get exactly under the
+# adapters' `?? → //` lowering: get() returns the first value for a key, or
+# `undef` when the key is absent. Perl's `//` (defined-or) coalesces only
+# `undef`, so an absent key falls back to the author's default while a
+# present-but-empty value (`?sort=`) keeps the empty string — the same
+# distinction JS `??` draws between `null` and `''`. (This is a closer match
+# than the Go adapter, whose `or` lowering also coalesces the empty string.)
+
+# new($class, $query = '')
+#
+# Parse a raw query string into the reader. A leading '?' is tolerated, '+'
+# decodes to a space, and %XX escapes are decoded — mirroring URLSearchParams's
+# application/x-www-form-urlencoded parsing. A malformed pair never dies; it
+# simply contributes nothing, matching the browser's lenient parsing.
+sub new ($class, $query = '') {
+    $query //= '';
+    $query =~ s/\A\?//;
+    my %values;
+    for my $pair (split /[&;]/, $query) {
+        next if $pair eq '';
+        my ($key, $val) = split /=/, $pair, 2;
+        $key = _decode($key);
+        $val = defined $val ? _decode($val) : '';
+        push @{ $values{$key} }, $val;
+    }
+    return bless { values => \%values }, $class;
+}
+
+# get($self, $key)
+#
+# First value for $key, or `undef` when the key is absent (see the package
+# docstring for why `undef` — not '' — is the right "missing" sentinel under
+# the `//` lowering). A present-but-empty value returns ''.
+sub get ($self, $key) {
+    my $vals = $self->{values}{$key};
+    return undef unless $vals && @$vals;
+    return $vals->[0];
+}
+
+sub _decode ($s) {
+    $s //= '';
+    $s =~ tr/+/ /;
+    # %XX → raw octet, then interpret the octet stream as UTF-8 (what
+    # URLSearchParams does). `utf8::decode` is a core builtin — no CPAN URI /
+    # URI::Escape dependency, keeping this runtime core-Perl-only. A byte run
+    # that isn't valid UTF-8 is left as-is rather than dying (lenient parsing).
+    $s =~ s/%([0-9A-Fa-f]{2})/chr hex $1/ge;
+    utf8::decode($s);
+    return $s;
+}
+
+1;

package/lib/BarefootJS.pm

@@ -1,5 +1,5 @@
 package BarefootJS;
-our $VERSION = "0.10.1";
+our $VERSION = "0.14.0";
 use strict;
 use warnings;
 use utf8;
@@ -103,6 +103,22 @@ sub new ($class, $c, $config = {}) {
     return $self;
 }
 
+# search_params($query = '')
+#
+# Build a request-scoped reader for the reactive searchParams() environment
+# signal (router v0.5, #1922) from a raw query string. Callable as a class or
+# instance method — the invocant is unused.
+#
+# The `require` lives here so consumers (the Mojo plugin, the Xslate host, the
+# test harness, generated render scripts) reach BarefootJS::SearchParams through
+# the BarefootJS object they already hold, never `use`-ing it directly — the
+# same lazy-load seam the Mojo backend uses above. The compiled template reads
+# the returned object via `$searchParams->get('key')`.
+sub search_params ($invocant, $query = '') {
+    require BarefootJS::SearchParams;
+    return BarefootJS::SearchParams->new($query);
+}
+
 # ---------------------------------------------------------------------------
 # Scope & Props
 # ---------------------------------------------------------------------------
@@ -265,6 +281,11 @@ sub register_script ($self, $path) {
 # ---------------------------------------------------------------------------
 # (`_child_renderers` accessor is generated by the minimal accessor base above.)
 
+# Register a renderer for `render_child($name, ...)`. The renderer is
+# invoked as `$renderer->($props_hashref, $invoking_bf)` — unpack `@_`
+# (`my ($props, $caller) = @_;`) instead of declaring a one-argument
+# subroutine signature, which would enforce arity and die on the second
+# argument.
 sub register_child_renderer ($self, $name, $renderer) {
     $self->_child_renderers->{$name} = $renderer;
 }
@@ -287,7 +308,15 @@ sub render_child ($self, $name, @args) {
     # touch children when present" behaviour.
     $props{children} = $self->backend->materialize($props{children})
         if exists $props{children};
-    return $renderer->(\%props);
+    # Renderer contract (#1897): the renderer is invoked with TWO
+    # arguments — the props hashref and the INVOKING instance. A renderer
+    # registered on the root may be called from a nested child render
+    # (AccordionTrigger -> ChevronDownIcon), and the grandchild's scope /
+    # slot identity must chain off the CALLER's scope id, not the
+    # registrant's. Renderers unpack `@_` (`my ($props, $caller) = @_;`)
+    # rather than enforcing arity with a one-arg subroutine signature —
+    # see `register_child_renderer`.
+    return $renderer->(\%props, $self);
 }
 
 # ---------------------------------------------------------------------------
@@ -345,7 +374,13 @@ sub register_components_from_manifest ($self, $manifest, %opts) {
         my $signal_init = $signal_inits->{$slot_key};
         my $manifest_defaults = $manifest->{$entry_name}{ssrDefaults};
         $self->register_child_renderer($slot_key, sub {
-            my ($props) = @_;
+            # `$caller` is the instance whose template invoked
+            # `render_child` (#1897) — for a nested render that is a child
+            # instance, and the grandchild's scope/slot identity must chain
+            # off ITS scope id (`root_s0_s0`), not the registrant's.
+            my ($props, $caller) = @_;
+            my $host = $caller // $parent;
+            my $host_scope = $host->_scope_id // $parent_scope;
             # Child shares the parent's backend so nested renders go
             # through the same engine + controller (and inherit any
             # injected json_encoder). The controller is fetched via the weak
@@ -358,16 +393,19 @@ sub register_components_from_manifest ($self, $manifest, %opts) {
             my $data_key = delete $props->{key};
             $child_bf->_data_key($data_key) if defined $data_key;
             $child_bf->_scope_id(
-                $slot_id ? $parent_scope . '_' . $slot_id
+                $slot_id ? $host_scope . '_' . $slot_id
                          : $template_name . '_' . substr(rand() =~ s/^0\.//r, 0, 6)
             );
             $child_bf->_is_child(1);
             # (#1249) Slot identity: host scope + slot id. Emitted as
             # bf-h / bf-m attributes by hydration_attrs.
             if ($slot_id) {
-                $child_bf->_bf_parent($parent_scope);
+                $child_bf->_bf_parent($host_scope);
                 $child_bf->_bf_mount($slot_id);
             }
+            # Share the root registry so the child's own template can
+            # render further imported components (#1897).
+            $child_bf->_child_renderers($parent->_child_renderers);
             $child_bf->_scripts($parent->_scripts);
             $child_bf->_script_seen($parent->_script_seen);
 
@@ -508,6 +546,10 @@ sub number ($self, $value) {
 # portable sentinel check in floor/ceil/round.
 sub _is_nan { my $n = shift; return $n != $n }
 
+# True for +/-Infinity. `9**9**9` is Perl's portable infinity literal; a
+# finite number is always strictly less than +Inf in magnitude.
+sub _is_inf { my $n = shift; return $n == 9**9**9 || $n == -9**9**9 }
+
 sub floor ($self, $value) {
     my $n = $self->number($value);
     return $n if _is_nan($n);
@@ -826,6 +868,27 @@ sub trim ($self, $recv) {
     return $s;
 }
 
+# `Number.prototype.toFixed(digits)` (#1897) — fixed-decimal string with
+# zero-padding. JS rounds the scaled integer half toward +Infinity (the
+# spec's "pick the larger n" tie-break), so `(2.5).toFixed(0)` is "3";
+# bare `sprintf("%.*f")` would round half-to-even ("2"), diverging. Scale
+# by 10**digits, round with `floor(x + 0.5)` (the same tie-break the
+# `round` helper uses), then format the exact multiple. A negative
+# `digits` clamps to 0, mirroring how the adapters default an omitted
+# argument.
+sub to_fixed ($self, $value, $digits = 0) {
+    my $n = $self->number($value);
+    # JS toFixed returns the STRINGS "NaN" / "Infinity" / "-Infinity" for
+    # non-finite inputs; the numeric values would stringify per-platform
+    # ("nan"/"inf"/...) and diverge.
+    return 'NaN' if _is_nan($n);
+    return $n < 0 ? '-Infinity' : 'Infinity' if _is_inf($n);
+    $digits = 0 if !defined $digits || $digits < 0;
+    my $factor  = 10 ** $digits;
+    my $rounded = POSIX::floor($n * $factor + 0.5);
+    return sprintf('%.*f', $digits, $rounded / $factor);
+}
+
 # `String.prototype.split(sep)` (#1448 Tier B) — string → ARRAY ref.
 #
 # Two JS-parity wrinkles drive the helper (a bare `split` emit would

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/perl",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "BarefootJS engine-agnostic Perl runtime (BarefootJS.pm) — pluggable rendering backend; the shared basis for Mojolicious and other Perl framework integrations",
   "type": "module",
   "files": [

package/t/helper_vectors.t

@@ -0,0 +1,366 @@
+use strict;
+use warnings;
+use Test::More;
+use FindBin;
+use File::Spec;
+use JSON::PP ();
+use Scalar::Util qw(looks_like_number);
+
+use lib "$FindBin::Bin/../lib";
+use BarefootJS;
+
+# Pure-Perl backend (core JSON::PP only) so this test runs with zero
+# Mojo present — same pattern as t/template_primitives.t.
+{
+    package PureBackend;
+    use JSON::PP ();
+    my $J = JSON::PP->new->canonical->allow_nonref;
+    sub new          { bless {}, shift }
+    sub encode_json  { $J->encode($_[1]) }
+    sub mark_raw     { $_[1] }
+    sub materialize  { ref($_[1]) eq 'CODE' ? $_[1]->() : $_[1] }
+    sub render_named { '' }
+}
+
+my $bf = bless { c => undef, config => {}, backend => PureBackend->new }, 'BarefootJS';
+
+# Golden helper vectors generated from the JS reference implementations
+# (spec/template-helpers.md in the monorepo). The file is not shipped in
+# the CPAN dist — packages/adapter-tests only exists in a monorepo
+# checkout — so skip everywhere else.
+my $vectors_path = File::Spec->catfile(
+    $FindBin::Bin, '..', '..', 'adapter-tests', 'helper-vectors', 'vectors.json'
+);
+plan skip_all => 'golden vectors not available outside the monorepo checkout'
+    unless -e $vectors_path;
+
+my $doc = do {
+    open my $fh, '<:raw', $vectors_path or die "open $vectors_path: $!";
+    local $/;
+    JSON::PP->new->decode(<$fh>);
+};
+
+# One binding per canonical helper id in the spec catalogue, bound to
+# the exact code shape compiled templates execute on the Perl backends.
+# Where the adapters lower an operation to a native Perl operator
+# (mojo-adapter.ts maps JSX `+` straight to Perl `+`), the binding IS
+# that operator rather than a BarefootJS.pm method. Per the spec, a
+# vector with no binding here fails the test — the Perl backend must
+# not silently fall behind the catalogue.
+my %bindings = (
+    add => sub { $_[0] + $_[1] },
+    sub => sub { $_[0] - $_[1] },
+    mul => sub { $_[0] * $_[1] },
+    div => sub { $_[0] / $_[1] },
+    mod => sub { $_[0] % $_[1] },
+    neg => sub { -$_[0] },
+
+    string => sub { $bf->string($_[0]) },
+    json   => sub { $bf->json($_[0]) },
+    number => sub { $bf->number($_[0]) },
+    floor  => sub { $bf->floor($_[0]) },
+    ceil   => sub { $bf->ceil($_[0]) },
+    round  => sub { $bf->round($_[0]) },
+    to_fixed => sub { $bf->to_fixed(@_) },
+
+    # The Mojo renderer emits native lc()/uc(); Xslate emits $bf.lc /
+    # $bf.uc. The helper methods wrap CORE::lc/uc, so binding them
+    # covers both shapes at value level.
+    lower       => sub { $bf->lc($_[0]) },
+    upper       => sub { $bf->uc($_[0]) },
+    trim        => sub { $bf->trim($_[0]) },
+    starts_with => sub { $bf->starts_with(@_) },
+    ends_with   => sub { $bf->ends_with(@_) },
+    replace     => sub { $bf->replace(@_) },
+    repeat      => sub { $bf->repeat(@_) },
+    pad_start   => sub { $bf->pad_start(@_) },
+    pad_end     => sub { $bf->pad_end(@_) },
+    split       => sub { $bf->split(@_) },
+
+    len           => sub { $bf->length($_[0]) },
+    at            => sub { $bf->at(@_) },
+    includes      => sub { $bf->includes(@_) },
+    index_of      => sub { $bf->index_of(@_) },
+    last_index_of => sub { $bf->last_index_of(@_) },
+    concat        => sub { $bf->concat(@_) },
+    # The Mojo emit always passes three value args (`undef` for an
+    # absent end) — mirror that exact shape.
+    slice   => sub { $bf->slice($_[0], $_[1], $_[2]) },
+    reverse => sub { $bf->reverse($_[0]) },
+    flat    => sub { $bf->flat(@_) },
+    join    => sub { $bf->join(@_) },
+    # Array literals are native arrayrefs on the Perl backends.
+    arr => sub { [@_] },
+    # Mirrors the Mojo inline `[grep { $_ } @{...}]` for filter(Boolean).
+    filter_truthy => sub { [grep { $_ } @{ $_[0] }] },
+
+    # searchParams().get(key) (#1922) via the lazy factory consumers use.
+    # No divergence entry: get() returns undef for an absent key (~ JS null)
+    # and '' for present-but-empty, so the Perl backend matches JS exactly.
+    search_params_get => sub { BarefootJS->search_params($_[0])->get($_[1]) },
+
+    # Higher-order entries arrive in the canonical projection form
+    # (spec: items + field [+ value]); the closures below rebuild the
+    # predicate the adapters compile (`i => i.field === value`,
+    # `i => i.field`), choosing eq vs == by the probe's string-typing
+    # the same way the Mojo emitter does.
+    every  => sub { $bf->every($_[0],  _truthy_pred($_[1])) },
+    some   => sub { $bf->some($_[0],   _truthy_pred($_[1])) },
+    filter => sub { $bf->filter($_[0], _field_eq_pred($_[1], $_[2])) },
+    find   => sub { $bf->find($_[0],   _field_eq_pred($_[1], $_[2])) },
+    find_index      => sub { $bf->find_index($_[0],      _field_eq_pred($_[1], $_[2])) },
+    find_last       => sub { $bf->find_last($_[0],       _field_eq_pred($_[1], $_[2])) },
+    find_last_index => sub { $bf->find_last_index($_[0], _field_eq_pred($_[1], $_[2])) },
+
+    sort => sub {
+        my ($recv, @spec) = @_;
+        my @keys;
+        while (@spec >= 4) {
+            my ($kind, $name, $ct, $dir) = splice(@spec, 0, 4);
+            push @keys, {
+                key_kind     => $kind,
+                key          => $name,
+                compare_type => $ct,
+                direction    => $dir,
+            };
+        }
+        return $bf->sort($recv, { keys => \@keys });
+    },
+    reduce => sub {
+        my ($recv, $op, $key_kind, $key, $type, $init, $direction) = @_;
+        return $bf->reduce($recv, {
+            op        => $op,
+            key_kind  => $key_kind,
+            key       => $key,
+            type      => $type,
+            init      => $init,
+            direction => $direction,
+        });
+    },
+    flat_map       => sub { $bf->flat_map(@_) },
+    flat_map_tuple => sub {
+        my ($recv, @flat) = @_;
+        my @specs;
+        while (@flat >= 2) {
+            my ($kind, $name) = splice(@flat, 0, 2);
+            push @specs, [$kind, $name];
+        }
+        return $bf->flat_map_tuple($recv, @specs);
+    },
+);
+
+sub _truthy_pred {
+    my ($field) = @_;
+    return sub { ref $_[0] eq 'HASH' ? $_[0]{$field} : undef };
+}
+
+sub _field_eq_pred {
+    my ($field, $value) = @_;
+    my $get = sub { ref $_[0] eq 'HASH' ? $_[0]{$field} : undef };
+    return looks_like_number($value)
+        ? sub { my $v = $get->($_[0]); defined $v && $v == $value }
+        : sub { my $v = $get->($_[0]); defined $v && $v eq $value };
+}
+
+# Per-backend status declarations (spec/template-helpers.md "Adapter
+# status model"). This file is the single source of truth for the
+# Perl backends' divergences — the spec stays backend-neutral.
+#
+# %DIVERGENCES pins a deliberate divergence from the JS-normative
+# expect, keyed by `fn/note`. Forms:
+#   { expect => <value>, reason => ... }  assert the pinned value
+#   { nan    => 1,       reason => ... }  assert a real NaN result
+#   { dies   => 1,       reason => ... }  assert the call dies
+# A pinned case that starts matching JS fails as stale; a key that
+# matches no vector case fails as dead.
+my %DIVERGENCES = (
+    'add/beyond the safe-integer edge rounds as a double' => {
+        expect => 9007199254740993,
+        reason => 'Perl IV arithmetic is 64-bit exact, not double-rounded',
+    },
+    'div/zero divisor yields Infinity' => {
+        dies   => 1,
+        reason => 'Perl native / dies on a zero divisor',
+    },
+    'mod/remainder keeps the dividend sign' => {
+        expect => 2,
+        reason => 'Perl native % takes the divisor sign',
+    },
+    'mod/float remainder' => {
+        expect => 1,
+        reason => 'Perl native % truncates operands to integers',
+    },
+    'number/empty string coerces to 0' => {
+        nan    => 1,
+        reason => 'deliberate: empty input must not silently zero downstream arithmetic',
+    },
+    'number/null coerces to 0' => {
+        nan    => 1,
+        reason => 'deliberate: unset props must not silently zero downstream arithmetic',
+    },
+    'string/null renders as the string "null"' => {
+        expect => '',
+        reason => 'deliberate: an unset prop must not surface a literal "null" in HTML',
+    },
+    'string/true renders as the string "true"' => {
+        expect => '1',
+        reason => 'Perl has no boolean type; template data carries 1/0',
+    },
+    'string/17-significant-digit double round-trips' => {
+        expect => '0.3',
+        reason => 'Perl stringifies doubles via %.15g',
+    },
+    'includes/cross-type probe is strict-equality false' => {
+        expect => 1,
+        reason => 'bf->includes scans with eq (string equality), so 2 eq "2" matches',
+    },
+    'filter_truthy/the string "0" is truthy' => {
+        expect => ['x'],
+        reason => 'Perl truthiness treats the string "0" as false',
+    },
+    'sort/localeCompare orders case-insensitively (ICU collation)' => {
+        expect => ['B', 'a'],
+        reason => 'cmp is byte order, not ICU collation',
+    },
+    'sort/relational compare on numeric strings is lexical' => {
+        expect => ['9', '10'],
+        reason => 'the "auto" compare goes numeric when both keys look_like_number',
+    },
+    'reduce/numeric-string items concatenate under JS +' => {
+        expect => 11,
+        reason => 'numeric folds parse numeric strings instead of concatenating',
+    },
+);
+
+# Helper ids not implemented on this backend yet — skipped visibly.
+# Empty for the Perl backends; the mechanism exists so a bootstrapping
+# backend can land its harness first and burn the list down.
+my %UNSUPPORTED = ();
+
+my %seen_declarations;
+for my $case (@{ $doc->{cases} }) {
+    my ($fn, $note) = @{$case}{qw(fn note)};
+    my $key = "$fn/$note";
+    if (my $why = $UNSUPPORTED{$fn}) {
+        SKIP: { skip "unsupported on this backend: $why", 1 }
+        next;
+    }
+    my $bind = $bindings{$fn};
+    if (!$bind) {
+        fail("no Perl binding for helper '$fn' — add it to %bindings in $0");
+        next;
+    }
+    my @args = map { normalize_arg($_) } @{ $case->{args} };
+    my $got  = eval { $bind->(@args) };
+    my $err  = $@;
+
+    if (my $d = $DIVERGENCES{$key}) {
+        $seen_declarations{$key} = 1;
+        my $label = "$key (declared divergence: $d->{reason})";
+        if ($d->{dies}) {
+            ok($err, $label) or diag("expected the call to die, got: " . explain_value($got));
+            next;
+        }
+        if ($err) {
+            fail($label);
+            diag("died unexpectedly: $err");
+            next;
+        }
+        if (_match($got, $case->{expect})) {
+            fail("stale divergence declaration for '$key' — the backend now matches JS; remove it");
+            next;
+        }
+        my $want_ok = $d->{nan} ? (looks_like_number($got // '') && $got != $got)
+                                : _match_plain($got, $d->{expect});
+        ok($want_ok, $label)
+            or diag('got ' . explain_value($got) . ', pinned ' . explain_value($d->{nan} ? 'NaN' : $d->{expect}));
+        next;
+    }
+
+    if ($err) {
+        fail("$key died: $err");
+        next;
+    }
+    ok(_match($got, $case->{expect}), "$key")
+        or diag('got ' . explain_value($got) . ', want ' . explain_value($case->{expect}));
+}
+
+for my $key (keys %DIVERGENCES) {
+    fail("divergence declaration '$key' matches no vector case — renamed note?")
+        unless $seen_declarations{$key};
+}
+
+done_testing;
+
+# Spec value-compat contract: numbers compare numerically (JSON::PP
+# decodes vector numbers to IV/NV, `==` compares the values), booleans
+# by truthiness, everything else structurally. Arrays currently go
+# through is_deeply (string compare per element) — refine to a
+# recursive numeric walk when the first float-array vector lands.
+# Production Perl template data has no boolean type — the adapters pass
+# 1/0 where JS has true/false — so JSON::PP boolean objects in vector
+# ARGS are lowered to 1/0 before reaching a binding. Expects keep their
+# boolean identity (vector_ok compares those by truthiness).
+sub normalize_arg {
+    my ($v) = @_;
+    return [ map { normalize_arg($_) } @$v ] if ref $v eq 'ARRAY';
+    return { map { $_ => normalize_arg($v->{$_}) } keys %$v } if ref $v eq 'HASH';
+    return JSON::PP::is_bool($v) ? ($v ? 1 : 0) : $v;
+}
+
+# _match: boolean form of the spec's value-compat comparison against a
+# JSON-decoded expect — sentinel hashes, booleans by truthiness,
+# numbers numerically, arrays/hashes recursively.
+sub _match {
+    my ($got, $expect) = @_;
+    return !defined $got if !defined $expect;
+    if (ref $expect eq 'HASH' && exists $expect->{'$num'}) {
+        my $kind = $expect->{'$num'};
+        return 0 unless defined $got && looks_like_number($got);
+        return $got != $got ? 1 : 0 if $kind eq 'NaN';
+        my $inf = 9**9**9;
+        return $got == ($kind eq 'Infinity' ? $inf : -$inf) ? 1 : 0;
+    }
+    if (JSON::PP::is_bool($expect)) {
+        return (!!$got eq !!$expect) ? 1 : 0;
+    }
+    if (ref $expect eq 'ARRAY') {
+        return 0 unless ref $got eq 'ARRAY' && @$got == @$expect;
+        _match($got->[$_], $expect->[$_]) or return 0 for 0 .. $#$expect;
+        return 1;
+    }
+    if (ref $expect eq 'HASH') {
+        return 0 unless ref $got eq 'HASH' && keys %$got == keys %$expect;
+        for my $k (keys %$expect) {
+            return 0 unless exists $got->{$k};
+            _match($got->{$k}, $expect->{$k}) or return 0;
+        }
+        return 1;
+    }
+    return 0 if !defined $got || ref $got;
+    return ($got == $expect ? 1 : 0) if looks_like_number($expect) && looks_like_number($got);
+    return ($got eq $expect) ? 1 : 0;
+}
+
+# _match_plain: like _match but against a plain Perl value from a
+# divergence declaration (no JSON boolean / sentinel forms).
+sub _match_plain {
+    my ($got, $expect) = @_;
+    return !defined $got if !defined $expect;
+    if (ref $expect eq 'ARRAY') {
+        return 0 unless ref $got eq 'ARRAY' && @$got == @$expect;
+        _match_plain($got->[$_], $expect->[$_]) or return 0 for 0 .. $#$expect;
+        return 1;
+    }
+    return 0 if !defined $got || ref $got;
+    return ($got == $expect ? 1 : 0) if looks_like_number($expect) && looks_like_number($got);
+    return ($got eq $expect) ? 1 : 0;
+}
+
+sub explain_value {
+    my ($v) = @_;
+    return 'undef' unless defined $v;
+    return JSON::PP->new->canonical->allow_nonref->allow_blessed->convert_blessed->encode($v)
+        if ref $v;
+    return "'$v'";
+}

package/t/render_child.t

@@ -0,0 +1,59 @@
+use strict;
+use warnings;
+use utf8;
+
+use Test2::V0;
+
+use lib 'lib';
+use BarefootJS;
+
+# A do-nothing backend: render_child only touches the backend to
+# materialize a `children` prop, which these cases never pass — but
+# `new` eagerly builds the default Mojo backend, which isn't a dependency
+# of this dist's test environment.
+{
+    package StubBackend;
+    sub new { bless {}, shift }
+    sub materialize { $_[1] }
+}
+sub new_bf { BarefootJS->new(undef, { backend => StubBackend->new }) }
+
+# render_child renderer-invocation contract (#1897): the renderer is
+# invoked with ($props_hashref, $invoking_bf) so nested renders can chain
+# scope/slot identity off the caller. Renderers unpack @_ rather than
+# enforcing arity with a one-arg subroutine signature (see
+# register_child_renderer's doc).
+
+subtest 'renderer receives the invoking instance' => sub {
+    my $bf = new_bf();
+    $bf->_scope_id('Root_test');
+
+    my ($seen_props, $seen_caller);
+    $bf->register_child_renderer('probe', sub {
+        my ($props, $caller) = @_;
+        ($seen_props, $seen_caller) = ($props, $caller);
+        return 'ok';
+    });
+
+    is $bf->render_child('probe', value => 1), 'ok', 'renderer output returned';
+    is $seen_props->{value}, 1, 'props forwarded';
+    ref_is $seen_caller, $bf, 'second argument is the invoking instance';
+
+    # A nested invocation from a different instance passes THAT instance.
+    my $child = new_bf();
+    $child->_scope_id('Root_test_s0');
+    $child->_child_renderers($bf->_child_renderers);
+    $child->render_child('probe');
+    ref_is $seen_caller, $child, 'nested call passes the nested instance';
+};
+
+subtest 'renderer exceptions propagate' => sub {
+    my $bf = new_bf();
+    $bf->register_child_renderer('boom', sub {
+        die "renderer exploded\n";
+    });
+    like dies { $bf->render_child('boom') }, qr/renderer exploded/,
+        'renderer errors propagate to the caller';
+};
+
+done_testing;

package/t/search_params.t

@@ -0,0 +1,58 @@
+use Test2::V0;
+use utf8;
+
+# BarefootJS::SearchParams — Perl-specific concerns of the searchParams()
+# environment-signal reader (router v0.5, #1922).
+#
+# The cross-language VALUE semantics of `get` (absent → null/undef, present →
+# first value, repeated keys, present-but-empty, `+`/`%XX`/encoded-separator
+# decoding, first-`=` split) are owned by the language-independent golden
+# vectors — `search_params_get` in packages/adapter-tests/helper-vectors,
+# asserted here via t/helper_vectors.t and in the Go runtime's vectors_test.go,
+# so Go/Perl/JS parity is mechanical. This file covers only what those value
+# vectors can't: the lazy-load factory seam, lenient parsing (never dies), the
+# `//` composition, and UTF-8 decoding.
+
+use FindBin qw($Bin);
+use lib "$Bin/../lib";
+
+use BarefootJS;
+
+# The lazy factory on the BarefootJS object is how every consumer (Mojo plugin,
+# Xslate host, render harness) reaches the reader — no one `use`s the class
+# directly. Assert it loads + builds a working reader.
+subtest 'BarefootJS->search_params lazy factory' => sub {
+    my $sp = BarefootJS->search_params('sort=price');
+    is ref($sp), 'BarefootJS::SearchParams', 'factory returns a reader instance';
+    is $sp->get('sort'), 'price', 'factory-built reader resolves the query';
+    is ref(BarefootJS->search_params), 'BarefootJS::SearchParams', 'default empty query';
+};
+
+# The adapters lower `searchParams().get(k) ?? d` to Perl's defined-or
+# (`$searchParams->get(k) // d`), which coalesces only undef — so an absent key
+# falls back to the default while a present-but-empty value keeps ''. This is
+# the Perl-specific divergence from the Go `or` lowering (which coalesces '').
+subtest '// composition (the ?? lowering) coalesces only undef' => sub {
+    my $absent = BarefootJS->search_params('other=x');
+    is(($absent->get('sort') // 'none'), 'none', 'absent key → author default');
+
+    my $empty = BarefootJS->search_params('sort=');
+    is(($empty->get('sort') // 'none'), '', 'present-but-empty value is kept, NOT defaulted');
+};
+
+# Percent-encoded UTF-8 decodes to characters via the core `utf8::decode`
+# builtin (no URI / URI::Escape dependency) — kept here rather than in the
+# ASCII-only shared vectors to avoid cross-harness byte/char encoding skew.
+subtest 'UTF-8 percent-decoding (core utf8::decode, no URI dep)' => sub {
+    my $sp = BarefootJS->search_params('q=%E2%9C%93');
+    is $sp->get('q'), "\x{2713}", 'percent-encoded UTF-8 → decoded character (✓)';
+};
+
+# Malformed input must degrade, never die (SSR survives junk query strings).
+subtest 'lenient parsing never dies' => sub {
+    ok lives { BarefootJS->search_params(undef) }, 'undef query';
+    ok lives { BarefootJS->search_params('&&&')->get('x') }, 'only separators';
+    ok lives { BarefootJS->search_params('=novalue')->get('x') }, 'empty key pair';
+};
+
+done_testing;