@barefootjs/perl 0.17.0 → 0.18.0

package/lib/BarefootJS/DevReload.pm

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

package/lib/BarefootJS/Evaluator.pm

@@ -81,6 +81,16 @@ sub evaluate ($node, $env) {
         return _read_index(evaluate($node->{object}, $env), evaluate($node->{index}, $env));
     }
     if ($kind eq 'call') {
+        # Nested `.map(cb)` / `.filter(cb)` (#2094) — e.g. a `.flatMap(p =>
+        # p.tags.map(t => '#'+t))` projection body that itself contains a
+        # `.map`/`.filter` call. Checked BEFORE builtin-name resolution
+        # (the callee is a `member` node, never a bare/dotted builtin
+        # identifier, so the two can't collide). Mirrors Go's
+        # evalArrayCallbackCall / evalArrayCallback.
+        my ($method, $object_node, $arrow_node) = _array_callback_call($node);
+        if (defined $method) {
+            return _array_callback($method, $object_node, $arrow_node, $env);
+        }
         my $name = _builtin_name($node->{callee});
         return undef unless defined $name && $name ne '';
         my @args = map { evaluate($_, $env) } @{ $node->{args} // [] };
@@ -108,12 +118,128 @@ sub evaluate ($node, $env) {
         }
         return \%out;
     }
-
-    # arrow-fn / higher-order / array-method / unsupported: a callback body
+    if ($kind eq 'array-method' && ($node->{method} // '') eq 'includes'
+        && @{ $node->{args} // [] } == 1)
+    {
+        # `.includes(x)` (#2075) — the one `array-method` in the evaluator
+        # subset, shared between `Array.prototype.includes` (SameValueZero
+        # membership) and `String.prototype.includes` (substring search),
+        # matching the receiver-type dispatch the SSR template lowering does
+        # at runtime (`bf_includes` / `$bf->includes`). Mirrors the JS
+        # reference's `includes()` (eval-reference.ts).
+        my $obj    = evaluate($node->{object}, $env);
+        my $needle = evaluate($node->{args}[0], $env);
+        if (ref $obj eq 'ARRAY') {
+            for my $el (@$obj) {
+                return _bool(1) if _same_value_zero($el, $needle);
+            }
+            return _bool(0);
+        }
+        if (_is_string($obj)) {
+            return _bool(index($obj, _to_string($needle)) != -1);
+        }
+        # Any other receiver is not a JS `.includes` target — degrade to
+        # false rather than throwing, mirroring the reference.
+        return _bool(0);
+    }
+    if ($kind eq 'array-method' && ($node->{method} // '') eq 'join'
+        && @{ $node->{args} // [] } <= 1)
+    {
+        # `.join(sep?)` (#2094), a sibling of `.includes` above in the
+        # `array-method` node kind — needed for a composed case like
+        # `.flatMap(p => p.tags.map(...).join(' ')).join(', ')`. JS
+        # semantics: default separator is `,`; a `null`/`undefined`
+        # element joins as `''` (NOT the string "null"). Mirrors the Go
+        # evaluator's evalJoin.
+        my $obj  = evaluate($node->{object}, $env);
+        my $args = $node->{args} // [];
+        my $sep  = @$args == 1 ? _to_string(evaluate($args->[0], $env)) : ',';
+        return _join_array($obj, $sep);
+    }
+
+    # arrow-fn / higher-order / unsupported array-method: a callback body
     # containing these is refused upstream (BF101); never reached here.
     return undef;
 }
 
+# ---------------------------------------------------------------------------
+# Nested `.map` / `.filter` callback recognition (#2094) — the evaluator
+# widening that lets a callback body (already evaluated here for reduce /
+# sort / filter / find / …) itself contain a `.map(cb)` or `.filter(cb)`
+# call, e.g. the #1938 blog-showcase `.flatMap(p => p.tags.map(t => '#'+t))`
+# projection. Everything else nested (`.some`/`.find`/`.every`/`.sort`/
+# `.reduce`/`.flat`/`.flatMap`, standalone arrows) stays refused upstream —
+# only `.map`/`.filter` are recognized here, mirroring Go's
+# evalArrayCallbackCall / evalArrayCallback exactly.
+# ---------------------------------------------------------------------------
+
+# _array_callback_call($node): if $node (a `call` node) is a `.map(arrow)` /
+# `.filter(arrow)` call — i.e. its callee is an uncomputed `member` node
+# whose property is "map"/"filter", and its first argument is an `arrow`
+# node — returns `(method, object_node, arrow_node)`. Otherwise returns the
+# empty list (so `if (my (...) = _array_callback_call($node))` is false).
+sub _array_callback_call ($node) {
+    my $callee = $node->{callee};
+    return () unless ref $callee eq 'HASH' && ($callee->{kind} // '') eq 'member';
+    return () if $callee->{computed};
+    my $prop = $callee->{property} // '';
+    return () unless $prop eq 'map' || $prop eq 'filter';
+    my $args = $node->{args} // [];
+    return () unless @$args;
+    my $arrow = $args->[0];
+    return () unless ref $arrow eq 'HASH' && ($arrow->{kind} // '') eq 'arrow';
+    return ($prop, $callee->{object}, $arrow);
+}
+
+# _array_callback($method, $object_node, $arrow_node, $env): evaluate the
+# receiver (`$object_node`) against $env, then map/filter it through the
+# arrow's body. `params` in the decoded JSON is an array ref of plain
+# strings (e.g. `["t"]` or `["t","i"]`) — 1 param binds the element, 2
+# params bind (element, index). The child env is a COPY of the parent env
+# (never mutated in place across sibling iterations), with the param
+# name(s) bound per call — matches Go's per-call `inner` env copy.
+sub _array_callback ($method, $object_node, $arrow_node, $env) {
+    my $arr = evaluate($object_node, $env);
+    return undef unless ref $arr eq 'ARRAY';
+    my @params = @{ $arrow_node->{params} // [] };
+    my $body   = $arrow_node->{body};
+    my $call_cb = sub {
+        my ($item, $index) = @_;
+        my %inner = %$env;
+        $inner{ $params[0] } = $item  if @params >= 1;
+        $inner{ $params[1] } = $index if @params >= 2;
+        return evaluate($body, \%inner);
+    };
+    if ($method eq 'map') {
+        my @out;
+        my $i = 0;
+        for my $item (@$arr) {
+            push @out, $call_cb->($item, $i);
+            $i++;
+        }
+        return \@out;
+    }
+    # filter
+    my @out;
+    my $i = 0;
+    for my $item (@$arr) {
+        push @out, $item if _truthy($call_cb->($item, $i));
+        $i++;
+    }
+    return \@out;
+}
+
+# _join_array($obj, $sep): `Array.prototype.join` semantics — non-ARRAY
+# receiver -> '' (the evaluator's degrade-rather-than-die convention,
+# matching `.includes` above); a `null`/`undefined` (Perl `undef`) element
+# joins as '' (not the string "null"); every other element goes through
+# `_to_string` (JS `String(x)` — a JS boolean stringifies "true"/"false", a
+# number "42"/"NaN"/"Infinity", etc.). Mirrors Go's evalJoin.
+sub _join_array ($obj, $sep) {
+    return '' unless ref $obj eq 'ARRAY';
+    return join($sep, map { defined $_ ? _to_string($_) : '' } @$obj);
+}
+
 # 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) {
@@ -276,6 +402,19 @@ sub _strict_eq ($l, $r) {
     return 0;
 }
 
+# _same_value_zero: `Array.prototype.includes` membership test — `===`
+# except `NaN` equals itself (and +0/-0 are not distinguished, which the
+# JSON-decoded values here can't represent anyway). Reuses `_strict_eq`'s
+# type/value rules and only special-cases the two-NaN case that `_strict_eq`
+# (deliberately, for `===`) reports as unequal.
+sub _same_value_zero ($l, $r) {
+    if (_is_number($l) && _is_number($r)) {
+        my ($lf, $rf) = ($l + 0, $r + 0);
+        return 1 if $lf != $lf && $rf != $rf;    # NaN sameValueZero NaN
+    }
+    return _strict_eq($l, $r);
+}
+
 sub _unary ($op, $v) {
     return _bool(!_truthy($v)) if $op eq '!';
     return -_to_number($v) if $op eq '-';
@@ -539,6 +678,21 @@ sub flat_map ($items, $proj, $param, $base_env = undef) {
     return \@out;
 }
 
+# map_items — project each element through $proj (a pure ParsedExpr), keeping
+# each result as one element (no flatten): JS value-producing `.map(cb)`
+# (#2073). Named map_items (not `map`) so the Perl builtin stays unshadowed.
+# Mirrors Go's MapEval. $base_env is optional.
+sub map_items ($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;
+        push @out, evaluate($proj, \%env);
+    }
+    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
@@ -575,4 +729,9 @@ sub flat_map_json ($items, $proj_json, $param, $base_env = undef) {
     return flat_map($items, JSON::PP->new->decode($proj_json), $param, $base_env);
 }
 
+sub map_json ($items, $proj_json, $param, $base_env = undef) {
+    require JSON::PP;
+    return map_items($items, JSON::PP->new->decode($proj_json), $param, $base_env);
+}
+
 1;

package/lib/BarefootJS.pm

@@ -1,5 +1,5 @@
 package BarefootJS;
-our $VERSION = "0.16.0";
+our $VERSION = "0.17.1";
 use strict;
 use warnings;
 use utf8;
@@ -168,7 +168,11 @@ sub props_attr ($self) {
     return '' unless $props && %$props;
     # encode_json returns a character string (not bytes) for safe embedding
     # in templates (the Mojo backend uses Mojo::JSON::to_json).
-    my $json = $self->backend->encode_json($props);
+    # The JSON must then be attribute-escaped: a raw `'` inside a string
+    # value (e.g. a blog paragraph) terminates the single-quoted attribute
+    # and truncates the hydration payload. The browser entity-decodes the
+    # attribute value, so the client's JSON.parse sees the original text.
+    my $json = _html_escape($self->backend->encode_json($props));
     return qq{ bf-p='$json'};
 }
 
@@ -345,17 +349,19 @@ sub render_child ($self, $name, @args) {
 # it takes precedence over the manifest's `ssrDefaults` for that
 # child, allowing callers to mix manual overrides with auto-derived
 # defaults for siblings.
+#
+# Multi-component modules (#2132): a registry module exporting several
+# components from one file (`ui/toast/index.tsx` → ToastProvider, Toast,
+# ToastTitle, ...) compiles to one template PER component, listed in the
+# entry's `components` map (`{ ToastProvider => { markedTemplate,
+# ssrDefaults }, ... }`). Compiled parent templates invoke each one under
+# its snake_cased component name (`render_child('toast_provider')`), so a
+# renderer is registered per component. These run AFTER the directory-name
+# registration and win on collision — for `ui/toast/index` the key `toast`
+# must resolve to Toast's own template, not the module's first template
+# (ToastProvider), which is all the bare `markedTemplate` carries.
 sub register_components_from_manifest ($self, $manifest, %opts) {
     my $signal_inits = $opts{signal_init} // {};
-    my $parent_scope = $self->_scope_id;
-    # Weaken the parent capture so the child-renderer closures stored on
-    # `$self->_child_renderers` don't keep `$self` alive (the direct
-    # closure <-> parent cycle). The controller is reached through `$parent`
-    # at call time rather than captured strongly here, so the closures hold
-    # no strong reference to `$c` either — see the controller-cycle note in
-    # `new`. `$parent` is always live whenever a closure runs (the closure is
-    # stored on `$parent`, so `$parent` outlives every invocation).
-    weaken(my $parent = $self);
 
     for my $entry_name (keys %$manifest) {
         # `__barefoot__` is the runtime entry, not a component.
@@ -365,70 +371,119 @@ sub register_components_from_manifest ($self, $manifest, %opts) {
         # render target rather than a child.
         next unless $entry_name =~ m{^ui/([^/]+)/index$};
         my $slot_key = $1;
-        my $marked = $manifest->{$entry_name}{markedTemplate} // '';
-        next unless $marked;
-        # `templates/ui/button/index.html.ep` → `ui/button/index`
-        my $template_name = $marked;
-        $template_name =~ s{^templates/}{};
-        $template_name =~ s{\.html\.ep$}{};
-
-        my $signal_init = $signal_inits->{$slot_key};
-        my $manifest_defaults = $manifest->{$entry_name}{ssrDefaults};
-        $self->register_child_renderer($slot_key, sub {
-            # `$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
-            # `$parent` at call time — never captured strongly — so the
-            # closure adds no edge to the per-request reference cycle.
-            my $child_bf = BarefootJS->new($parent->c, { backend => $parent->backend });
-            my $slot_id = delete $props->{_bf_slot};
-            # JSX `key` (a reserved prop) → data-key on the child's scope root
-            # for keyed-loop reconciliation (see `data_key_attr`).
-            my $data_key = delete $props->{key};
-            $child_bf->_data_key($data_key) if defined $data_key;
-            $child_bf->_scope_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($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);
-
-            my %extra;
-            if ($signal_init) {
-                %extra = $signal_init->($props);
-            } elsif ($manifest_defaults) {
-                %extra = _derive_stash_from_defaults($manifest_defaults, $props);
-            }
+        my $entry = $manifest->{$entry_name};
+
+        # Directory-name registration — the pre-`components` convention,
+        # kept so manifests from older builds (no `components` map) still
+        # resolve single-component modules like `button`.
+        $self->_register_manifest_child(
+            $slot_key, $entry->{markedTemplate},
+            $signal_inits->{$slot_key}, $entry->{ssrDefaults},
+        );
 
-            # Render the child template with $child_bf bound as the active
-            # instance for the nested render. The backend owns the
-            # engine-specific binding + restore (stash juggle for Mojo).
-            my $html = $parent->backend->render_named(
-                $template_name, $child_bf, { %$props, %extra },
+        # Per-component registrations (#2132), keyed by the snake_cased
+        # component name the compiled templates actually call.
+        my $components = $entry->{components};
+        next unless ref($components) eq 'HASH';
+        for my $component_name (sort keys %$components) {
+            my $component = $components->{$component_name};
+            next unless ref($component) eq 'HASH';
+            my $component_key = _snake_case($component_name);
+            $self->_register_manifest_child(
+                $component_key, $component->{markedTemplate},
+                $signal_inits->{$component_key}, $component->{ssrDefaults},
             );
-            chomp $html;
-            return $html;
-        });
+        }
     }
 }
 
+# PascalCase → snake_case, mirroring the Mojo adapter's `toTemplateName`
+# (prefix every uppercase letter with `_`, lowercase the whole string,
+# strip the leading `_`): `ToastProvider` → `toast_provider`.
+sub _snake_case ($name) {
+    my $s = $name;
+    $s =~ s/([A-Z])/_$1/g;
+    $s = CORE::lc $s;
+    $s =~ s/^_//;
+    return $s;
+}
+
+# Register one manifest-driven child renderer: `$slot_key` becomes the
+# `render_child` name, `$marked` locates the template, and `$signal_init`
+# / `$manifest_defaults` seed the child's template vars (see
+# `register_components_from_manifest` for the contract).
+sub _register_manifest_child ($self, $slot_key, $marked, $signal_init, $manifest_defaults) {
+    $marked //= '';
+    return unless $marked;
+    my $parent_scope = $self->_scope_id;
+    # Weaken the parent capture so the child-renderer closures stored on
+    # `$self->_child_renderers` don't keep `$self` alive (the direct
+    # closure <-> parent cycle). The controller is reached through `$parent`
+    # at call time rather than captured strongly here, so the closures hold
+    # no strong reference to `$c` either — see the controller-cycle note in
+    # `new`. `$parent` is always live whenever a closure runs (the closure is
+    # stored on `$parent`, so `$parent` outlives every invocation).
+    weaken(my $parent = $self);
+
+    # `templates/ui/button/index.html.ep` → `ui/button/index`
+    my $template_name = $marked;
+    $template_name =~ s{^templates/}{};
+    $template_name =~ s{\.html\.ep$}{};
+
+    $self->register_child_renderer($slot_key, sub {
+        # `$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
+        # `$parent` at call time — never captured strongly — so the
+        # closure adds no edge to the per-request reference cycle.
+        my $child_bf = BarefootJS->new($parent->c, { backend => $parent->backend });
+        my $slot_id = delete $props->{_bf_slot};
+        # JSX `key` (a reserved prop) → data-key on the child's scope root
+        # for keyed-loop reconciliation (see `data_key_attr`).
+        my $data_key = delete $props->{key};
+        $child_bf->_data_key($data_key) if defined $data_key;
+        $child_bf->_scope_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($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);
+
+        my %extra;
+        if ($signal_init) {
+            %extra = $signal_init->($props);
+        } elsif ($manifest_defaults) {
+            %extra = _derive_stash_from_defaults($manifest_defaults, $props);
+        }
+
+        # Render the child template with $child_bf bound as the active
+        # instance for the nested render. The backend owns the
+        # engine-specific binding + restore (stash juggle for Mojo).
+        my $html = $parent->backend->render_named(
+            $template_name, $child_bf, { %$props, %extra },
+        );
+        chomp $html;
+        return $html;
+    });
+}
+
 # Derive template-stash kvs from a manifest entry's `ssrDefaults`
 # section. Each entry shape:
 #   { value => <static-fallback>, propName => <prop>, isRestProps => bool }
@@ -581,8 +636,14 @@ sub round ($self, $value) {
 # receiver shapes apart without TS type inference, so both lower to
 # the same IR node (`array-method` / method `includes`). This helper
 # dispatches at the Perl level via `ref()`:
-#   - ARRAY ref:  scan elements with `eq`; one defined-vs-undef
-#                 hop matches JS's `===` for null/undefined.
+#   - ARRAY ref:  scan elements with `BarefootJS::Evaluator::_same_value_zero`,
+#                 matching `Array.prototype.includes`'s SameValueZero
+#                 semantics (no cross-type coercion, e.g. `[2].includes("2")`
+#                 is false; NaN matches NaN) — the same algorithm the
+#                 evaluator's serialized-callback path already uses for
+#                 `.includes`, so both positions agree. This used to be a
+#                 stringy `eq` scan, which coerced numbers to strings
+#                 (`[2].includes("2")` was true) and diverged from JS.
 #   - scalar:     `index($recv, $sub) != -1`, with both args
 #                 coerced through `// ''` so an undef receiver /
 #                 needle doesn't trip Perl's substr warning.
@@ -593,11 +654,7 @@ sub round ($self, $value) {
 sub includes ($self, $recv, $elem) {
     if (ref($recv) eq 'ARRAY') {
         for my $item (@$recv) {
-            if (!defined $item) {
-                return 1 if !defined $elem;
-                next;
-            }
-            return 1 if defined $elem && $item eq $elem;
+            return 1 if BarefootJS::Evaluator::_same_value_zero($item, $elem);
         }
         return 0;
     }
@@ -805,6 +862,59 @@ sub flat ($self, $recv, $depth = 1) {
     return \@out;
 }
 
+# `Array.prototype.flat(depth)` with a DYNAMIC depth (#2094) — the depth is
+# itself an arbitrary runtime value (e.g. a prop), not a compile-time literal,
+# so it must be coerced with JS's `ToIntegerOrInfinity` before delegating to
+# `flat` above: truncate toward zero; negative -> 0; NaN / non-numeric -> 0;
+# +Infinity or a huge finite value -> flatten fully.
+#
+# Deliberately a SEPARATE entry point from `flat`, not a smarter version of
+# it: the literal-depth path's `-1` argument is a compile-time SENTINEL baked
+# into the template source, meaning "the source literally said `Infinity`". A
+# genuinely dynamic depth that happens to evaluate to `-1` at render time
+# means the OPPOSITE in real JS (`[1,[2]].flat(-1)` never recurses — same as
+# `.flat(0)`). Since both paths would otherwise hand the same literal-looking
+# argument to one shared function, that function couldn't tell which case
+# it's in — so the two stay separate. Mirrors Go's `FlatDynamicDepth` /
+# `coerceFlatDepth` in bf.go.
+sub flat_dynamic ($self, $recv, $depth) {
+    return $self->flat($recv, _coerce_flat_depth($depth));
+}
+
+# _coerce_flat_depth: JS `ToIntegerOrInfinity` for a dynamic `.flat(depth)`
+# argument, collapsed to `flat`'s int contract (`-1` == flatten fully).
+#
+# Perl's scalar type system blurs string/number duality, so `looks_like_number`
+# (already the codebase's ToNumber-style coercion check, see BarefootJS::
+# Evaluator's `_to_number`) is reused here rather than inventing a new
+# convention. `looks_like_number` on this Perl (5.38) already recognises the
+# strings "Infinity" / "-Infinity" / "NaN" as numeric (verified empirically:
+# `perl -MScalar::Util=looks_like_number -e 'print looks_like_number("Infinity")'`
+# prints 1), and `$str + 0` on those strings yields the corresponding Perl
+# non-finite double, so no extra string special-casing is needed here.
+sub _coerce_flat_depth ($depth) {
+    return 0 unless defined $depth;
+    my $f;
+    if (ref($depth) eq 'JSON::PP::Boolean') {
+        $f = $depth ? 1 : 0;
+    }
+    elsif (!ref($depth) && looks_like_number($depth)) {
+        $f = $depth + 0;
+    }
+    else {
+        # undef handled above; anything else non-numeric (a plain string
+        # that isn't a number, a HASH/ARRAY ref, ...) coerces via NaN.
+        return 0;
+    }
+    return 0 if $f != $f;              # NaN
+    return -1 if $f == 9**9**9;        # +Infinity -> flatten fully sentinel
+    return 0  if $f == -(9**9**9);     # -Infinity -> 0
+    my $trunc = int($f);               # Perl's int() truncates toward zero
+    return 0  if $trunc < 0;
+    return -1 if $trunc > 1_000_000;   # huge finite ~= flatten fully
+    return $trunc;
+}
+
 # `Array.prototype.flatMap(fn)` value-returning field projection
 # (#1448 Tier C) — map each element through a self / field projection,
 # then flatten one level. `field` reads a HASH-ref key (the raw JS prop
@@ -1180,6 +1290,13 @@ sub flat_map_eval ($self, $recv, $proj_json, $param, $base_env = {}) {
     return BarefootJS::Evaluator::flat_map_json($recv, $proj_json, $param, $base_env);
 }
 
+# Value-producing `.map(cb)` (#2073): project each element through the
+# serialized projection body, one result per element (no flatten). Composes
+# through the array-method chain (`.map(cb).join(' ')`).
+sub map_eval ($self, $recv, $proj_json, $param, $base_env = {}) {
+    return BarefootJS::Evaluator::map_json($recv, $proj_json, $param, $base_env);
+}
+
 sub sort ($self, $recv, $opts = {}) {
     return [] unless ref($recv) eq 'ARRAY';
 
@@ -1412,6 +1529,25 @@ sub _style_to_css ($value) {
     return @parts ? CORE::join(';', @parts) : undef;
 }
 
+
+# Object-rest residual for a `.map()` destructure binding
+# (`{ id, ...rest } => …`, #2087 Phase B): returns a NEW hashref holding
+# every key of `$bag` except those named in `$keys` (an ARRAY ref of key
+# strings). This is plain JS destructure semantics (`const { id, ...rest }
+# = item`) — unlike `spread_attrs` below, there's no event-handler /
+# `children` filtering or key remapping here, because the residual is a
+# *value* the template may read fields off of (`$rest->{flag}`) or later
+# forward wholesale to `spread_attrs` (`{...rest}` on an element) — either
+# consumer applies its own rules downstream. A non-hashref `$bag` returns
+# an empty hashref rather than dying, so this stays safe as a `my` local
+# initializer even off unexpected/absent data (same defensive contract as
+# `spread_attrs`'s "no bag → nothing").
+sub omit ($self, $bag, $keys) {
+    return {} unless defined $bag && ref($bag) eq 'HASH';
+    my %exclude = map { $_ => 1 } @$keys;
+    return { map { $_ => $bag->{$_} } grep { !$exclude{$_} } keys %$bag };
+}
+
 sub spread_attrs ($self, $bag) {
     return '' unless defined $bag && ref($bag) eq 'HASH';
     my @parts;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/perl",
-  "version": "0.17.0",
+  "version": "0.18.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

@@ -16,7 +16,7 @@ use BarefootJS::Evaluator;
 # 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'
+    $FindBin::Bin, '..', '..', 'adapter-tests', 'vectors', 'eval-vectors.json'
 );
 plan skip_all => 'eval vectors not available outside the monorepo checkout'
     unless -e $vectors_path;

package/t/evaluator.t

@@ -20,6 +20,11 @@ sub ncall_math {
     return { kind => 'call', callee => nmem(nid('Math'), $fn), args => [$arg] };
 }
 
+sub nincludes {
+    my ($object, $needle) = @_;
+    return { kind => 'array-method', method => 'includes', object => $object, args => [$needle] };
+}
+
 # A plain false for the `computed` flag; the evaluator only checks truthiness.
 sub JSON_false { return 0 }
 
@@ -134,6 +139,40 @@ subtest 'boolean-valued ops return JS booleans, not 1/0' => sub {
     ok(!defined $len, '(123).length is null, not 3');
 };
 
+# `.includes` (#2075) is the one `array-method` in the evaluator subset,
+# dispatching on the receiver type like the SSR template lowering does at
+# runtime (`bf_includes` / `$bf->includes`): array → SameValueZero membership
+# (the same value rules as `===`, so a numeric 2 does NOT match the string
+# "2"); string → substring search; anything else degrades to false rather
+# than dying.
+subtest 'array-method includes' => sub {
+    my $hit = BarefootJS::Evaluator::evaluate(nincludes(nid('tags'), nstr('go')), { tags => [ 'perl', 'go' ] });
+    ok(JSON::PP::is_bool($hit), 'array hit is a JS boolean');
+    ok($hit, 'array .includes: hit');
+
+    my $miss = BarefootJS::Evaluator::evaluate(nincludes(nid('tags'), nstr('rust')), { tags => [ 'perl', 'go' ] });
+    ok(JSON::PP::is_bool($miss), 'array miss is a JS boolean');
+    ok(!$miss, 'array .includes: miss');
+
+    # SameValueZero, not loose equality: the numeric element 2 matches the
+    # numeric needle 2, but the string needle "2" (a different JS type) does
+    # not — mirroring `===`'s type-sensitivity.
+    my $num_hit = BarefootJS::Evaluator::evaluate(nincludes(nid('nums'), { kind => 'literal', value => 2 }), { nums => [ 1, 2, 3 ] });
+    ok($num_hit, 'array .includes: numeric element hit');
+    my $num_vs_string = BarefootJS::Evaluator::evaluate(nincludes(nid('nums'), nstr('2')), { nums => [ 1, 2, 3 ] });
+    ok(!$num_vs_string, 'array .includes: numeric element does not match a string needle');
+
+    my $sub = BarefootJS::Evaluator::evaluate(nincludes(nid('name'), nstr('ar')), { name => 'bare' });
+    ok($sub, 'string .includes: substring hit');
+
+    # A non-array, non-string receiver (number, null, object) is not a JS
+    # `.includes` target; the evaluator degrades to false rather than dying.
+    my $scalar_recv = BarefootJS::Evaluator::evaluate(nincludes(nid('n'), { kind => 'literal', value => 1 }), { n => 42 });
+    ok(!$scalar_recv, 'non-collection receiver (number) is false, not a die');
+    my $null_recv = BarefootJS::Evaluator::evaluate(nincludes(nid('n'), nstr('x')), { n => undef });
+    ok(!$null_recv, 'non-collection receiver (null) is false, not a die');
+};
+
 # 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 {
@@ -262,4 +301,121 @@ subtest 'flat_map projects + flattens one level' => sub {
     is_deeply($fj, [ 'a', 'b', 'c' ], 'flat_map_json decodes + projects');
 };
 
+# #2073: map_items is the value-producing `.map(cb)` — one result per element,
+# NO flatten (an array-valued projection stays one element). Mirrors the Go
+# TestMapEval shapes.
+subtest 'map_items projects one result per element (no flatten)' => sub {
+    my $tmpl = {
+        kind  => 'template-literal',
+        parts => [
+            { type => 'string',     value => '#' },
+            { type => 'expression', expr  => nid('t') },
+        ],
+    };
+    is_deeply(BarefootJS::Evaluator::map_items([ 'perl', 'go' ], $tmpl, 't'),
+        [ '#perl', '#go' ], 'template-literal projection maps each element');
+
+    my @users = ({ name => 'Ada' }, { name => 'Grace' });
+    my $field = nmem(nid('u'), 'name');
+    is_deeply(BarefootJS::Evaluator::map_items(\@users, $field, 'u'),
+        [ 'Ada', 'Grace' ], 'field projection maps each element');
+
+    my @rows = ({ tags => [ 'a', 'b' ] });
+    is_deeply(BarefootJS::Evaluator::map_items(\@rows, nmem(nid('i'), 'tags'), 'i'),
+        [ [ 'a', 'b' ] ], 'array-valued projection stays ONE element (no flatten)');
+
+    # JSON seam.
+    my $mj = BarefootJS::Evaluator::map_json(\@users,
+        JSON::PP->new->encode($field), 'u');
+    is_deeply($mj, [ 'Ada', 'Grace' ], 'map_json decodes + projects');
+};
+
+# #2094: the evaluator widening lets a callback body (already evaluated here
+# for reduce/sort/filter/find/…) itself contain a nested `.map(cb)` /
+# `.filter(cb)` call — e.g. the #1938 blog-showcase
+# `.flatMap(p => p.tags.map(t => '#'+t))` projection body. Mirrors the Go
+# TestArrayCallback shapes.
+subtest 'nested .map / .filter callback calls (#2094)' => sub {
+    # item.tags.map(t => '#' + t)
+    my $map_call = {
+        kind    => 'call',
+        callee  => nmem(nmem(nid('item'), 'tags'), 'map'),
+        args    => [ {
+            kind   => 'arrow',
+            params => ['t'],
+            body   => nbin('+', nstr('#'), nid('t')),
+        } ],
+    };
+    is_deeply(
+        BarefootJS::Evaluator::evaluate($map_call, { item => { tags => [ 'go', 'perl' ] } }),
+        [ '#go', '#perl' ],
+        'nested .map: string-prefix projection',
+    );
+
+    # item.tags.filter(t => t.active)
+    my $filter_call = {
+        kind   => 'call',
+        callee => nmem(nmem(nid('item'), 'tags'), 'filter'),
+        args   => [ {
+            kind   => 'arrow',
+            params => ['t'],
+            body   => nmem(nid('t'), 'active'),
+        } ],
+    };
+    my $filtered = BarefootJS::Evaluator::evaluate($filter_call, {
+        item => { tags => [ { active => JSON::PP::true, n => 1 }, { active => JSON::PP::false, n => 2 } ] },
+    });
+    is_deeply([ map { $_->{n} } @$filtered ], [1], 'nested .filter: keeps only active');
+
+    # 2-param arrow (value, index): item.tags.map((t, i) => t.n + i)
+    my $indexed = {
+        kind   => 'call',
+        callee => nmem(nmem(nid('item'), 'tags'), 'map'),
+        args   => [ {
+            kind   => 'arrow',
+            params => ['t', 'i'],
+            body   => nbin('+', nmem(nid('t'), 'n'), nid('i')),
+        } ],
+    };
+    is_deeply(
+        BarefootJS::Evaluator::evaluate($indexed, { item => { tags => [ { n => 10 }, { n => 20 }, { n => 30 } ] } }),
+        [ 10, 21, 32 ],
+        'nested .map: 2-param arrow does not leak the index across sibling calls',
+    );
+
+    # .filter(...).length > 0 — the doc/#2038 motivating composed shape.
+    my $len_gt = {
+        kind => 'binary', op => '>',
+        left => nmem($filter_call, 'length'),
+        right => { kind => 'literal', value => 0, literalType => 'number' },
+    };
+    ok(BarefootJS::Evaluator::evaluate($len_gt, {
+        item => { tags => [ { active => JSON::PP::true }, { active => JSON::PP::false } ] },
+    }), '.filter(...).length > 0 composes: at least one active');
+    ok(!BarefootJS::Evaluator::evaluate($len_gt, {
+        item => { tags => [ { active => JSON::PP::false }, { active => JSON::PP::false } ] },
+    }), '.filter(...).length > 0 composes: none active is falsy');
+};
+
+# #2094: `.join(sep?)` — a sibling `array-method` alongside `.includes`.
+subtest 'array-method join (#2094)' => sub {
+    my $tags = nmem(nid('item'), 'tags');
+    my $join_default = { kind => 'array-method', method => 'join', object => $tags, args => [] };
+    is(BarefootJS::Evaluator::evaluate($join_default, { item => { tags => [ 'a', 'b' ] } }),
+        'a,b', 'no separator defaults to a comma');
+
+    my $join_custom = {
+        kind => 'array-method', method => 'join', object => $tags,
+        args => [ nstr('-') ],
+    };
+    is(BarefootJS::Evaluator::evaluate($join_custom, { item => { tags => [ 'a', 'b', 'c' ] } }),
+        'a-b-c', 'custom separator');
+
+    is(BarefootJS::Evaluator::evaluate($join_custom, { item => { tags => [] } }),
+        '', 'empty array joins to the empty string');
+
+    is(BarefootJS::Evaluator::evaluate($join_default, { item => { tags => [ 'a', undef, 'b' ] } }),
+        'a,,b', 'a null/undef element joins as empty, not the string "null"');
+};
+
 done_testing;

package/t/helper_vectors.t

@@ -35,7 +35,7 @@ my $bf = bless { c => undef, config => {}, backend => PureBackend->new }, 'Baref
 # 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'
+    $FindBin::Bin, '..', '..', 'adapter-tests', 'vectors', 'vectors.json'
 );
 plan skip_all => 'golden vectors not available outside the monorepo checkout'
     unless -e $vectors_path;
@@ -49,6 +49,23 @@ my $doc = do {
     JSON::PP->new->utf8->decode(scalar <$fh>);
 };
 
+# Per-backend status declarations (spec/template-helpers.md "Adapter
+# status model") live in t/vector-divergences.json, package-local to this
+# adapter — the spec stays backend-neutral. This harness enforces them: a
+# pinned case that starts matching JS fails as stale, and a key that
+# matches no vector case fails as dead (see the two checks below).
+my $divergences_path = File::Spec->catfile($FindBin::Bin, 'vector-divergences.json');
+die "divergences file not found: $divergences_path (it is package-local and must always be present)"
+    unless -e $divergences_path;
+
+my $divergences_doc = do {
+    open my $fh, '<:raw', $divergences_path or die "open $divergences_path: $!";
+    local $/;
+    JSON::PP->new->utf8->decode(scalar <$fh>);
+};
+my %DIVERGENCES = %{ $divergences_doc->{divergences} };
+my %UNSUPPORTED = %{ $divergences_doc->{unsupported} };
+
 # 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
@@ -97,6 +114,7 @@ my %bindings = (
     slice   => sub { $bf->slice($_[0], $_[1], $_[2]) },
     reverse => sub { $bf->reverse($_[0]) },
     flat    => sub { $bf->flat(@_) },
+    flat_dynamic => sub { $bf->flat_dynamic(@_) },
     join    => sub { $bf->join(@_) },
     # Array literals are native arrayrefs on the Perl backends.
     arr => sub { [@_] },
@@ -176,81 +194,6 @@ sub _field_eq_pred {
         : 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)};
@@ -271,7 +214,7 @@ for my $case (@{ $doc->{cases} }) {
     if (my $d = $DIVERGENCES{$key}) {
         $seen_declarations{$key} = 1;
         my $label = "$key (declared divergence: $d->{reason})";
-        if ($d->{dies}) {
+        if ($d->{throws}) {
             ok($err, $label) or diag("expected the call to die, got: " . explain_value($got));
             next;
         }
@@ -284,10 +227,10 @@ for my $case (@{ $doc->{cases} }) {
             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}));
+        die "divergence '$key' has neither throws nor expect — malformed perl.json entry"
+            unless exists $d->{expect};
+        ok(_match($got, $d->{expect}), $label)
+            or diag('got ' . explain_value($got) . ', pinned ' . explain_value($d->{expect}));
         next;
     }
 
@@ -356,21 +299,6 @@ sub _match {
     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;

package/t/manifest_components.t

@@ -0,0 +1,170 @@
+use strict;
+use warnings;
+use utf8;
+
+use Test2::V0;
+
+use FindBin qw($Bin);
+use lib "$Bin/../lib";
+
+use BarefootJS;
+
+# Multi-component registry modules (#2132).
+#
+# A registry module exporting several components from one file
+# (`ui/toast/index.tsx` → ToastProvider / Toast / ToastTitle) compiles to
+# one template per component, and `bf build` lists them in the manifest
+# entry's `components` map. Compiled parent templates call each one under
+# its snake_cased component name (`render_child('toast_provider')`), so
+# `register_components_from_manifest` must register one child renderer per
+# component — the old dir-name-only registration left every sub-component
+# unresolvable and the render died with "No renderer registered".
+
+# Backend stub that records which template each nested render resolved to,
+# along with the vars it received.
+{
+    package RecordingBackend;
+    sub new { bless { calls => [] }, shift }
+    sub calls       { $_[0]{calls} }
+    sub encode_json { '{}' }
+    sub mark_raw    { $_[1] }
+    sub materialize { $_[1] }
+    sub render_named {
+        my ($self, $template_name, $child_bf, $vars) = @_;
+        push @{ $self->{calls} }, { template => $template_name, vars => $vars };
+        return "<rendered:$template_name>";
+    }
+}
+
+sub new_bf {
+    my $backend = RecordingBackend->new;
+    my $bf = BarefootJS->new(undef, { backend => $backend });
+    $bf->_scope_id('Root_test');
+    return ($bf, $backend);
+}
+
+# The manifest shape `bf build` emits for the toast module (see the emitter
+# pin in packages/cli/src/__tests__/build-manifest-components.test.ts).
+my $TOAST_ENTRY = {
+    markedTemplate => 'templates/ui/toast/ToastProvider.html.ep',
+    clientJs       => 'client/ui/toast/index.client.js',
+    ssrDefaults    => { children => { propName => 'children', value => undef } },
+    components     => {
+        ToastProvider => {
+            markedTemplate => 'templates/ui/toast/ToastProvider.html.ep',
+            ssrDefaults    => { children => { propName => 'children', value => undef } },
+        },
+        Toast => {
+            markedTemplate => 'templates/ui/toast/Toast.html.ep',
+            ssrDefaults    => {
+                open     => { propName => 'open', value => 0 },
+                children => { propName => 'children', value => undef },
+            },
+        },
+        ToastTitle => {
+            markedTemplate => 'templates/ui/toast/ToastTitle.html.ep',
+            ssrDefaults    => { children => { propName => 'children', value => undef } },
+        },
+    },
+};
+
+subtest 'each exported component gets a renderer under its snake_case name' => sub {
+    my ($bf, $backend) = new_bf();
+    $bf->register_components_from_manifest({ 'ui/toast/index' => $TOAST_ENTRY });
+
+    for my $case (
+        [ toast_provider => 'ui/toast/ToastProvider' ],
+        [ toast          => 'ui/toast/Toast' ],
+        [ toast_title    => 'ui/toast/ToastTitle' ],
+    ) {
+        my ($slot_key, $template) = @$case;
+        my $html = $bf->render_child($slot_key);
+        is $html, "<rendered:$template>",
+            "render_child('$slot_key') renders $template";
+    }
+};
+
+subtest 'the dir-name key resolves to the COMPONENT template, not the module primary' => sub {
+    # `ui/toast/index`'s dir key is `toast`, which collides with
+    # snake_case('Toast'). The per-component registration must win: without
+    # it, `render_child('toast')` renders the module's FIRST template
+    # (ToastProvider) — the wrong markup entirely.
+    my ($bf, $backend) = new_bf();
+    $bf->register_components_from_manifest({ 'ui/toast/index' => $TOAST_ENTRY });
+
+    $bf->render_child('toast');
+    is $backend->calls->[-1]{template}, 'ui/toast/Toast',
+        'toast maps to Toast.html.ep (not ToastProvider.html.ep)';
+};
+
+subtest 'per-component ssrDefaults seed the child vars' => sub {
+    my ($bf, $backend) = new_bf();
+    $bf->register_components_from_manifest({ 'ui/toast/index' => $TOAST_ENTRY });
+
+    # No caller prop → Toast's own static default.
+    $bf->render_child('toast');
+    is $backend->calls->[-1]{vars}{open}, 0,
+        'omitted prop falls back to the component default';
+
+    # Caller-supplied prop wins.
+    $bf->render_child('toast', open => 1);
+    is $backend->calls->[-1]{vars}{open}, 1, 'caller prop overrides the default';
+};
+
+subtest 'signal_init override applies per component key' => sub {
+    my ($bf, $backend) = new_bf();
+    $bf->register_components_from_manifest(
+        { 'ui/toast/index' => $TOAST_ENTRY },
+        signal_init => { toast => sub { (open => 'forced') } },
+    );
+
+    $bf->render_child('toast');
+    is $backend->calls->[-1]{vars}{open}, 'forced',
+        'signal_init keyed by the snake_case component name wins over ssrDefaults';
+
+    $bf->render_child('toast_title');
+    is $backend->calls->[-1]{template}, 'ui/toast/ToastTitle',
+        'sibling components without an override still render';
+};
+
+subtest 'manifests without a components map keep the dir-name registration' => sub {
+    # Older builds emit no `components` map; the single-component
+    # convention (dir name == snake_cased component name) must keep working.
+    my ($bf, $backend) = new_bf();
+    $bf->register_components_from_manifest({
+        'ui/button/index' => {
+            markedTemplate => 'templates/ui/button/index.html.ep',
+            ssrDefaults    => { variant => { propName => 'variant', value => 'default' } },
+        },
+    });
+
+    my $html = $bf->render_child('button');
+    is $html, '<rendered:ui/button/index>', 'dir-name key still renders';
+    is $backend->calls->[-1]{vars}{variant}, 'default', 'entry ssrDefaults still seed';
+};
+
+subtest 'a components row without a markedTemplate is skipped, siblings survive' => sub {
+    my ($bf, $backend) = new_bf();
+    my $entry = {
+        %$TOAST_ENTRY,
+        components => {
+            %{ $TOAST_ENTRY->{components} },
+            Broken => {},    # no markedTemplate
+        },
+    };
+    $bf->register_components_from_manifest({ 'ui/toast/index' => $entry });
+
+    like dies { $bf->render_child('broken') }, qr/No renderer registered/,
+        'template-less row registers nothing';
+    is $bf->render_child('toast_title'), '<rendered:ui/toast/ToastTitle>',
+        'sibling components still registered';
+};
+
+subtest '_snake_case mirrors the Mojo adapter toTemplateName' => sub {
+    is BarefootJS::_snake_case('Toast'),         'toast',          'single word';
+    is BarefootJS::_snake_case('ToastProvider'), 'toast_provider', 'two words';
+    is BarefootJS::_snake_case('DropdownMenu'),  'dropdown_menu',  'kebab-dir module component';
+    is BarefootJS::_snake_case('InputOTP'),      'input_o_t_p',    'acronym splits per capital';
+};
+
+done_testing;

package/t/omit.t

@@ -0,0 +1,61 @@
+use Test2::V0;
+
+# omit — object-rest residual runtime helper for a `.map()` destructure
+# binding (`{ id, ...rest } => …`, #2087 Phase B). Both the Mojo and Xslate
+# template adapters lower an object-rest binding to `bf->omit($parent,
+# [...excluded keys...])` / `$bf.omit($parent, [...])` so the residual is a
+# TRUE hashref (not the whole item aliased) — `rest.flag` and `{...rest}`
+# both read from the same real value. See packages/adapter-perl/lib/BarefootJS.pm.
+
+use FindBin qw($Bin);
+use lib "$Bin/../lib";
+
+use BarefootJS;
+
+# Minimal pure-Perl backend: `omit` never reaches the backend (no
+# mark_raw / escaping — it returns a plain hashref, not markup).
+{
+    package PureBackend;
+    sub new { bless {}, shift }
+}
+
+my $bf = bless { c => undef, config => {}, backend => PureBackend->new }, 'BarefootJS';
+
+subtest 'basic shapes' => sub {
+    is $bf->omit(undef, []), {}, 'undef bag -> empty hashref';
+    is $bf->omit('not a hash', []), {}, 'non-hash scalar -> empty hashref';
+    is $bf->omit({}, []), {}, 'empty bag -> empty hashref';
+    is $bf->omit({ id => 'a', title => 'b' }, []),
+       { id => 'a', title => 'b' },
+       'no excluded keys -> full copy';
+};
+
+subtest 'excludes named keys' => sub {
+    is $bf->omit({ id => 't1', title => 'one', flag => 'a' }, ['id', 'title']),
+       { flag => 'a' },
+       'excludes the destructured sibling keys, keeps the rest';
+    is $bf->omit({ id => 't1' }, ['id', 'title']),
+       {},
+       'excluding a key absent from the bag is a no-op for that key';
+};
+
+subtest 'non-identifier keys (rest-spread-onto-element shape)' => sub {
+    # Mirrors the `rest-destructure-object-spread-in-map` fixture:
+    # `{ id, title, ...rest }` with a hyphenated sibling key
+    # (`'data-priority'`) surviving into the residual untouched.
+    is $bf->omit(
+        { id => 't1', title => 'one', 'data-priority' => 'high', tag => 'urgent' },
+        ['id', 'title'],
+    ),
+       { 'data-priority' => 'high', tag => 'urgent' },
+       'non-identifier keys pass through the residual unchanged';
+};
+
+subtest 'returns a new hashref (no aliasing)' => sub {
+    my $bag = { id => 'a', flag => 'x' };
+    my $rest = $bf->omit($bag, ['id']);
+    $rest->{flag} = 'mutated';
+    is $bag->{flag}, 'x', 'mutating the residual does not affect the source bag';
+};
+
+done_testing;

package/t/props_attr.t

@@ -0,0 +1,44 @@
+use Test2::V0;
+
+# 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.
+
+use FindBin qw($Bin);
+use lib "$Bin/../lib";
+
+use BarefootJS;
+use JSON::PP ();
+
+{
+    package PropsAttrStubBackend;
+    sub new         { bless {}, shift }
+    sub encode_json { JSON::PP->new->canonical->encode($_[1]) }
+}
+
+sub bf_with {
+    my ($props) = @_;
+    my $bf = BarefootJS->new(undef, { backend => PropsAttrStubBackend->new });
+    $bf->_props($props) if $props;
+    return $bf;
+}
+
+is bf_with(undef)->props_attr, '', 'no props emits nothing';
+is bf_with({})->props_attr,    '', 'empty props emits nothing';
+
+my $attr = bf_with({ note => q{it's <b> & co} })->props_attr;
+is $attr, q{ bf-p='{&#34;note&#34;:&#34;it&#39;s &lt;b&gt; &amp; co&#34;}'},
+    'JSON is attribute-escaped';
+
+my ($value) = $attr =~ /bf-p='([^']*)'/;
+my %ent = ('&#34;' => '"', '&#39;' => "'", '&lt;' => '<', '&gt;' => '>', '&amp;' => '&');
+(my $decoded = $value) =~ s/(&#34;|&#39;|&lt;|&gt;|&amp;)/$ent{$1}/g;
+# Assign first: `is JSON::PP->...` parses as indirect-object notation.
+my $parsed = JSON::PP->new->decode($decoded);
+is $parsed, { note => q{it's <b> & co} },
+    'attribute round-trips through entity decoding';
+
+done_testing;

package/t/query.t

@@ -6,7 +6,7 @@ use utf8;
 #
 # 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
+# — packages/adapter-tests/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.
 #

package/t/search_params.t

@@ -7,7 +7,7 @@ use utf8;
 # 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,
+# vectors — `search_params_get` in packages/adapter-tests/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

package/t/template_primitives.t

@@ -81,11 +81,16 @@ subtest 'floor / ceil / round — Math.* mirrors; propagate NaN' => sub {
 # `Array.prototype.includes(x)` + `String.prototype.includes(sub)` lower
 # to the same `$bf->includes($recv, $elem)` shape — see #1448 Tier A.
 # The Perl helper dispatches on `ref()`: ARRAY ref scans elements with
-# `eq`; scalar falls back to `index(..., ...) != -1`. Anything else
-# (HASH ref, code ref) returns false to match the JS semantic that
-# `.includes` is only defined on Array / TypedArray / String.
+# `BarefootJS::Evaluator::_same_value_zero` (SameValueZero — no cross-type
+# coercion, NaN matches NaN), matching the evaluator's serialized-callback
+# `.includes` path so both positions agree; scalar falls back to
+# `index(..., ...) != -1`. Anything else (HASH ref, code ref) returns
+# false to match the JS semantic that `.includes` is only defined on
+# Array / TypedArray / String.
 subtest 'includes — array + string + non-array/string dispatch' => sub {
-    # Array receiver: element-wise `eq` (handles defined/undef parity).
+    # Array receiver: SameValueZero element search (handles defined/undef
+    # parity, and no numeric/string coercion — see the cross-type cases
+    # below).
     ok  $bf->includes(['a', 'b', 'c'], 'b'), 'array contains element → 1';
     ok !$bf->includes(['a', 'b', 'c'], 'z'), 'array does not contain → 0';
     ok  $bf->includes([1, 2, 3], 2),         'numeric element';
@@ -93,6 +98,12 @@ subtest 'includes — array + string + non-array/string dispatch' => sub {
     ok  $bf->includes([undef, 'a'], undef),  'undef element matches undef needle';
     ok !$bf->includes(['a', 'b'], undef),    'undef needle, no undef element → 0';
 
+    # SameValueZero never coerces across types — pins the divergence from
+    # the old stringy `eq` scan (where `[2].includes("2")` was true).
+    ok !$bf->includes([2], '2'),   '[2].includes("2") → 0 (no numeric→string coercion)';
+    ok  $bf->includes([2], 2),     '[2].includes(2) → 1';
+    ok  $bf->includes(['2'], '2'), '["2"].includes("2") → 1 (string vs string still matches)';
+
     # String receiver: substring search.
     ok  $bf->includes('hello world', 'world'), 'substring present → 1';
     ok !$bf->includes('hello world', 'earth'), 'substring absent → 0';

package/t/vector-divergences.json

@@ -0,0 +1,61 @@
+{
+  "version": 1,
+  "backend": "perl",
+  "runner": "packages/adapter-perl/t/helper_vectors.t",
+  "spec": "spec/template-helpers.md",
+  "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": {
+      "throws": true,
+      "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": {
+      "expect": { "$num": "NaN" },
+      "reason": "deliberate: empty input must not silently zero downstream arithmetic"
+    },
+    "number/null coerces to 0": {
+      "expect": { "$num": "NaN" },
+      "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"
+    },
+    "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"
+    }
+  },
+  "unsupported": {}
+}