@barefootjs/cli 0.17.0 → 0.18.0

package/dist/docs/core/adapters/php-adapter.md

@@ -0,0 +1,193 @@
+---
+title: PHP Adapter
+description: Render BarefootJS components from PHP — one engine-agnostic runtime with Twig and Laravel Blade backends.
+---
+
+# PHP Adapter
+
+Run the same JSX components on a PHP backend. BarefootJS compiles your JSX into
+a **marked template** plus **client JS**; on the server, a small PHP runtime
+renders those templates. The runtime is deliberately **template-engine- and
+web-framework-agnostic**, so one implementation drives multiple stacks.
+
+```
+JSX → IR → marked template (.twig / .blade.php) + Component.client.js
+                 │
+                 ▼
+   BarefootJS runtime  ──delegates──▶  pluggable backend
+   (@barefootjs/php, `barefootjs/php`)       (Twig | Laravel Blade)
+```
+
+## Two backends, one runtime
+
+| Backend | Template syntax | Compile-time package | Runtime | Where it runs |
+|---------|-----------------|----------------------|---------|---------------|
+| Twig | `{{ }}` / `{% %}` | `@barefootjs/twig` | `Barefoot\TwigBackend` | **any PHP web app** (Slim, plain PHP) — no framework |
+| Laravel Blade | `{{ }}` / `@if` / `@foreach` | `@barefootjs/blade` | `Barefoot\BladeBackend` | `illuminate/view` standalone — no Laravel application/container required |
+
+Both compile-time packages emit per-component template files and the shared
+client JS, and both render through the same engine-agnostic PHP runtime
+(`Barefoot\BarefootJS`, shipped by `@barefootjs/php` / Composer package
+`barefootjs/php`). The only thing that differs is the **backend**: a tiny
+object that implements the five operations the runtime delegates to.
+
+Both adapters are near-mechanical ports of `@barefootjs/jinja` (the Jinja2
+adapter — see the [Python Adapter](./python-adapter.md)) to their respective
+template syntax, handling the JS/PHP semantics divergences (truthiness,
+stringification, reserved-word identifier mangling, and evaluator-only
+higher-order-callback lowering, since neither Twig nor Blade has a lambda
+expression) in one uniform place.
+
+### The backend contract
+
+Everything that depends on *how* a template renders — JSON marshalling,
+raw-string marking, JSX-children materialisation, named-template
+rendering, and template-variable-name mangling — lives behind a backend
+object with five methods:
+
+| Method | Purpose |
+|--------|---------|
+| `encode_json($data)` | Serialize a value for `bf-p` props / inline JSON |
+| `mark_raw($str)` | Mark already-safe HTML so the engine won't re-escape it |
+| `materialize($value)` | Resolve captured JSX children to a string |
+| `render_named($name, $bf, $vars)` | Render a child component's template |
+| `ident($name)` | Mangle a prop name into an engine-safe template variable (Twig: grammar keywords like `for` → `for_`; Blade: render-scope collisions like `loop` → `loop_`) |
+
+Because that is the *only* engine-specific surface, the runtime
+(`Barefoot\BarefootJS` + `Barefoot\Evaluator`, in `packages/adapter-php/src/`)
+is shared unchanged between `TwigBackend` and `BladeBackend`.
+
+## Twig
+
+```
+npm install @barefootjs/twig
+```
+
+Configure the build (`barefoot.config.ts`):
+
+```typescript
+import { createConfig } from '@barefootjs/twig/build'
+
+export default createConfig({
+  components: ['./src/components'],
+  outDir: './dist',
+})
+```
+
+`bf build` emits `.twig` templates plus client JS under `outDir`. On the PHP
+side, require `barefootjs/twig` via Composer and point a `TwigBackend` at the
+emitted templates — it builds a `FilesystemLoader`-backed `Twig\Environment`
+with the defaults the templates assume (`autoescape: 'html'`,
+`strict_variables: false`); pass a pre-built Environment via `'env'` to
+customize. Rendering goes through the shared runtime: construct a
+`Barefoot\BarefootJS` over the backend and hand it to `render_named`:
+
+```php
+use Barefoot\BarefootJS;
+use Barefoot\TwigBackend;
+
+$backend = new TwigBackend([
+    'paths' => ['dist/templates'],
+]);
+$bf = new BarefootJS(null, ['backend' => $backend]);
+
+$html = $backend->render_named('user_card', $bf, ['name' => 'Ada']);
+```
+
+Twig's default escaper emits `"`/`'` for `"`/`'`, where the
+Perl/Go/Python adapters emit the numeric `"`/`'` forms — the adapter
+accounts for this byte-form difference so output stays consistent across
+backends.
+
+## Laravel Blade
+
+```
+npm install @barefootjs/blade
+```
+
+Configure the build (`barefoot.config.ts`):
+
+```typescript
+import { createConfig } from '@barefootjs/blade/build'
+
+export default createConfig({
+  components: ['./src/components'],
+  outDir: './dist',
+})
+```
+
+`bf build` emits `.blade.php` templates plus client JS under `outDir`. Blade
+runs on `illuminate/view` used **standalone** — no Laravel application or
+service container required. Construct a `Factory` (`Filesystem` + an event
+`Dispatcher` + an `EngineResolver` registering a `blade` engine over a
+`BladeCompiler` + a `FileViewFinder`, all wired together by the `Factory` —
+see `Barefoot\BladeBackend`'s constructor — `new BladeBackend(['paths' =>
+…])` wires all of that for you) pointed at the emitted templates. Rendering
+goes through the shared runtime, same as Twig:
+
+```php
+use Barefoot\BarefootJS;
+use Barefoot\BladeBackend;
+
+$backend = new BladeBackend([
+    'paths' => ['dist/templates'],
+]);
+$bf = new BarefootJS(null, ['backend' => $backend]);
+
+$html = $backend->render_named('user_card', $bf, ['name' => 'Ada']);
+```
+
+Blade's `{{ }}` echo (`Illuminate\Support\e()`) emits named HTML entity forms
+(`"`/`'` via `ENT_QUOTES`) where Perl/Go/markupsafe emit the numeric
+`"`/`'` forms — the adapter accounts for this byte-form difference so
+output stays consistent across backends.
+
+## Template output shape
+
+Both backends share the same hydration-marker contract:
+
+- One template file per component, named by snake-casing the PascalCase
+  component name (`UserCard` → `user_card.twig` / `user_card.blade.php`).
+- Hydration markers use the same runtime method names as every other
+  adapter's `bf.*` calls, spelled as PHP method calls on the `$bf` variable
+  (`bf.scope_attr()` / `$bf->scope_attr()`, `bf.hydration_attrs()` /
+  `$bf->hydration_attrs()`, `text_start`/`text_end`, `comment(...)`, …) — see
+  [`spec/template-helpers.md`](https://github.com/piconic-ai/barefootjs/blob/main/spec/template-helpers.md)
+  for the shared helper contract.
+- Every text/attribute interpolation of a possibly-non-string value is routed
+  through `string(...)` (or `bool_str(...)` for boolean-shaped values); every
+  non-comparison condition position is routed through `truthy(...)`; every JS
+  `===`/`!==` comparison routes through `eq(...)`/`neq(...)` — PHP's own
+  `==`/`===` are either loose or number-representation-sensitive in ways that
+  diverge from JS strict equality.
+
+## PHP runtime
+
+`packages/adapter-php` (Composer package `barefootjs/php`, npm package
+`@barefootjs/php`) is a self-contained, engine-agnostic PHP package with no
+template-engine dependency. It implements the `bf` object every emitted
+template calls into: hydration markers, context propagation
+(`provide_context`/`use_context`), child-component rendering
+(`render_child`), script registration, and the JS-compatible helper library
+(`string`, `bool_str`, `truthy`, `number`, `floor`/`ceil`/`round`,
+array/string helpers, `spread_attrs`, `query`, `eq`/`neq`, …). `TwigBackend`
+(`packages/adapter-twig/php/`, Composer package `barefootjs/twig`) and
+`BladeBackend` (`packages/adapter-blade/php/`, Composer package
+`barefootjs/blade`) both depend on it via a composer `path` repository, so
+adding a third PHP template engine means implementing the five-method backend
+contract above, not re-porting the runtime.
+
+## Examples
+
+Runnable end-to-end apps that render the same shared components on a PHP
+backend live under
+[`integrations/php`](https://github.com/piconic-ai/barefootjs/tree/main/integrations/php)
+(Twig) and
+[`integrations/blade`](https://github.com/piconic-ai/barefootjs/tree/main/integrations/blade)
+(Blade).
+
+## See also
+
+- [Python Adapter](./python-adapter.md) — the Jinja2 adapter this port maps from
+- [Adapter Architecture](./adapter-architecture.md) — the `TemplateAdapter` interface and IR contract
+- [Writing a Custom Adapter](./custom-adapter.md)

package/dist/docs/core/adapters/python-adapter.md

@@ -0,0 +1,100 @@
+---
+title: Python Adapter
+description: Render BarefootJS components from Python via Jinja2 — no framework required (Flask, Django, bare WSGI).
+---
+
+# Python Adapter
+
+Run the same JSX components on a Python backend. BarefootJS compiles your
+JSX into a **Jinja2 marked template** plus **client JS**; on the server, a
+small Python runtime (`barefootjs`) renders those templates through a plain
+`jinja2.Environment` — no framework is required, so Flask, Django, or bare
+WSGI all work the same way.
+
+```
+JSX → IR → marked template (.jinja) + Component.client.js
+                 │
+                 ▼
+   BarefootJS runtime  ──delegates──▶  jinja2.Environment
+   (python/barefootjs/)
+```
+
+This adapter is a near-mechanical port of `@barefootjs/xslate` (the
+Text::Xslate/Kolon adapter — see the [Perl Adapter](./perl-adapter.md)) to
+Jinja2 syntax, handling the JS/Python semantics divergences (truthiness,
+stringification, reserved-word identifier mangling, and evaluator-only
+higher-order-callback lowering, since Jinja has no lambda expression) in one
+uniform place rather than per fixture.
+
+## Template output shape
+
+- One `.jinja` file per component, named by snake-casing the PascalCase
+  component name (`UserCard` → `user_card.jinja`).
+- Hydration markers use the same runtime method names as every other
+  adapter's `bf.*` calls (`bf.scope_attr()`, `bf.hydration_attrs()`,
+  `bf.text_start`/`text_end`, `bf.comment(...)`, …).
+- Every text/attribute interpolation of a possibly-non-string value is
+  routed through `bf.string(...)` (or `bf.bool_str(...)` for boolean-shaped
+  values); every non-comparison condition position is routed through
+  `bf.truthy(...)`.
+
+## Python runtime
+
+`python/barefootjs/` (shipped inside `@barefootjs/jinja`) is a
+self-contained Python package with only one dependency, `jinja2`. It
+implements the engine-agnostic `bf` object every emitted template calls
+into: hydration markers, context propagation
+(`provide_context`/`use_context`), child-component rendering
+(`render_child`), script registration, and the JS-compatible helper library
+(`string`, `bool_str`, `truthy`, `number`, `floor`/`ceil`/`round`,
+array/string helpers, `spread_attrs`, `query`, …).
+
+## Usage
+
+```
+npm install @barefootjs/jinja
+```
+
+Configure the build (`barefoot.config.ts`):
+
+```typescript
+import { createConfig } from '@barefootjs/jinja/build'
+
+export default createConfig({
+  components: ['./src/components'],
+  outDir: './dist',
+})
+```
+
+`bf build` emits `.jinja` templates plus client JS under `outDir`. On the
+Python side, vendor `python/barefootjs/` (from `@barefootjs/jinja`) into
+your app and render a component by constructing a `jinja2.Environment` over
+a `FileSystemLoader` pointed at the emitted templates, with the exact
+settings this adapter's output assumes:
+
+```python
+import jinja2
+from barefootjs import backend_jinja
+
+env = jinja2.Environment(
+    loader=jinja2.FileSystemLoader("dist/templates"),
+    autoescape=True,
+    undefined=jinja2.ChainableUndefined,
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+
+html = backend_jinja.render_named(env, "user_card", vars={"name": "Ada"})
+```
+
+`trim_blocks`/`lstrip_blocks` are required because the adapter places
+`{% … %}` control tags on their own source line; `ChainableUndefined` is
+required so a missing nested attribute (`missing.deep`) renders as empty
+rather than raising.
+
+## See also
+
+- [Perl Adapter](./perl-adapter.md) — the Text::Xslate/Kolon adapter this port maps from
+- [Rust Adapter](./rust-adapter.md) — a near-verbatim port of this adapter targeting minijinja, with identical template output
+- [Adapter Architecture](./adapter-architecture.md) — the `TemplateAdapter` interface and IR contract
+- [Writing a Custom Adapter](./custom-adapter.md)

package/dist/docs/core/adapters/ruby-adapter.md

@@ -0,0 +1,88 @@
+---
+title: Ruby Adapter
+description: Render BarefootJS components from Ruby via ERB — runs under any Rack app (Sinatra, Rails).
+---
+
+# Ruby Adapter
+
+Run the same JSX components on a Ruby backend. BarefootJS compiles your JSX
+into an **ERB marked template** plus **client JS**; on the server, a small
+Ruby runtime (`BarefootJS`) renders those templates through Ruby's stdlib
+`ERB` — no web framework is required, so it runs under any Rack app
+(Sinatra, Rails, or plain Rack).
+
+```
+JSX → IR → marked template (.erb) + Component.client.js
+                 │
+                 ▼
+   BarefootJS runtime  ──delegates──▶  BarefootJS::Backend::Erb
+   (lib/barefoot_js.rb)                (stdlib ERB)
+```
+
+It is a Ruby port of the Perl runtime (`BarefootJS.pm`, see the
+[Perl Adapter](./perl-adapter.md)), keeping method names 1:1 (`bf.scope_attr`,
+`bf.hydration_attrs`, `bf.render_child`, …) so the compile-time adapter and
+runtime share one naming contract across languages.
+
+## Backend contract
+
+Like the Perl and Text::Xslate ports, everything that depends on *how* a
+template renders is delegated to a small `backend` object:
+
+| Method | Purpose |
+|--------|---------|
+| `encode_json(data)` | Serialize a value for `bf-p` props / inline JSON |
+| `mark_raw(str)` | Mark already-safe HTML (identity for ERB — see below) |
+| `materialize(value)` | Resolve captured JSX children to a string |
+| `render_named(name, bf, vars)` | Render a child component's `.erb` template |
+
+Unlike Kolon or Twig, stdlib ERB's `<%= %>` does **not** auto-escape, so
+`mark_raw` is a no-op — the compiled templates call `bf.h(...)` explicitly
+wherever escaping is required. `mark_raw` exists purely so runtime helpers
+that already produce finished HTML (e.g. `spread_attrs`) share one
+`backend.mark_raw(...)` call shape with every other BarefootJS backend.
+
+## Usage
+
+```
+npm install @barefootjs/erb
+```
+
+Configure the build (`barefoot.config.ts`):
+
+```typescript
+import { createConfig } from '@barefootjs/erb/build'
+
+export default createConfig({
+  components: ['./components'],
+  outDir: 'dist',
+})
+```
+
+`bf build` emits one `.erb` file per component plus the client JS bundle. On
+the Ruby side, vendor `lib/barefoot_js.rb` (from `@barefootjs/erb`) into your
+app and construct the ERB backend against the output directory:
+
+```ruby
+require 'barefoot_js'
+require 'barefoot_js/backend/erb'
+
+backend = BarefootJS::Backend::Erb.new(path: 'dist/templates')
+bf = BarefootJS::Context.new(backend)
+bf._scope_id("Counter_#{rand(1_000_000)}")
+
+html = backend.render_named('Counter', bf, { count: 0 })
+```
+
+Each compiled `.erb` template receives exactly two locals: `bf` (the
+`BarefootJS::Context` for this render) and `v` (a symbol-keyed Hash holding
+every prop/signal/memo the template references) — e.g.
+`<%= bf.h(v[:count]) %>`, `<%= bf.spread_attrs(bag) %>` — stdlib ERB's
+`<%=` never auto-escapes, so both plain and already-safe-HTML helpers use
+the same tag; there is no separate raw-output tag like Mojolicious's `<%==`.
+
+## See also
+
+- [Perl Adapter](./perl-adapter.md) — the runtime this port mirrors method-for-method
+- [Adapter Architecture](./adapter-architecture.md) — the `TemplateAdapter` interface and IR contract
+- [Writing a Custom Adapter](./custom-adapter.md)

package/dist/docs/core/adapters/rust-adapter.md

@@ -0,0 +1,136 @@
+---
+title: Rust Adapter
+description: Render BarefootJS components from Rust via minijinja — no framework required (axum, actix-web, warp).
+---
+
+# Rust Adapter
+
+Run the same JSX components on a Rust backend. BarefootJS compiles your JSX
+into a **minijinja marked template** plus **client JS**; on the server, a
+small Rust runtime (crate `barefootjs`) renders those templates through a
+plain [`minijinja::Environment`](https://docs.rs/minijinja) — no framework
+is required, so axum, actix-web, warp, or bare `hyper` all work the same
+way.
+
+```
+JSX → IR → marked template (.j2) + Component.client.js
+                 │
+                 ▼
+   BarefootJS runtime  ──delegates──▶  minijinja::Environment
+   (runtime/, crate barefootjs)
+```
+
+This adapter is a near-verbatim port of `@barefootjs/jinja` (the Python
+adapter — see the [Python Adapter](./python-adapter.md)) to the `minijinja`
+Rust crate. **The emitted template syntax is identical** to
+`@barefootjs/jinja`'s output — minijinja 2.21 is Jinja2-compatible for
+everything this adapter emits. Only the identity fields differ (`.j2`
+extension) plus the render engine that interprets the syntax at request
+time (a Rust `minijinja::Environment` instead of Python's
+`jinja2.Environment`).
+
+## Template output shape
+
+- One `.j2` file per component, named by snake-casing the PascalCase
+  component name (`UserCard` → `user_card.j2`).
+- Hydration markers use the same runtime method names as every other
+  adapter's `bf.*` calls (`bf.scope_attr()`, `bf.hydration_attrs()`,
+  `bf.text_start`/`text_end`, `bf.comment(...)`, …).
+- Every text/attribute interpolation of a possibly-non-string value is
+  routed through `bf.string(...)` (or `bf.bool_str(...)` for boolean-shaped
+  values); every non-comparison condition position is routed through
+  `bf.truthy(...)`.
+
+## The minijinja Environment contract
+
+This adapter's output assumes an `Environment` built with a specific set of
+options — `ChainableUndefined`, `trim_blocks`/`lstrip_blocks`, HTML
+auto-escaping forced on, and a custom formatter. Rather than assembling
+these yourself, call the crate's `build_environment`, which constructs the
+`Environment` per that contract:
+
+```rust
+use barefootjs::backend_minijinja::build_environment;
+
+let env = build_environment(templates_dir); // .j2 files
+```
+
+`trim_blocks`/`lstrip_blocks` are required because `{% … %}` control tags
+sit on their own source line; without them every such line leaks a stray
+newline/indentation into the rendered HTML. The internal formatter escapes
+strings with MarkupSafe-compatible entities (`'`, not minijinja's
+default `'`) and formats numbers with JS `String(n)` semantics
+(`1.0` → `1`), matching every other adapter's byte-for-byte output.
+
+## Rust runtime
+
+`runtime/` (crate `barefootjs`, deps: `minijinja`, `serde`, `serde_json`)
+implements the engine-agnostic `bf` object every emitted template calls
+into: hydration markers, context propagation
+(`provide_context`/`use_context`), child-component rendering
+(`render_child`), script registration, and the JS-compatible helper library
+(`string`, `bool_str`, `truthy`, `number`, `floor`/`ceil`/`round`,
+array/string helpers, `spread_attrs`, `query`, …).
+
+## Usage
+
+```
+npm install @barefootjs/rust
+```
+
+Configure the build (`barefoot.config.ts`):
+
+```typescript
+import { createConfig } from '@barefootjs/rust/build'
+
+export default createConfig({
+  components: ['./src/components'],
+  outDir: './dist',
+})
+```
+
+`bf build` emits `.j2` templates plus client JS under `outDir`. On the Rust
+side, depend on the `barefootjs` crate, build the `Environment` via
+`build_environment` (per the contract above), and render a component
+through a `RenderSession` + root `BfInstance`:
+
+```rust
+use axum::{routing::get, Router};
+use barefootjs::{backend_minijinja, BfInstance, JsValue, RenderSession};
+use minijinja::Environment;
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+use std::sync::Arc;
+
+async fn user_card(env: Arc<Environment<'static>>) -> axum::response::Html<String> {
+    let session = RenderSession::new();
+    let root = BfInstance::root(Arc::clone(&session), "UserCard_0");
+    let vars = JsValue::Object(BTreeMap::from([("name".to_string(), JsValue::String("Ada".into()))]));
+
+    let html = backend_minijinja::render_named(&env, "user_card", root.as_mj_value(), &vars).unwrap();
+    axum::response::Html(html)
+}
+
+#[tokio::main]
+async fn main() {
+    let env = Arc::new(backend_minijinja::build_environment(&PathBuf::from("dist/templates")));
+    let app = Router::new().route("/", get(move || user_card(env.clone())));
+    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
+    axum::serve(listener, app).await.unwrap();
+}
+```
+
+A full runnable app wiring this up with manifest-driven child-component
+registration lives at
+[`integrations/axum`](https://github.com/piconic-ai/barefootjs/tree/main/integrations/axum)
+(see `src/render.rs`'s `render_component` for the production-shaped version
+of the snippet above). The crate also ships a `bf-render` binary, a
+conformance renderer used by the adapter's own test suite (`cargo build
+--bin bf-render`) — most hosts should link the `barefootjs` library crate
+directly, as above, rather than shelling out to the binary.
+
+## See also
+
+- [Python Adapter](./python-adapter.md) — the Jinja2 adapter this is a near-verbatim port of, with identical template syntax
+- [Adapter Architecture](./adapter-architecture.md) — the `TemplateAdapter` interface and IR contract
+- [Writing a Custom Adapter](./custom-adapter.md)

package/dist/docs/core/adapters.md

@@ -23,6 +23,10 @@ JSX Source
 | [`HonoAdapter`](./adapters/hono-adapter.md) | `.tsx` | Hono / JSX-based servers | `@barefootjs/hono` |
 | [`GoTemplateAdapter`](./adapters/go-template-adapter.md) | `.tmpl` + `_types.go` | Go `html/template` | `@barefootjs/go-template` |
 | [Perl](./adapters/perl-adapter.md) | `.ep` / `.tx` | Mojolicious, Text::Xslate (PSGI/Plack) | `@barefootjs/mojolicious`, `@barefootjs/xslate` |
+| [Ruby](./adapters/ruby-adapter.md) | `.erb` | stdlib ERB (any Rack app — Sinatra, Rails) | `@barefootjs/erb` |
+| [Python](./adapters/python-adapter.md) | `.jinja` | Jinja2 (Flask, Django, bare WSGI) | `@barefootjs/jinja` |
+| [PHP](./adapters/php-adapter.md) | `.twig` / `.blade.php` | Twig (Slim, plain PHP), Laravel Blade (`illuminate/view` standalone) | `@barefootjs/twig`, `@barefootjs/blade` |
+| [Rust](./adapters/rust-adapter.md) | `.j2` | minijinja (axum, actix-web, warp) | `@barefootjs/rust` |
 | [CSR](./adapters/csr.md) | — (client-rendered) | None (browser-only) | `@barefootjs/client` |
 
 > CSR is not an IR→template adapter. It renders components directly in the browser using client-side template functions — use it when the server can't (or shouldn't) emit the initial HTML.
@@ -31,6 +35,8 @@ The `GoTemplateAdapter` is web-framework-agnostic: its `html/template` output ru
 
 The Perl adapters share one engine-agnostic runtime (`BarefootJS`): `@barefootjs/mojolicious` targets Mojolicious EP, and `@barefootjs/xslate` targets Text::Xslate (Kolon) and runs under any PSGI/Plack app. See the [Perl Adapter](./adapters/perl-adapter.md) page.
 
+The Ruby, Python, and Rust adapters are each single-backend, engine-agnostic ports of that same runtime model to another language: `@barefootjs/erb` (Ruby/ERB), `@barefootjs/jinja` (Python/Jinja2), and `@barefootjs/rust` (Rust/minijinja) — none of them require a specific web framework. The PHP adapters follow the same pattern but, like Perl, share one engine-agnostic runtime (`@barefootjs/php`) across two backends: `@barefootjs/twig` targets Twig and `@barefootjs/blade` targets Laravel Blade (via `illuminate/view` standalone). `@barefootjs/twig`, `@barefootjs/blade`, and `@barefootjs/rust` are themselves near-mechanical ports of `@barefootjs/jinja`'s Jinja2 syntax, so all emit near-identical templates. See the [PHP Adapter](./adapters/php-adapter.md) page.
+
 ## Pages
 
 | Topic | Description |
@@ -39,5 +45,9 @@ The Perl adapters share one engine-agnostic runtime (`BarefootJS`): `@barefootjs
 | [Hono Adapter](./adapters/hono-adapter.md) | Configuration and output format for Hono / JSX-based servers |
 | [Go Template Adapter](./adapters/go-template-adapter.md) | Configuration and output format for Go `html/template` |
 | [Perl Adapter](./adapters/perl-adapter.md) | Mojolicious and Text::Xslate (PSGI/Plack) backends, sharing one runtime |
+| [Ruby Adapter](./adapters/ruby-adapter.md) | ERB backend, running under any Rack app |
+| [Python Adapter](./adapters/python-adapter.md) | Jinja2 backend, running under any Python web framework |
+| [PHP Adapter](./adapters/php-adapter.md) | Twig (any PHP web app) and Laravel Blade (`illuminate/view` standalone) backends |
+| [Rust Adapter](./adapters/rust-adapter.md) | minijinja backend, running under any Rust web framework |
 | [CSR](./adapters/csr.md) | Client-side rendering without a server-rendered template |
 | [Writing a Custom Adapter](./adapters/custom-adapter.md) | Step-by-step guide to implementing your own adapter |

package/dist/docs/core/advanced/error-codes.md

@@ -141,10 +141,18 @@ Simple subtraction: `(a, b) => a.field - b.field`:
 // ✅ SSR-compilable
 {items().sort((a, b) => a.price - b.price).map(...)}     // ascending
 {items().toSorted((a, b) => b.date - a.date).map(...)}   // descending
-
-// ❌ BF021 — block bodies, localeCompare, ternary operators, etc. are not supported
-{items().sort((a, b) => { return a.price - b.price }).map(...)}
-{items().sort((a, b) => a.name.localeCompare(b.name)).map(...)}
+{items().sort((a, b) => { return a.price - b.price }).map(...)}     // single-return block body
+{items().sort((a, b) => a.name.localeCompare(b.name)).map(...)}     // zero-arg localeCompare
+
+// A bare identifier reference to a same-file const/function comparator
+// resolves one hop and compiles like the inline arrow above (#2090):
+const byPrice = (a, b) => a.price - b.price
+{items().sort(byPrice).map(...)}
+
+// ❌ BF021 — locale/options localeCompare, and an unresolved comparator
+// (imported, a prop, or an alias chain) are not supported
+{items().sort((a, b) => a.name.localeCompare(b.name, 'ja', { numeric: true })).map(...)}
+{items().sort(importedCmp).map(...)}
 ```
 
 #### Workaround

package/dist/docs/core/llms.txt

@@ -45,6 +45,10 @@
 - [Go Template Adapter](https://barefootjs.dev/docs/adapters/go-template-adapter.md): Generate Go html/template files and type definitions from the compiler's IR.
 - [Hono Adapter](https://barefootjs.dev/docs/adapters/hono-adapter.md): Generate Hono JSX templates from the compiler's IR for Hono-based servers.
 - [Perl Adapter](https://barefootjs.dev/docs/adapters/perl-adapter.md): Render BarefootJS components from Perl — one engine-agnostic runtime with Mojolicious and Text::Xslate (PSGI/Plack) backends.
+- [PHP Adapter](https://barefootjs.dev/docs/adapters/php-adapter.md): Render BarefootJS components from PHP — one engine-agnostic runtime with Twig and Laravel Blade backends.
+- [Python Adapter](https://barefootjs.dev/docs/adapters/python-adapter.md): Render BarefootJS components from Python via Jinja2 — no framework required (Flask, Django, bare WSGI).
+- [Ruby Adapter](https://barefootjs.dev/docs/adapters/ruby-adapter.md): Render BarefootJS components from Ruby via ERB — runs under any Rack app (Sinatra, Rails).
+- [Rust Adapter](https://barefootjs.dev/docs/adapters/rust-adapter.md): Render BarefootJS components from Rust via minijinja — no framework required (axum, actix-web, warp).
 
 ## Advanced
 

package/dist/docs/core/rendering/jsx-compatibility.md

@@ -76,7 +76,7 @@ return <div>...</div>
 ))}
 ```
 
-Supported comparator shapes: `(a, b) => a - b`, `(a, b) => a.field - b.field`, `(a, b) => a.localeCompare(b)`, `(a, b) => a.field.localeCompare(b.field)`, relational-ternary returns (`(a, b) => a.field > b.field ? 1 : -1`, including the 3-way `a < b ? -1 : a > b ? 1 : 0` form), and any of these `||`-chained for multi-key tie-breaks. A single-`return` block body (`(a, b) => { return a.field - b.field }`) works too. Reverse the operands (or the ternary sign) for descending order. Other shapes — function references (`sort(myCmp)`), multi-statement block bodies, and `localeCompare(b, locale, opts)` — produce a compile error; use `/* @client */` in that case.
+Supported comparator shapes: `(a, b) => a - b`, `(a, b) => a.field - b.field`, `(a, b) => a.localeCompare(b)`, `(a, b) => a.field.localeCompare(b.field)`, relational-ternary returns (`(a, b) => a.field > b.field ? 1 : -1`, including the 3-way `a < b ? -1 : a > b ? 1 : 0` form), and any of these `||`-chained for multi-key tie-breaks. A single-`return` block body (`(a, b) => { return a.field - b.field }`) works too. Reverse the operands (or the ternary sign) for descending order. A bare identifier reference to a same-file `const`/`function` comparator (`sort(byPrice)`) resolves one hop and compiles the same as the inline arrow. Other shapes — multi-statement block bodies, `localeCompare(b, locale, opts)`, and an unresolved reference (imported, a prop, or an alias chain like `const c2 = c1`) — produce a compile error; use `/* @client */` in that case.
 
 
 ## Event Handling
@@ -106,8 +106,10 @@ Some JavaScript expressions cannot be translated into marked template syntax. Wh
 | `.filter()` with destructured param (`({done}) => done`) | works (runs as JS) | **BF101** |
 | `.filter()` with `function` keyword callback | works | **BF101** |
 | `.reduce()`, `.forEach()`, `.flatMap()` | works | **BF101** |
-| Nested higher-order in filter predicate (`x => x.tags.filter(...).length > 0`) | works | **BF101** |
-| Sort comparator that's a function reference, multi-statement block body, or `localeCompare(b, locale, opts)` | **BF021** (all adapters) | **BF021** |
+| Nested `.filter()` / `.map()` in a filter predicate (`x => x.tags.filter(...).length > 0`) | works | works |
+| Nested `.some()` / `.find()` / `.reduce()` in a filter predicate | works | **BF101** |
+| Sort comparator that's a multi-statement block body or `localeCompare(b, locale, opts)` | **BF021** (all adapters) | **BF021** |
+| Sort comparator that's a function reference to an imported/prop identifier, or an alias chain (`const c2 = c1`) | **BF021** (all adapters) | **BF021** |
 | `typeof` in a filter predicate | **BF021** (all adapters) | **BF021** |
 
 `BF021` is raised at the IR layer and applies to every adapter. `BF101` is raised by adapters that can't lower the expression to their template language. Either way, add [`/* @client */`](./client-directive.md) to opt into client-only evaluation and suppress the error.
@@ -116,12 +118,21 @@ Some JavaScript expressions cannot be translated into marked template syntax. Wh
 
 **Nested higher-order methods:**
 
+A nested `.filter()` / `.map()` inside a filter predicate's callback body lowers on every adapter — the runtime evaluator serializes the nested call (the callback arrow travels with it) instead of refusing it:
+
+```tsx
+// ✅ Nested `.filter()` / `.map()` now compiles everywhere
+{items().filter(x => x.tags.filter(t => t.active).length > 0).map(t => t.name)}
+```
+
+A nested `.some()` / `.find()` / `.reduce()` still has no faithful Go/Mojo lowering (they return a boolean-from-search / element / fold, not a per-element projection), so they still refuse:
+
 ```tsx
 // ❌ BF101 on Go/Mojo; works on Hono
-{items().filter(x => x.tags.filter(t => t.active).length > 0).map(...)}
+{items().filter(x => x.tags.some(t => t.active)).map(t => t.name)}
 
 // ✅ Add /* @client */ to evaluate on the client
-{/* @client */ items().filter(x => x.tags.filter(t => t.active).length > 0).map(...)}
+{/* @client */ items().filter(x => x.tags.some(t => t.active)).map(t => t.name)}
 ```
 
 **`.reduce()` / `.forEach()` / `.flatMap()`:**
@@ -156,7 +167,7 @@ Some JavaScript expressions cannot be translated into marked template syntax. Wh
 
 ### Patterns that error on all adapters
 
-**Unsupported sort comparators** (imperative block bodies, function references):
+**Unsupported sort comparators** (imperative block bodies, unresolved function references):
 
 A value-producing block body normalizes to an expression — pure `const`
 bindings inline (let-inline) and a value-producing `if` / early `return`
@@ -184,4 +195,22 @@ Only a genuinely imperative comparator — one that re-assigns a local, loops, o
 ))}
 ```
 
+A same-file `const`/`function` comparator reference resolves one hop and
+compiles (see the "Sort comparators" section above); an **imported** or
+**aliased** reference does not — the compiler follows the identifier back
+only one binding, so it can't see through a re-export or `const c2 = c1`:
+
+```tsx
+// ❌ BF021 — `byPrice` is imported, not declared in this file
+import { byPrice } from './comparators'
+function SortedList({ items }: { items: Item[] }) {
+  return <ul>{items.sort(byPrice).map((item) => <li key={item.id}>{item.name}</li>)}</ul>
+}
+
+// ✅ Use /* @client */, or inline / re-declare the comparator locally
+{/* @client */ items().sort(byPrice).map(item => (
+  <Item key={item.id} item={item} />
+))}
+```
+
 See the [TodoApp example](https://github.com/piconic-ai/barefootjs/blob/main/integrations/shared/components/TodoApp.tsx) for a real-world component using `/* @client */`.