@barefootjs/perl 0.16.0 → 0.17.0

package/lib/BarefootJS/DevReload.pm

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

package/lib/BarefootJS/Evaluator.pm

@@ -0,0 +1,578 @@
+package BarefootJS::Evaluator;
+our $VERSION = "0.14.0";
+use strict;
+use warnings;
+use utf8;
+use feature 'signatures';
+no warnings 'experimental::signatures';
+
+use B ();
+use POSIX ();
+use JSON::PP ();
+use Scalar::Util qw(looks_like_number);
+
+# Lightweight evaluator for the pure `ParsedExpr` subset, scoped to
+# higher-order callback bodies (reduce / sort / map / filter / find
+# `(…) => expr`) — issue #2018. Templates cannot carry a lambda in
+# expression position, which is why the adapters historically special-cased
+# these callbacks into fixed shapes (bf_sort's comparator catalogue,
+# bf_reduce's +/* fold). Instead, the callback BODY rides as a pure
+# `ParsedExpr` subtree (the structured IR the compiler already produces) and
+# is evaluated here against an environment (`{acc, item, …captured free
+# vars}`).
+#
+# ONE shared implementation for both Perl backends (Mojo + Xslate), living
+# alongside SearchParams.pm in the engine-agnostic core (no CPAN deps beyond
+# core B / POSIX / Scalar::Util). The accepted subset and its semantics are
+# documented in spec/compiler.md ("ParsedExpr Evaluator Semantics") and pinned
+# isomorphically by the cross-language golden vectors
+# (packages/adapter-tests/helper-vectors/eval-vectors.json), shared with the Go
+# evaluator (bf.go) — same input → same output.
+#
+# The coercion below is JS-faithful (ToNumber / ToString / ToBoolean, strict
+# equality) and deliberately distinct from the divergent bf->string / number
+# helpers in BarefootJS.pm, so the contract is unambiguous and the two
+# template adapters stay byte-equal with each other and with Go.
+
+# evaluate($node, $env)
+#
+# Evaluate a decoded ParsedExpr node (a hashref keyed by `kind`) against the
+# environment hashref ($env), returning a Perl value (number, string,
+# JSON::PP::Boolean, undef for null, arrayref, hashref). The matching JSON
+# entry point is eval_json() below.
+sub evaluate ($node, $env) {
+    return undef unless ref $node eq 'HASH';
+    my $kind = $node->{kind} // '';
+
+    if ($kind eq 'literal') {
+        return $node->{value};
+    }
+    if ($kind eq 'identifier') {
+        return $env->{ $node->{name} };
+    }
+    if ($kind eq 'binary') {
+        return _binary($node->{op},
+            evaluate($node->{left}, $env), evaluate($node->{right}, $env));
+    }
+    if ($kind eq 'unary') {
+        return _unary($node->{op}, evaluate($node->{argument}, $env));
+    }
+    if ($kind eq 'logical') {
+        my $op   = $node->{op};
+        my $left = evaluate($node->{left}, $env);
+        if ($op eq '&&') {
+            return _truthy($left) ? evaluate($node->{right}, $env) : $left;
+        }
+        if ($op eq '||') {
+            return _truthy($left) ? $left : evaluate($node->{right}, $env);
+        }
+        # `??`
+        return defined $left ? $left : evaluate($node->{right}, $env);
+    }
+    if ($kind eq 'conditional') {
+        return _truthy(evaluate($node->{test}, $env))
+            ? evaluate($node->{consequent}, $env)
+            : evaluate($node->{alternate}, $env);
+    }
+    if ($kind eq 'member') {
+        return _read_property(evaluate($node->{object}, $env), $node->{property});
+    }
+    if ($kind eq 'index-access') {
+        return _read_index(evaluate($node->{object}, $env), evaluate($node->{index}, $env));
+    }
+    if ($kind eq 'call') {
+        my $name = _builtin_name($node->{callee});
+        return undef unless defined $name && $name ne '';
+        my @args = map { evaluate($_, $env) } @{ $node->{args} // [] };
+        return _call_builtin($name, \@args);
+    }
+    if ($kind eq 'template-literal') {
+        my $out = '';
+        for my $p (@{ $node->{parts} // [] }) {
+            if (($p->{type} // '') eq 'string') {
+                $out .= $p->{value} // '';
+            }
+            else {
+                $out .= _to_string(evaluate($p->{expr}, $env));
+            }
+        }
+        return $out;
+    }
+    if ($kind eq 'array-literal') {
+        return [ map { evaluate($_, $env) } @{ $node->{elements} // [] } ];
+    }
+    if ($kind eq 'object-literal') {
+        my %out;
+        for my $prop (@{ $node->{properties} // [] }) {
+            $out{ $prop->{key} } = evaluate($prop->{value}, $env);
+        }
+        return \%out;
+    }
+
+    # arrow-fn / higher-order / array-method / unsupported: a callback body
+    # containing these is refused upstream (BF101); never reached here.
+    return undef;
+}
+
+# eval_json($json, $env): decode a ParsedExpr JSON string and evaluate it.
+# Mirrors the Go EvalExpr entry point. Requires JSON::PP only when used.
+sub eval_json ($json, $env) {
+    require JSON::PP;
+    my $node = JSON::PP->new->decode($json);
+    return evaluate($node, $env);
+}
+
+# ---------------------------------------------------------------------------
+# JS value classification. JSON-decoded strings carry the string flag (POK)
+# but no numeric flag; JSON-decoded numbers carry IOK/NOK. This lets the
+# evaluator tell the JS *string* "10" from the JS *number* 10 — essential for
+# the `+` overload and relational comparison — which looks_like_number alone
+# cannot (it is true for both).
+# ---------------------------------------------------------------------------
+
+sub _is_string ($v) {
+    return 0 if !defined $v || ref $v;
+    my $f = B::svref_2object(\$v)->FLAGS;
+    return (($f & B::SVf_POK) && !($f & (B::SVf_IOK | B::SVf_NOK))) ? 1 : 0;
+}
+
+sub _is_number ($v) {
+    return (defined $v && !ref $v && !_is_string($v)) ? 1 : 0;
+}
+
+sub _nan {
+    my $inf = 9**9**9;
+    return $inf - $inf;
+}
+
+# ---------------------------------------------------------------------------
+# JS coercion primitives (ToNumber / ToString / ToBoolean).
+# ---------------------------------------------------------------------------
+
+sub _to_number ($v) {
+    return 0 if !defined $v;
+    if (ref $v eq 'JSON::PP::Boolean') { return $v ? 1 : 0 }
+    return _nan() if ref $v;
+    if (_is_string($v)) {
+        my $t = $v;
+        $t =~ s/\A\s+//;
+        $t =~ s/\s+\z//;
+        return 0 if $t eq '';
+        return looks_like_number($t) ? ($t + 0) : _nan();
+    }
+    return $v + 0;
+}
+
+sub _to_string ($v) {
+    return 'null' if !defined $v;
+    if (ref $v eq 'JSON::PP::Boolean') { return $v ? 'true' : 'false' }
+    # JS spells the non-finite doubles "Infinity" / "-Infinity" / "NaN";
+    # Perl stringifies them "Inf" / "-Inf" / "NaN", so the non-finite cases
+    # are pinned here to stay JS-faithful (and match the Go evaluator's
+    # evalToString). Finite numbers and strings fall through to plain
+    # interpolation.
+    if (_is_number($v)) {
+        my $n = $v + 0;
+        return 'NaN'       if $n != $n;
+        return 'Infinity'  if $n == 9**9**9;
+        return '-Infinity' if $n == -(9**9**9);
+    }
+    return "$v";
+}
+
+sub _truthy ($v) {
+    return 0 if !defined $v;
+    if (ref $v eq 'JSON::PP::Boolean') { return $v ? 1 : 0 }
+    return 1 if ref $v;    # arrays / objects are always truthy in JS
+    if (_is_string($v)) { return $v ne '' ? 1 : 0 }    # incl. the truthy "0"
+    my $n = $v + 0;
+    return ($n != 0 && $n == $n) ? 1 : 0;              # nonzero and not NaN
+}
+
+# _bool: wrap a Perl truthy/falsy into a JS boolean (JSON::PP::Boolean), so
+# boolean-valued operators (relational, ===, !, Boolean()) return a real
+# boolean rather than 1/0 — matching the Go evaluator's bool (e.g.
+# String(a < b) is "true", and `'x' + (a < b)` is "xtrue"). The coercions
+# above already treat JSON::PP::Boolean correctly.
+sub _bool ($t) { $t ? JSON::PP::true() : JSON::PP::false() }
+
+# ---------------------------------------------------------------------------
+# Operators
+# ---------------------------------------------------------------------------
+
+sub _binary ($op, $l, $r) {
+    if ($op eq '+') {
+        # JS `+`: string concatenation once either operand is a string,
+        # numeric addition otherwise.
+        return _to_string($l) . _to_string($r) if _is_string($l) || _is_string($r);
+        return _to_number($l) + _to_number($r);
+    }
+    return _to_number($l) - _to_number($r) if $op eq '-';
+    return _to_number($l) * _to_number($r) if $op eq '*';
+    if ($op eq '/') {
+        my $ln = _to_number($l);
+        my $rn = _to_number($r);
+        # JS division by zero is finite-valued, not an error: x/0 is ±Infinity
+        # (NaN for 0/0). Perl's native `/` dies on a zero divisor, so guard it
+        # to stay JS-faithful and match the Go evaluator (Go float division
+        # already yields ±Inf / NaN).
+        if ($rn == 0) {
+            return _nan() if $ln == 0 || $ln != $ln;
+            return $ln > 0 ? 9**9**9 : -(9**9**9);
+        }
+        return $ln / $rn;
+    }
+    if ($op eq '%') {
+        my $rn = _to_number($r);
+        return _nan() if $rn == 0;
+        return POSIX::fmod(_to_number($l), $rn);
+    }
+    return _relational($op, $l, $r) if $op eq '<' || $op eq '<=' || $op eq '>' || $op eq '>=';
+    return _bool(_strict_eq($l, $r))  if $op eq '===';
+    return _bool(!_strict_eq($l, $r)) if $op eq '!==';
+    # Loose equality / bitwise / shift are out of the subset.
+    return undef;
+}
+
+sub _relational ($op, $l, $r) {
+    # JS Abstract Relational Comparison: both strings → compare by code unit;
+    # otherwise coerce both to numbers (a NaN operand makes it false).
+    my $c;
+    if (_is_string($l) && _is_string($r)) {
+        $c = $l lt $r ? -1 : $l gt $r ? 1 : 0;
+    }
+    else {
+        my $ln = _to_number($l);
+        my $rn = _to_number($r);
+        return _bool(0) if $ln != $ln || $rn != $rn;    # NaN → false
+        $c = $ln < $rn ? -1 : $ln > $rn ? 1 : 0;
+    }
+    return _bool($c < 0)  if $op eq '<';
+    return _bool($c <= 0) if $op eq '<=';
+    return _bool($c > 0)  if $op eq '>';
+    return _bool($c >= 0) if $op eq '>=';
+    return _bool(0);
+}
+
+sub _strict_eq ($l, $r) {
+    # Strict `===`: equal JS type and value, no coercion.
+    my $ln = _is_number($l);
+    my $rn = _is_number($r);
+    if ($ln && $rn) {
+        my ($lf, $rf) = ($l + 0, $r + 0);
+        return 0 if $lf != $lf || $rf != $rf;    # NaN
+        return $lf == $rf ? 1 : 0;
+    }
+    return 0 if $ln != $rn;    # one numeric, one not
+    if (!defined $l) { return !defined $r ? 1 : 0 }
+    return 0 if !defined $r;
+    my $lb = ref $l eq 'JSON::PP::Boolean';
+    my $rb = ref $r eq 'JSON::PP::Boolean';
+    if ($lb || $rb) {
+        return 0 unless $lb && $rb;
+        return ((!!$l) == (!!$r)) ? 1 : 0;
+    }
+    return ($l eq $r ? 1 : 0) if _is_string($l) && _is_string($r);
+    return 0;
+}
+
+sub _unary ($op, $v) {
+    return _bool(!_truthy($v)) if $op eq '!';
+    return -_to_number($v) if $op eq '-';
+    return _to_number($v)  if $op eq '+';
+    return undef;
+}
+
+# ---------------------------------------------------------------------------
+# Built-in calls (the deterministic allowlist). Locale-sensitive builtins
+# (localeCompare) are deliberately excluded to keep the backends isomorphic.
+# ---------------------------------------------------------------------------
+
+# _builtin_name: resolve a `call` callee to its builtin name (e.g.
+# "Math.max"), or '' when the callee is not an allowlisted builtin reference.
+sub _builtin_name ($callee) {
+    return '' unless ref $callee eq 'HASH';
+    my $kind = $callee->{kind} // '';
+    if ($kind eq 'identifier') {
+        return $callee->{name} // '';
+    }
+    if ($kind eq 'member' && !$callee->{computed}) {
+        my $obj = $callee->{object};
+        return '' unless ref $obj eq 'HASH' && ($obj->{kind} // '') eq 'identifier';
+        return ($obj->{name} // '') . '.' . ($callee->{property} // '');
+    }
+    return '';
+}
+
+# _math_round: half rounds toward +Infinity (JS Math.round: 2.5→3, -2.5→-2),
+# matching the existing round helper rather than half-away-from-zero.
+sub _math_round ($n) {
+    return POSIX::floor($n + 0.5);
+}
+
+sub _call_builtin ($name, $args) {
+    if ($name eq 'Math.max') {
+        my $m = -(9**9**9);    # JS Math.max() with no args is -Infinity
+        for my $a (@$args) {
+            my $n = _to_number($a);
+            return $n if $n != $n;    # any NaN argument ⇒ NaN (JS / Go)
+            $m = $n if $n > $m;
+        }
+        return $m;
+    }
+    if ($name eq 'Math.min') {
+        my $m = 9**9**9;       # JS Math.min() with no args is +Infinity
+        for my $a (@$args) {
+            my $n = _to_number($a);
+            return $n if $n != $n;    # any NaN argument ⇒ NaN (JS / Go)
+            $m = $n if $n < $m;
+        }
+        return $m;
+    }
+    return abs(_to_number($args->[0]))          if $name eq 'Math.abs';
+    return POSIX::floor(_to_number($args->[0])) if $name eq 'Math.floor';
+    return POSIX::ceil(_to_number($args->[0]))  if $name eq 'Math.ceil';
+    return _math_round(_to_number($args->[0]))  if $name eq 'Math.round';
+    return _to_string($args->[0])              if $name eq 'String';
+    return _to_number($args->[0])              if $name eq 'Number';
+    return _bool(_truthy($args->[0]))          if $name eq 'Boolean';
+    # Any other callee is outside the subset (refused upstream).
+    return undef;
+}
+
+# ---------------------------------------------------------------------------
+# Member / index access
+# ---------------------------------------------------------------------------
+
+sub _read_property ($obj, $key) {
+    return undef unless defined $obj;
+    if (ref $obj eq 'HASH') {
+        return exists $obj->{$key} ? $obj->{$key} : undef;
+    }
+    if (ref $obj eq 'ARRAY') {
+        return $key eq 'length' ? scalar(@$obj) : undef;
+    }
+    return undef if ref $obj;
+    # `.length` is a string property only — a numeric scalar (123) has no
+    # `.length` in the subset (JS `(123).length` is undefined → null), so
+    # guard on _is_string rather than coercing the number to a string.
+    # Matches the Go evaluator (numbers fall through to nil there).
+    return length($obj) if $key eq 'length' && _is_string($obj);
+    return undef;
+}
+
+sub _read_index ($obj, $index) {
+    if (ref $obj eq 'ARRAY') {
+        my $f = _to_number($index);
+        my $i = int($f);
+        return undef if $i != $f || $i < 0 || $i >= @$obj;
+        return $obj->[$i];
+    }
+    if (ref $obj eq 'HASH') {
+        return $obj->{ _to_string($index) };
+    }
+    return undef;
+}
+
+# ---------------------------------------------------------------------------
+# Evaluator-driven higher-order folds (the generalization of bf_reduce /
+# bf_sort onto the evaluator) — the runtime half both Perl backends share.
+# ---------------------------------------------------------------------------
+
+# fold($items, $body, $acc_name, $item_name, $init, $direction, $base_env)
+#
+# Fold an arrayref into a value via the evaluator. The reducer $body is a
+# pure ParsedExpr node evaluated against `{$acc_name => acc, $item_name =>
+# item}` plus the captured free vars in $base_env per element; $init seeds the
+# accumulator and $direction is "left" (reduce) or "right" (reduceRight).
+# Generalizes bf_reduce — any reducer body, not just the +/* arithmetic
+# catalogue, and acc may appear anywhere. $base_env is optional; the
+# acc/item keys shadow any same-named base key. Mirrors Go's FoldEval.
+sub fold ($items, $body, $acc_name, $item_name, $init, $direction = 'left', $base_env = undef) {
+    my @arr = ref $items eq 'ARRAY' ? @$items : ();
+    @arr = reverse @arr if ($direction // '') eq 'right';
+    # Seed the env from the captured free vars once; acc / item are
+    # overwritten each iteration (constant base keys carry through).
+    my %env = $base_env ? %$base_env : ();
+    my $acc = $init;
+    for my $item (@arr) {
+        $env{$acc_name}  = $acc;
+        $env{$item_name} = $item;
+        $acc = evaluate($body, \%env);
+    }
+    return $acc;
+}
+
+# sort_by($items, $cmp, $param_a, $param_b, $base_env)
+#
+# Return a new arrayref ordered by a ParsedExpr comparator $cmp evaluated
+# against `{$param_a => a, $param_b => b}` plus the captured free vars in
+# $base_env to a number (negative / zero / positive, like a JS comparator).
+# Generalizes bf_sort — any comparator body. $base_env is optional. Stable
+# and non-mutating. Mirrors Go's SortEval.
+sub sort_by ($items, $cmp, $param_a, $param_b, $base_env = undef) {
+    # Non-array receiver → empty arrayref, matching the nil-tolerant
+    # BarefootJS->sort helper convention (and avoiding an undef-deref footgun
+    # for callers that use the result as an arrayref). Value-compatible with
+    # the Go SortEval, whose nil slice iterates as empty too.
+    return [] unless ref $items eq 'ARRAY';
+    my %env = $base_env ? %$base_env : ();
+    # Decorate each element with its original index and tie-break on it when
+    # the comparator returns 0, so stability is explicit and independent of
+    # the `sort` pragma / build (portable to the declared minimum Perl, and
+    # matching Go's sort.SliceStable).
+    my @decorated = map { [ $_, $items->[$_] ] } 0 .. $#$items;
+    my @sorted = sort {
+        $env{$param_a} = $a->[1];
+        $env{$param_b} = $b->[1];
+        my $c = _to_number(evaluate($cmp, \%env));
+        # Explicit sign test rather than `<=> 0`: a NaN comparator result
+        # warns / is undefined under `<=>`, whereas `< 0` / `> 0` are both
+        # false for NaN, yielding 0 (no reordering) — matching JS (NaN
+        # comparator ⇒ keep order) and the Go SortEval sign test. The
+        # original-index tie-break then preserves input order for equal keys.
+        ($c < 0 ? -1 : $c > 0 ? 1 : 0) || ($a->[0] <=> $b->[0])
+    } @decorated;
+    return [ map { $_->[1] } @sorted ];
+}
+
+# JSON entry points for the adapters: decode the callback body once, then fold /
+# sort. Mirror the Go `bf_reduce_eval` / `bf_sort_eval` template funcs, which the
+# adapters emit with a serialized-ParsedExpr body argument.
+sub fold_json ($items, $body_json, $acc_name, $item_name, $init, $direction = 'left', $base_env = undef) {
+    require JSON::PP;
+    return fold($items, JSON::PP->new->decode($body_json), $acc_name, $item_name, $init, $direction, $base_env);
+}
+
+sub sort_by_json ($items, $cmp_json, $param_a, $param_b, $base_env = undef) {
+    require JSON::PP;
+    return sort_by($items, JSON::PP->new->decode($cmp_json), $param_a, $param_b, $base_env);
+}
+
+# ---------------------------------------------------------------------------
+# Higher-order predicates (#2018, P2) — the generalization of bf_filter /
+# bf_find / bf_find_index / bf_every / bf_some onto the evaluator. The
+# predicate $pred is a pure ParsedExpr evaluated against `{$param => item}`
+# plus the captured free vars in $base_env per element, lifting the
+# field-equality / truthiness restriction to any pure predicate body. Each
+# mirrors the corresponding Go helper (FilterEval / EveryEval / SomeEval /
+# FindEval / FindIndexEval). $base_env is optional.
+# ---------------------------------------------------------------------------
+
+# filter — new arrayref of the elements the predicate keeps. Non-array receiver
+# → empty arrayref (the BarefootJS->filter nil-tolerant convention).
+sub filter ($items, $pred, $param, $base_env = undef) {
+    return [] unless ref $items eq 'ARRAY';
+    my %env = $base_env ? %$base_env : ();
+    my @out;
+    for my $item (@$items) {
+        $env{$param} = $item;
+        push @out, $item if _truthy(evaluate($pred, \%env));
+    }
+    return \@out;
+}
+
+# every — 1 iff the predicate holds for every element (vacuously 1 for an empty
+# receiver, like JS).
+sub every ($items, $pred, $param, $base_env = undef) {
+    my @arr = ref $items eq 'ARRAY' ? @$items : ();
+    my %env = $base_env ? %$base_env : ();
+    for my $item (@arr) {
+        $env{$param} = $item;
+        return 0 unless _truthy(evaluate($pred, \%env));
+    }
+    return 1;
+}
+
+# some — 1 iff the predicate holds for any element (0 for an empty receiver).
+sub some ($items, $pred, $param, $base_env = undef) {
+    my @arr = ref $items eq 'ARRAY' ? @$items : ();
+    my %env = $base_env ? %$base_env : ();
+    for my $item (@arr) {
+        $env{$param} = $item;
+        return 1 if _truthy(evaluate($pred, \%env));
+    }
+    return 0;
+}
+
+# find — first matching element, or undef. $forward false searches from the end
+# (findLast).
+sub find ($items, $pred, $param, $forward = 1, $base_env = undef) {
+    my @arr = ref $items eq 'ARRAY' ? @$items : ();
+    @arr = reverse @arr unless $forward;
+    my %env = $base_env ? %$base_env : ();
+    for my $item (@arr) {
+        $env{$param} = $item;
+        return $item if _truthy(evaluate($pred, \%env));
+    }
+    return undef;
+}
+
+# find_index — index of the first matching element, or -1. $forward false →
+# findLastIndex (the index is into the original array either way).
+sub find_index ($items, $pred, $param, $forward = 1, $base_env = undef) {
+    my @arr = ref $items eq 'ARRAY' ? @$items : ();
+    my %env = $base_env ? %$base_env : ();
+    my @idx = $forward ? ( 0 .. $#arr ) : reverse( 0 .. $#arr );
+    for my $i (@idx) {
+        $env{$param} = $arr[$i];
+        return $i if _truthy(evaluate($pred, \%env));
+    }
+    return -1;
+}
+
+# flat_map — project each element through $proj (a pure ParsedExpr) and flatten
+# the results one level. A projection yielding an arrayref contributes its
+# elements; any other value contributes itself (JS `.flatMap` keeps a non-array
+# return as a single element). Generalizes bf->flat_map / flat_map_tuple to any
+# pure projection. Mirrors Go's FlatMapEval. $base_env is optional.
+sub flat_map ($items, $proj, $param, $base_env = undef) {
+    my @arr = ref $items eq 'ARRAY' ? @$items : ();
+    my %env = $base_env ? %$base_env : ();
+    my @out;
+    for my $item (@arr) {
+        $env{$param} = $item;
+        my $v = evaluate($proj, \%env);
+        if (ref $v eq 'ARRAY') { push @out, @$v }
+        else                   { push @out, $v }
+    }
+    return \@out;
+}
+
+# ---------------------------------------------------------------------------
+# JSON-string seams — the adapters emit `bf->filter_eval($recv, '<json>', …)`;
+# the predicate body arrives as a JSON string here, decoded then handed to the
+# helper above (mirroring fold_json / sort_by_json).
+# ---------------------------------------------------------------------------
+
+sub filter_json ($items, $pred_json, $param, $base_env = undef) {
+    require JSON::PP;
+    return filter($items, JSON::PP->new->decode($pred_json), $param, $base_env);
+}
+
+sub every_json ($items, $pred_json, $param, $base_env = undef) {
+    require JSON::PP;
+    return every($items, JSON::PP->new->decode($pred_json), $param, $base_env);
+}
+
+sub some_json ($items, $pred_json, $param, $base_env = undef) {
+    require JSON::PP;
+    return some($items, JSON::PP->new->decode($pred_json), $param, $base_env);
+}
+
+sub find_json ($items, $pred_json, $param, $forward = 1, $base_env = undef) {
+    require JSON::PP;
+    return find($items, JSON::PP->new->decode($pred_json), $param, $forward, $base_env);
+}
+
+sub find_index_json ($items, $pred_json, $param, $forward = 1, $base_env = undef) {
+    require JSON::PP;
+    return find_index($items, JSON::PP->new->decode($pred_json), $param, $forward, $base_env);
+}
+
+sub flat_map_json ($items, $proj_json, $param, $base_env = undef) {
+    require JSON::PP;
+    return flat_map($items, JSON::PP->new->decode($proj_json), $param, $base_env);
+}
+
+1;

package/lib/BarefootJS.pm

@@ -1,5 +1,5 @@
 package BarefootJS;
-our $VERSION = "0.15.2";
+our $VERSION = "0.16.0";
 use strict;
 use warnings;
 use utf8;
@@ -8,6 +8,7 @@ no warnings 'experimental::signatures';
 
 use POSIX ();
 use Scalar::Util qw(looks_like_number weaken);
+use BarefootJS::Evaluator ();
 
 # NOTE: This runtime is template-engine-agnostic AND framework-agnostic by
 # design, so it can ship as a standalone CPAN distribution. It depends only on
@@ -1010,6 +1011,53 @@ sub replace ($self, $recv, $pattern, $replacement) {
     return substr($s, 0, $i) . $n . substr($s, $i + CORE::length($o));
 }
 
+# `queryHref(base, { … })` (#2042) — build `"$base?k=v&…"` from a flat list of
+# (guard, key, value) triples. A pair is included iff its guard is truthy AND
+# its value is a non-empty string, mirroring the client `queryHref`'s `if
+# (value)` over string values: the adapter passes the guard `1` for a plain
+# `key: v`, or the lowered condition for `key: cond ? v : undefined`. Repeating a
+# key overwrites the value at its first position (`URLSearchParams.set`
+# semantics).
+#
+# A value may instead be an array ref, which APPENDS one pair per non-empty
+# member (`{ tag => ['a','b'] }` → `tag=a&tag=b`, i.e. `URLSearchParams.append`);
+# empty members are skipped, so an empty/all-empty array contributes nothing.
+#
+# Keys/values are form-encoded to equal the browser render byte-for-byte; no
+# surviving pair yields the bare base.
+sub query ($self, $base, @triples) {
+    my $b = defined $base && !ref($base) ? "$base" : '';
+    my (@pairs, %pos);
+    my $i = 0;
+    while ($i + 2 < @triples) {
+        my ($guard, $key, $val) = @triples[$i, $i + 1, $i + 2];
+        $i += 3;
+        next unless $guard;
+        $key = defined $key && !ref($key) ? "$key" : '';
+        if (ref($val) eq 'ARRAY') {
+            # Append each non-empty member; appended pairs never overwrite, so
+            # they don't participate in the set()-position map.
+            for my $m (@$val) {
+                my $s = defined $m && !ref($m) ? "$m" : '';
+                next if $s eq '';
+                push @pairs, [$key, $s];
+            }
+            next;
+        }
+        $val = defined $val && !ref($val) ? "$val" : '';
+        next if $val eq '';
+        if (exists $pos{$key}) {
+            $pairs[$pos{$key}][1] = $val;
+        }
+        else {
+            $pos{$key} = scalar @pairs;
+            push @pairs, [$key, $val];
+        }
+    }
+    return $b unless @pairs;
+    return "$b?" . CORE::join('&', map { _form_escape($_->[0]) . '=' . _form_escape($_->[1]) } @pairs);
+}
+
 # `String.prototype.repeat(n)` — the receiver concatenated n times
 # (#1448 Tier B), via Perl's `x` operator. JS throws RangeError for a
 # negative count, but SSR templates degrade to the empty string rather
@@ -1089,6 +1137,49 @@ sub pad_end ($self, $recv, $target, $pad = undef) {
 # A future `nulls => 'first' | 'last'` knob can land per key without
 # churn — the opts hash is the right place to grow.
 
+# Evaluator-driven sort / reduce (#2018): the comparator / reducer body rides
+# as a serialized-ParsedExpr JSON string and is evaluated per element, delegating
+# to the shared BarefootJS::Evaluator. The adapter emits `bf->sort_eval(...)` /
+# `bf->reduce_eval(...)` for any pure comparator / reducer body; a body it can't
+# model (e.g. localeCompare) keeps the legacy `bf->sort` / `bf->reduce` path.
+sub sort_eval ($self, $recv, $cmp_json, $param_a, $param_b, $base_env = {}) {
+    return BarefootJS::Evaluator::sort_by_json($recv, $cmp_json, $param_a, $param_b, $base_env);
+}
+
+sub reduce_eval ($self, $recv, $body_json, $acc_name, $item_name, $init, $direction = 'left', $base_env = {}) {
+    return BarefootJS::Evaluator::fold_json($recv, $body_json, $acc_name, $item_name, $init, $direction, $base_env);
+}
+
+# Evaluator-driven higher-order predicates (#2018, P2): the predicate body
+# rides as a serialized-ParsedExpr JSON string evaluated per element, delegating
+# to the shared BarefootJS::Evaluator. The adapter emits `bf->filter_eval(...)`
+# etc. for any pure predicate; a body it can't model (e.g. a method-call
+# predicate) keeps the legacy `grep` / `bf->find` path. `find_eval` /
+# `find_index_eval` take a `$forward` flag (false → findLast / findLastIndex).
+sub filter_eval ($self, $recv, $pred_json, $param, $base_env = {}) {
+    return BarefootJS::Evaluator::filter_json($recv, $pred_json, $param, $base_env);
+}
+
+sub every_eval ($self, $recv, $pred_json, $param, $base_env = {}) {
+    return BarefootJS::Evaluator::every_json($recv, $pred_json, $param, $base_env);
+}
+
+sub some_eval ($self, $recv, $pred_json, $param, $base_env = {}) {
+    return BarefootJS::Evaluator::some_json($recv, $pred_json, $param, $base_env);
+}
+
+sub find_eval ($self, $recv, $pred_json, $param, $forward = 1, $base_env = {}) {
+    return BarefootJS::Evaluator::find_json($recv, $pred_json, $param, $forward, $base_env);
+}
+
+sub find_index_eval ($self, $recv, $pred_json, $param, $forward = 1, $base_env = {}) {
+    return BarefootJS::Evaluator::find_index_json($recv, $pred_json, $param, $forward, $base_env);
+}
+
+sub flat_map_eval ($self, $recv, $proj_json, $param, $base_env = {}) {
+    return BarefootJS::Evaluator::flat_map_json($recv, $proj_json, $param, $base_env);
+}
+
 sub sort ($self, $recv, $opts = {}) {
     return [] unless ref($recv) eq 'ARRAY';
 
@@ -1266,6 +1357,18 @@ sub _to_attr_name ($key) {
     return $out;
 }
 
+sub _form_escape ($s) {
+    # application/x-www-form-urlencoded serialisation, matching the browser's
+    # `URLSearchParams` (which the SSR query render must equal): keep ASCII
+    # alphanumerics and `* - . _`; encode every other byte as `%XX` (UPPER hex);
+    # space → `+`. Non-ASCII is encoded byte-wise over its UTF-8 bytes.
+    my $bytes = defined $s ? "$s" : '';
+    utf8::encode($bytes) if utf8::is_utf8($bytes);
+    $bytes =~ s/([^A-Za-z0-9*\-._ ])/sprintf('%%%02X', ord($1))/ge;
+    $bytes =~ tr/ /+/;
+    return $bytes;
+}
+
 sub _html_escape ($value) {
     # HTML attribute-value escape for SSR string emission. The
     # spread bag's values reach the browser as part of a generated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/perl",
-  "version": "0.16.0",
+  "version": "0.17.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/eval_vectors.t

@@ -0,0 +1,113 @@
+use strict;
+use warnings;
+use Test::More;
+use FindBin;
+use File::Spec;
+use JSON::PP ();
+use B ();
+use Scalar::Util qw(looks_like_number);
+
+use lib "$FindBin::Bin/../lib";
+use BarefootJS::Evaluator;
+
+# Golden ParsedExpr-evaluator vectors (issue #2018, spec/compiler.md
+# "ParsedExpr Evaluator Semantics"), generated from the JS reference
+# evaluator and shared with the Go evaluator. 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', 'eval-vectors.json'
+);
+plan skip_all => 'eval 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>);
+};
+
+die "eval-vectors.json contains no cases" unless @{ $doc->{cases} || [] };
+
+# The evaluator is JS-faithful by contract, so there are NO Perl-side
+# divergences here (unlike the bf->string / number helper vectors). Each
+# case's real ParsedExpr tree, evaluated against its environment, must
+# reproduce the JS-computed expect exactly — same input → same output as Go.
+for my $case (@{ $doc->{cases} }) {
+    my $note   = $case->{note};
+    my $expr   = $case->{expr};
+    my $env    = $case->{env};
+    my $expect = $case->{expect};
+
+    my $got = eval { BarefootJS::Evaluator::evaluate($expr, $env) };
+    if (my $err = $@) {
+        fail("$note died: $err");
+        next;
+    }
+    ok(_match($got, $expect), $note)
+        or diag('got ' . explain_value($got) . ', want ' . explain_value($expect));
+}
+
+done_testing;
+
+# _is_real_number: true only when the scalar is an actual number (SV carries
+# IOK/NOK), NOT a numeric-looking string. JSON::PP decodes a JSON number to
+# IOK/NOK and a JSON string to a POK-only scalar, so this tells the JS *number*
+# 42 from the JS *string* "42" — the distinction the evaluator must preserve.
+# (looks_like_number can't: it is true for the string "42" too.)
+sub _is_real_number {
+    my ($v) = @_;
+    return 0 unless defined $v && !ref $v;
+    return (B::svref_2object(\$v)->FLAGS & (B::SVf_IOK | B::SVf_NOK)) ? 1 : 0;
+}
+
+# _match: boolean form of the spec's value-compat comparison against a
+# JSON-decoded expect — non-finite sentinel hashes, booleans by truthiness,
+# numbers numerically, arrays/hashes recursively, strings by eq.
+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)) {
+        # The result must itself be a JS boolean (JSON::PP::Boolean), not a
+        # truthy/falsy 1/0 — otherwise a boolean-valued expression returning
+        # the number 1 instead of `true` would pass and mask the divergence.
+        return 0 unless JSON::PP::is_bool($got);
+        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;
+    # Numeric == only when BOTH are real numbers (not numeric-looking strings),
+    # so a string-vs-number mismatch fails: e.g. String(42) must return the
+    # string "42", and the evaluator returning the number 42 must NOT pass.
+    my $want_num = _is_real_number($expect);
+    return 0 if $want_num != _is_real_number($got);
+    return ($got == $expect ? 1 : 0) if $want_num;
+    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/evaluator.t

@@ -0,0 +1,265 @@
+use strict;
+use warnings;
+use Test::More;
+use FindBin;
+use JSON::PP ();
+
+use lib "$FindBin::Bin/../lib";
+use BarefootJS::Evaluator;
+
+# Hand-built ParsedExpr constructors for the fold / sort_by trees, mirroring
+# the Go eval_test.go demonstrations so the two backends prove the SAME
+# restriction-lifting on the SAME shapes.
+sub nid  { return { kind => 'identifier', name => $_[0] } }
+sub nmem { return { kind => 'member', object => $_[0], property => $_[1], computed => JSON_false() } }
+sub nbin { return { kind => 'binary', op => $_[0], left => $_[1], right => $_[2] } }
+sub nstr { return { kind => 'literal', value => $_[0], literalType => 'string' } }
+
+sub ncall_math {
+    my ($fn, $arg) = @_;
+    return { kind => 'call', callee => nmem(nid('Math'), $fn), args => [$arg] };
+}
+
+# A plain false for the `computed` flag; the evaluator only checks truthiness.
+sub JSON_false { return 0 }
+
+# fold lifts bf_reduce's op restriction and acc-canonical form: a reducer body
+# that mixes acc with a product of two fields is impossible in the +/*
+# self/field catalogue but trivial for the evaluator.
+subtest 'fold: arbitrary reducer body (acc + item.price * item.qty)' => sub {
+    my $body = nbin('+',
+        nid('acc'),
+        nbin('*', nmem(nid('item'), 'price'), nmem(nid('item'), 'qty')),
+    );
+    my $items = [ { price => 5, qty => 3 }, { price => 2, qty => 4 } ];
+    is(BarefootJS::Evaluator::fold($items, $body, 'acc', 'item', 0, 'left'),
+        23, '0 + 5*3 + 2*4');
+};
+
+# reduceRight is observable for string concatenation; the same body folds both
+# directions.
+subtest 'fold: direction is observable for string concat' => sub {
+    my $body  = nbin('+', nid('acc'), nid('item'));
+    my $items = [ 'a', 'b', 'c' ];
+    is(BarefootJS::Evaluator::fold($items, $body, 'acc', 'item', '', 'left'),  'abc', 'left');
+    is(BarefootJS::Evaluator::fold($items, $body, 'acc', 'item', '', 'right'), 'cba', 'right');
+};
+
+# sort_by lifts bf_sort's comparator pattern restriction: a comparator that
+# calls Math.abs on each operand's field is outside the subtraction /
+# localeCompare / relational-ternary catalogue, but is just another pure
+# expression to the evaluator.
+subtest 'sort_by: arbitrary comparator body (abs-of-field difference)' => sub {
+    my $cmp = nbin('-',
+        ncall_math('abs', nmem(nid('a'), 'v')),
+        ncall_math('abs', nmem(nid('b'), 'v')),
+    );
+    my $items  = [ { v => -5 }, { v => 3 }, { v => -1 } ];
+    my $sorted = BarefootJS::Evaluator::sort_by($items, $cmp, 'a', 'b');
+    is_deeply([ map { $_->{v} } @$sorted ], [ -1, 3, -5 ], 'ascending by |v|');
+};
+
+# Descending is just a reversed comparator body — no separate direction knob.
+subtest 'sort_by: descending via a reversed comparator' => sub {
+    my $cmp = nbin('-', nmem(nid('b'), 'x'), nmem(nid('a'), 'x'));
+    my $items  = [ { x => 10 }, { x => 30 }, { x => 20 } ];
+    my $sorted = BarefootJS::Evaluator::sort_by($items, $cmp, 'a', 'b');
+    is_deeply([ map { $_->{x} } @$sorted ], [ 30, 20, 10 ], 'descending by x');
+};
+
+# Non-finite coercion stays JS-faithful (and matches the Go evaluator):
+# division by zero is ±Infinity / NaN rather than a Perl die, and those
+# values stringify as "Infinity" / "-Infinity" / "NaN" (not Perl's "Inf").
+subtest 'non-finite: division by zero and JS stringification' => sub {
+    my $div = sub {
+        my ($a, $b) = @_;
+        BarefootJS::Evaluator::evaluate(
+            nbin('/', { kind => 'identifier', name => 'a' }, { kind => 'identifier', name => 'b' }),
+            { a => $a, b => $b },
+        );
+    };
+    my $inf = 9**9**9;
+    is($div->(1, 0),  $inf,  '1/0 is +Infinity, not a die');
+    is($div->(-1, 0), -$inf, '-1/0 is -Infinity');
+    my $nan = $div->(0, 0);
+    ok($nan != $nan, '0/0 is NaN');
+
+    is(BarefootJS::Evaluator::_to_string($inf),    'Infinity',  'String(Infinity)');
+    is(BarefootJS::Evaluator::_to_string(-$inf),   '-Infinity', 'String(-Infinity)');
+    is(BarefootJS::Evaluator::_to_string($inf - $inf), 'NaN',   'String(NaN)');
+};
+
+# Captured free vars flow through $base_env (mirrors the Go FoldEval/SortEval
+# baseEnv test) — a reducer / comparator body can reference an outer const.
+subtest 'captured free vars via base_env' => sub {
+    # reduce: acc + item * factor, with `factor` captured.
+    my $body = nbin('+', nid('acc'), nbin('*', nid('item'), nid('factor')));
+    my $sum = BarefootJS::Evaluator::fold([1, 2, 3], $body, 'acc', 'item', 0, 'left', { factor => 10 });
+    is($sum, 60, '0 + 1*10 + 2*10 + 3*10 with captured factor');
+
+    # sort by distance from a captured `pivot`: |a-pivot| - |b-pivot|.
+    my $cmp = nbin('-',
+        ncall_math('abs', nbin('-', nid('a'), nid('pivot'))),
+        ncall_math('abs', nbin('-', nid('b'), nid('pivot'))),
+    );
+    my $sorted = BarefootJS::Evaluator::sort_by([1, 8, 4], $cmp, 'a', 'b', { pivot => 5 });
+    is_deeply($sorted, [4, 8, 1], 'ascending by distance from captured pivot');
+};
+
+# Boolean-valued operators return JS booleans (JSON::PP::Boolean), not 1/0 —
+# matching the Go evaluator, so they stringify "true"/"false" and concatenate
+# as JS does.
+subtest 'boolean-valued ops return JS booleans, not 1/0' => sub {
+    my $lt = BarefootJS::Evaluator::evaluate(nbin('<', nid('a'), nid('b')), { a => 1, b => 2 });
+    ok(JSON::PP::is_bool($lt), 'a < b is a JS boolean');
+    is(BarefootJS::Evaluator::_to_string($lt), 'true', 'String(a < b) is "true", not "1"');
+
+    my $cat = BarefootJS::Evaluator::evaluate(
+        nbin('+', nstr('x'), nbin('<', nid('a'), nid('b'))), { a => 1, b => 2 });
+    is($cat, 'xtrue', "'x' + (a < b) is 'xtrue', not 'x1'");
+
+    my $eq = BarefootJS::Evaluator::evaluate(nbin('===', nid('a'), nid('b')), { a => 1, b => 1 });
+    ok(JSON::PP::is_bool($eq), '1 === 1 is a JS boolean');
+
+    my $not = BarefootJS::Evaluator::evaluate({ kind => 'unary', op => '!', argument => nstr('') }, {});
+    is(BarefootJS::Evaluator::_to_string($not), 'true', 'String(!"") is "true"');
+
+    my $b = BarefootJS::Evaluator::evaluate(
+        { kind => 'call', callee => nid('Boolean'), args => [nstr('')] }, {});
+    ok(JSON::PP::is_bool($b), 'Boolean("") is a JS boolean');
+    is(BarefootJS::Evaluator::_to_string($b), 'false', 'String(Boolean("")) is "false", not "0"');
+
+    # `.length` is a string/array property only; a numeric scalar has none.
+    my $len = BarefootJS::Evaluator::evaluate(nmem(nid('n'), 'length'), { n => 123 });
+    ok(!defined $len, '(123).length is null, not 3');
+};
+
+# sort_by tolerates a non-array receiver by returning an empty arrayref (the
+# BarefootJS->sort convention), never undef — so callers can always deref it.
+subtest 'sort_by non-array receiver returns []' => sub {
+    my $cmp = nbin('-', nid('a'), nid('b'));
+    is_deeply(BarefootJS::Evaluator::sort_by(undef, $cmp, 'a', 'b'), [], 'undef receiver → []');
+    is_deeply(BarefootJS::Evaluator::sort_by(42, $cmp, 'a', 'b'), [], 'scalar receiver → []');
+};
+
+# sort_by is stable: equal-comparing elements keep their input order. The
+# explicit index tie-break makes this independent of the `sort` pragma /
+# build, matching Go's sort.SliceStable.
+subtest 'sort_by is stable for equal keys' => sub {
+    my $cmp = nbin('-', nmem(nid('a'), 'k'), nmem(nid('b'), 'k'));
+    # All-equal keys → input order preserved.
+    my $eq = BarefootJS::Evaluator::sort_by(
+        [ { k => 1, id => 'a' }, { k => 1, id => 'b' }, { k => 1, id => 'c' } ],
+        $cmp, 'a', 'b');
+    is_deeply([ map { $_->{id} } @$eq ], [ 'a', 'b', 'c' ], 'equal keys keep input order');
+    # Mixed keys → sorted by key, ties stable (x before z).
+    my $mixed = BarefootJS::Evaluator::sort_by(
+        [ { k => 2, id => 'x' }, { k => 1, id => 'y' }, { k => 2, id => 'z' } ],
+        $cmp, 'a', 'b');
+    is_deeply([ map { $_->{id} } @$mixed ], [ 'y', 'x', 'z' ], 'tie (x,z) stays in input order');
+};
+
+# fold_json / sort_by_json are the JSON-string seam the adapters emit into:
+# the serialized ParsedExpr body travels as a `bf->reduce_eval` / `bf->sort_eval`
+# argument and is decoded here, then handed to fold / sort_by. These exercise
+# the exact shapes the #2018 EXPR2 reduce/sort migration emits (field access
+# over hashref rows keyed by the raw JS prop name), with the captured-env arg.
+subtest 'fold_json / sort_by_json decode a JSON body and evaluate it' => sub {
+    my @rows = ({ duration => 95 }, { duration => 213 }, { duration => 185 });
+
+    # reduce: sum + t.duration, seed 0 → 493
+    my $reduce = JSON::PP->new->encode(
+        nbin('+', nid('sum'), nmem(nid('t'), 'duration')));
+    is(BarefootJS::Evaluator::fold_json(\@rows, $reduce, 'sum', 't', 0, 'left', {}),
+        493, 'fold_json sums a field');
+
+    # reduceRight concat is order-observable: cba, not abc.
+    my @labels = ({ label => 'a' }, { label => 'b' }, { label => 'c' });
+    my $concat = JSON::PP->new->encode(
+        nbin('+', nid('acc'), nmem(nid('x'), 'label')));
+    is(BarefootJS::Evaluator::fold_json(\@labels, $concat, 'acc', 'x', '', 'left', {}),
+        'abc', 'fold_json concat left → abc');
+    is(BarefootJS::Evaluator::fold_json(\@labels, $concat, 'acc', 'x', '', 'right', {}),
+        'cba', 'fold_json concat right → cba');
+
+    # sort: a.duration - b.duration → ascending
+    my $cmp = JSON::PP->new->encode(
+        nbin('-', nmem(nid('a'), 'duration'), nmem(nid('b'), 'duration')));
+    my $sorted = BarefootJS::Evaluator::sort_by_json(\@rows, $cmp, 'a', 'b', {});
+    is_deeply([ map { $_->{duration} } @$sorted ], [ 95, 185, 213 ],
+        'sort_by_json orders by a field');
+};
+
+# The #2018 P2 higher-order predicate helpers evaluate an arbitrary pure
+# predicate body per element, generalizing bf_filter / bf_find / bf_every /
+# bf_some. Mirrors the Go TestPredicateEvalHelpers shapes (u => u.age >= 18).
+subtest 'filter / every / some / find / find_index over a predicate body' => sub {
+    my @rows = ({ age => 15 }, { age => 30 }, { age => 18 });
+    my $pred = nbin('>=', nmem(nid('u'), 'age'),
+        { kind => 'literal', value => 18, literalType => 'number' });
+
+    my $f = BarefootJS::Evaluator::filter(\@rows, $pred, 'u');
+    is_deeply([ map { $_->{age} } @$f ], [ 30, 18 ], 'filter keeps age >= 18');
+
+    is(BarefootJS::Evaluator::some(\@rows, $pred, 'u'), 1, 'some → true');
+    is(BarefootJS::Evaluator::every(\@rows, $pred, 'u'), 0, 'every → false (15 < 18)');
+
+    is(BarefootJS::Evaluator::find(\@rows, $pred, 'u', 1)->{age}, 30, 'find forward → 30');
+    is(BarefootJS::Evaluator::find(\@rows, $pred, 'u', 0)->{age}, 18, 'findLast → 18');
+    is(BarefootJS::Evaluator::find_index(\@rows, $pred, 'u', 1), 1, 'findIndex → 1');
+    is(BarefootJS::Evaluator::find_index(\@rows, $pred, 'u', 0), 2, 'findLastIndex → 2');
+
+    # Empty receiver: every vacuously true, some false, find undef / index -1.
+    is(BarefootJS::Evaluator::every([], $pred, 'u'), 1, 'every(empty) → true');
+    is(BarefootJS::Evaluator::some([], $pred, 'u'), 0, 'some(empty) → false');
+    ok(!defined BarefootJS::Evaluator::find([], $pred, 'u'), 'find(empty) → undef');
+    is(BarefootJS::Evaluator::find_index([], $pred, 'u'), -1, 'find_index(empty) → -1');
+
+    # JSON seam: the body arrives as the string the adapter emits. Cover more
+    # than filter_json so each *_json entry point is pinned (Copilot review
+    # #2032).
+    my $json = JSON::PP->new->encode($pred);
+    my $fj = BarefootJS::Evaluator::filter_json(\@rows, $json, 'u');
+    is_deeply([ map { $_->{age} } @$fj ], [ 30, 18 ], 'filter_json decodes + filters');
+    is(BarefootJS::Evaluator::every_json(\@rows, $json, 'u'), 0, 'every_json → false');
+    is(BarefootJS::Evaluator::some_json(\@rows, $json, 'u'),  1, 'some_json → true');
+    is(BarefootJS::Evaluator::find_json(\@rows, $json, 'u', 1)->{age}, 30, 'find_json forward → 30');
+    is(BarefootJS::Evaluator::find_index_json(\@rows, $json, 'u', 0), 2, 'find_index_json backward → 2');
+
+    # Captured base_env: a predicate `u => u.age >= threshold` reads the outer
+    # `threshold`, and changing it changes the result — pins the capture
+    # plumbing (Copilot review #2032).
+    my $cap = nbin('>=', nmem(nid('u'), 'age'), nid('threshold'));
+    my $hi  = BarefootJS::Evaluator::filter(\@rows, $cap, 'u', { threshold => 18 });
+    my $lo  = BarefootJS::Evaluator::filter(\@rows, $cap, 'u', { threshold => 100 });
+    is(scalar(@$hi), 2, 'captured threshold 18 keeps 2');
+    is(scalar(@$lo), 0, 'captured threshold 100 keeps 0');
+    is(BarefootJS::Evaluator::find_index(\@rows, $cap, 'u', 1, { threshold => 100 }), -1,
+        'find_index with unmet captured threshold → -1');
+};
+
+# #2018 P3: flat_map projects each element through a projection body and
+# flattens one level — a field projection yielding an arrayref contributes its
+# elements; an array-literal (tuple) projection contributes its leaves. Mirrors
+# the Go TestFlatMapEval shapes.
+subtest 'flat_map projects + flattens one level' => sub {
+    my @rows = ({ tags => [ 'a', 'b' ] }, { tags => [ 'c' ] });
+    my $field = nmem(nid('i'), 'tags');
+    is_deeply(BarefootJS::Evaluator::flat_map(\@rows, $field, 'i'), [ 'a', 'b', 'c' ],
+        'field projection flattens the per-item arrays');
+
+    my @pts = ({ x => 1, y => 2 }, { x => 3, y => 4 });
+    my $tuple = {
+        kind     => 'array-literal',
+        elements => [ nmem(nid('p'), 'x'), nmem(nid('p'), 'y') ],
+    };
+    is_deeply(BarefootJS::Evaluator::flat_map(\@pts, $tuple, 'p'), [ 1, 2, 3, 4 ],
+        'array-literal projection flattens the leaf tuples');
+
+    # JSON seam.
+    my $fj = BarefootJS::Evaluator::flat_map_json(\@rows,
+        JSON::PP->new->encode($field), 'i');
+    is_deeply($fj, [ 'a', 'b', 'c' ], 'flat_map_json decodes + projects');
+};
+
+done_testing;

package/t/helper_vectors.t

@@ -9,6 +9,12 @@ use Scalar::Util qw(looks_like_number);
 use lib "$FindBin::Bin/../lib";
 use BarefootJS;
 
+# vectors.json is UTF-8 (string args like "café"; `≡` in some notes). Decode it
+# as UTF-8 (below) and route TAP through a UTF-8 layer so wide test names don't
+# trigger "Wide character in print".
+binmode Test::More->builder->$_, ':encoding(UTF-8)'
+    for qw(output failure_output todo_output);
+
 # Pure-Perl backend (core JSON::PP only) so this test runs with zero
 # Mojo present — same pattern as t/template_primitives.t.
 {
@@ -37,7 +43,10 @@ plan skip_all => 'golden vectors not available outside the monorepo checkout'
 my $doc = do {
     open my $fh, '<:raw', $vectors_path or die "open $vectors_path: $!";
     local $/;
-    JSON::PP->new->decode(<$fh>);
+    # ->utf8 decodes the file's UTF-8 bytes into Perl characters, so a value
+    # like "café" round-trips to a single é (U+00E9) instead of its two raw
+    # bytes — otherwise _form_escape would re-encode them and double-escape.
+    JSON::PP->new->utf8->decode(scalar <$fh>);
 };
 
 # One binding per canonical helper id in the spec catalogue, bound to
@@ -99,6 +108,11 @@ my %bindings = (
     # and '' for present-but-empty, so the Perl backend matches JS exactly.
     search_params_get => sub { BarefootJS->search_params($_[0])->get($_[1]) },
 
+    # queryHref SSR builder (#2042): (base, include, key, value, …) → URL. The
+    # include flags arrive as JSON booleans (JSON::PP::Boolean, truthy/falsy
+    # under `next unless`); the helper form-encodes to match URLSearchParams.
+    query => sub { $bf->query(@_) },
+
     # 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`,

package/t/query.t

@@ -0,0 +1,49 @@
+use Test2::V0;
+use utf8;
+
+# BarefootJS->query — the `queryHref(base, { … })` URL-query builder helper
+# (#2042).
+#
+# The full CROSS-BACKEND behaviour (control flow + form-encoding parity with the
+# browser's URLSearchParams) is defined ONCE in the shared golden helper vectors
+# — packages/adapter-tests/helper-vectors/vectors.json, fn "query" — and run
+# here by t/helper_vectors.t and by the Go runtime's TestHelperVectors, so the
+# Perl and Go expectations can't drift apart.
+#
+# This file keeps a few representative cases for always-on coverage (the golden
+# file is monorepo-only, absent from the CPAN dist) plus the Perl-runtime-
+# SPECIFIC defensive behaviour the golden vectors can't express: an `undef`
+# value. JSON has no `undefined`, and a JSON `null` stringifies to "null" under
+# JS `String()`, so it can't be a shared vector; Perl coerces `undef` to '' and
+# omits the empty pair.
+
+use FindBin qw($Bin);
+use lib "$Bin/../lib";
+
+use BarefootJS;
+
+# `query` is a pure helper (no backend / controller), so a bare blessed stub is
+# enough — mirroring t/helper_vectors.t. Triples are (include, key, value).
+my $bf = bless {}, 'BarefootJS';
+
+# Representative control flow: a repeated key overwrites at its first position
+# (URLSearchParams.set), surrounding order preserved.
+is $bf->query('/blog', 1, 'sort', 'title', 1, 'tag', 'go', 1, 'sort', 'date'),
+    '/blog?sort=date&tag=go', 'order preserved, repeated key overwrites at first position';
+
+# Representative form-encoding: space → '+', '~' → %7E, '*' kept (URLSearchParams,
+# not Go's url.QueryEscape).
+is $bf->query('/s', 1, 't', 'a~b *c'), '/s?t=a%7Eb+*c', 'form-encode: ~ → %7E, * kept, space → +';
+
+# Representative array value: an array ref appends one pair per non-empty member
+# (#2048), skipping empties.
+is $bf->query('/list', 1, 'tag', ['a', '', 'b']), '/list?tag=a&tag=b',
+    'array value appends a pair per non-empty member';
+
+# Perl-specific: an `undef` value is coerced to '' and then omitted, without
+# disturbing the surrounding pairs.
+is $bf->query('/list', 1, 'tag', undef), '/list', 'undef value coerced to empty → omitted';
+is $bf->query('/list', 1, 'tag', undef, 1, 'keep', 'me'), '/list?keep=me',
+    'undef value dropped, surrounding pairs intact';
+
+done_testing;