@barefootjs/blade 0.1.0

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@barefootjs/blade",
+  "version": "0.1.0",
+  "description": "Laravel Blade (PHP) adapter for BarefootJS — compiles IR to .blade.php templates and ships the PHP BarefootJS rendering runtime on illuminate/view standalone",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapter": {
+      "types": "./dist/adapter/index.d.ts",
+      "import": "./dist/adapter/index.js"
+    },
+    "./test-render": {
+      "bun": "./src/test-render.ts"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "import": "./dist/build.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "php/src",
+    "php/composer.json",
+    "php/tests",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build ./src/index.ts ./src/adapter/index.ts ./src/build.ts --root ./src --outdir ./dist --format esm --external @barefootjs/jsx --external @barefootjs/shared",
+    "build:types": "tsgo --emitDeclarationOnly --outDir ./dist",
+    "test": "bun test",
+    "clean": "rm -rf dist",
+    "prepack": "node ../../scripts/swap-publish-config.mjs pack",
+    "postpack": "node ../../scripts/swap-publish-config.mjs unpack"
+  },
+  "keywords": [
+    "blade",
+    "laravel",
+    "php",
+    "barefoot",
+    "ssr"
+  ],
+  "author": "kobaken <kentafly88@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/piconic-ai/barefootjs",
+    "directory": "packages/adapter-blade"
+  },
+  "dependencies": {
+    "@barefootjs/shared": "0.17.1"
+  },
+  "peerDependencies": {
+    "@barefootjs/jsx": ">=0.2.0"
+  },
+  "devDependencies": {
+    "@barefootjs/adapter-tests": "0.1.0",
+    "@barefootjs/jsx": "0.17.1",
+    "typescript": "^5.0.0"
+  }
+}

package/php/composer.json

@@ -0,0 +1,32 @@
+{
+    "name": "barefootjs/blade",
+    "description": "Laravel Blade rendering backend for the BarefootJS PHP runtime (barefootjs/php) -- BladeBackend implements the engine backend contract on illuminate/view standalone (Filesystem + Dispatcher + EngineResolver/BladeCompiler + FileViewFinder + Factory), ported from packages/adapter-twig/php/src/TwigBackend.php (see also the packages/adapter-jinja/python port's JinjaBackend).",
+    "type": "library",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "kobaken",
+            "email": "kentafly88@gmail.com"
+        }
+    ],
+    "require": {
+        "php": ">=8.2",
+        "illuminate/view": "^12.0",
+        "barefootjs/php": "@dev"
+    },
+    "repositories": [
+        {
+            "type": "path",
+            "url": "../../adapter-php"
+        }
+    ],
+    "autoload": {
+        "psr-4": {
+            "Barefoot\\": "src/"
+        },
+        "files": [
+            "src/naming.php"
+        ]
+    },
+    "minimum-stability": "stable"
+}

package/php/src/BladeBackend.php

@@ -0,0 +1,197 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Barefoot;
+
+use Illuminate\Contracts\View\Factory as ViewFactory;
+use Illuminate\Events\Dispatcher;
+use Illuminate\Filesystem\Filesystem;
+use Illuminate\Support\HtmlString;
+use Illuminate\View\Compilers\BladeCompiler;
+use Illuminate\View\Engines\CompilerEngine;
+use Illuminate\View\Engines\EngineResolver;
+use Illuminate\View\Engines\PhpEngine;
+use Illuminate\View\Factory;
+use Illuminate\View\FileViewFinder;
+
+/**
+ * Laravel Blade rendering backend for the `BarefootJS` runtime -- port of
+ * packages/adapter-twig/php/src/TwigBackend.php (itself a port of
+ * packages/adapter-jinja/python/barefootjs/backend_jinja.py's `JinjaBackend`).
+ *
+ * The engine-agnostic runtime logic (JS-compat value helpers, array/string
+ * methods, hydration markers, child rendering) lives in `BarefootJS`
+ * (`packages/adapter-php`). This backend supplies the five engine-specific
+ * operations the runtime delegates to, targeting Blade syntax, wired onto
+ * `illuminate/view` used STANDALONE -- no Laravel application/container is
+ * required, only the pieces `Illuminate\View\ViewServiceProvider` wires up
+ * (`Filesystem`, an event `Dispatcher`, an `EngineResolver` registering a
+ * `blade` engine (`CompilerEngine` over a `BladeCompiler`), a
+ * `FileViewFinder`, and the `Factory` that ties them together):
+ *
+ *   encode_json(data)            -> JSON string (injectable encoder)
+ *   mark_raw(str)                -> a value Blade emits verbatim (no re-escaping)
+ *   materialize(value)           -> resolve a captured-children value to a string
+ *   render_named(name, bf, vars) -> render `<name>.blade.php` with `bf` + vars bound
+ *   ident(name)                  -> mangle a template-variable name for this engine
+ *
+ * Pair it with the `@barefootjs/blade` compile-time adapter, which emits
+ * `.blade.php` templates that call the runtime as a `$bf` object:
+ * `{{ $bf->scope_attr() }}`, `{{ $bf->json($x) }}`, `{{ $bf->spread_attrs($bag) }}`.
+ *
+ * Escaping note (empirically verified against illuminate/view 12.x, see the
+ * adapter design doc). Blade's plain `{{ $x }}` echo compiles to
+ * `<?php echo e($x); ?>`. `Illuminate\Support\e()` special-cases any value
+ * implementing `Illuminate\Contracts\Support\Htmlable` -- it calls
+ * `->toHtml()` and returns it VERBATIM, skipping `htmlspecialchars()`
+ * entirely; every other value is escaped via `htmlspecialchars($value,
+ * ENT_QUOTES, ..., $doubleEncode = true)`. `mark_raw` below returns an
+ * `Illuminate\Support\HtmlString`, which implements `Htmlable` -- so a
+ * value this backend has marked raw (e.g. `BarefootJS::spread_attrs`'s
+ * return value) passes through a plain `{{ }}` unescaped for free, with no
+ * `{!! !!}` needed at THAT call site; call sites that receive an ordinary
+ * PHP string this runtime does NOT wrap (e.g. `hydration_attrs()`,
+ * `text_start()`/`text_end()`, `comment()`, `scope_comment()`,
+ * `render_child()`'s return value) must use the compiler's `{!! ... !!}`
+ * raw-echo form instead (mirrors Twig's explicit `| raw` filter at those
+ * same call sites). `ENT_QUOTES` emits NAMED entity forms
+ * (`&quot;`/`&#039;`), same byte-form difference as Twig's default escaper
+ * relative to Perl/Go/markupsafe's numeric forms (`&#34;`/`&#39;`) -- the
+ * adapter-tests harness's `normalizeHTML` canonicalizes entity forms before
+ * comparison, so this is conformance-equivalent, not a special case. The
+ * runtime's OWN escape paths that bypass autoescaping via `mark_raw`
+ * (`BarefootJS::spread_attrs`, and the inline quote-escaping in
+ * `hydration_attrs`/`data_key_attr`) still emit numeric entities directly,
+ * ported unchanged from `BarefootJS.pm`'s `_html_escape`.
+ */
+final class BladeBackend
+{
+    private ViewFactory $factory;
+
+    /** @var callable(mixed): string */
+    private $jsonEncoder;
+
+    /**
+     * Options-shaped constructor, mirroring `TwigBackend`'s
+     * `(paths: [...], cache_dir: ..., json_encoder: ...)` assoc-array
+     * calling convention (PHP has no keyword arguments for arrays, so one
+     * options bag is the canonical shape across every backend in this
+     * repo).
+     *
+     * @param array{
+     *   paths?: list<string>,
+     *   cache_dir?: string|null,
+     *   json_encoder?: callable|null,
+     *   factory?: ViewFactory|null,
+     * } $options `paths`: template directories (`FileViewFinder`);
+     *   `cache_dir`: directory for Blade's compiled-template cache (defaults
+     *   to a subdirectory of `sys_get_temp_dir()`, created if missing);
+     *   `json_encoder`: overrides the default canonical (sorted-key)
+     *   encoder; `factory`: a pre-built `Illuminate\Contracts\View\Factory`
+     *   (when given, `paths`/`cache_dir` are ignored and the caller owns
+     *   wiring the `blade` engine — used by integrations that already run a
+     *   full Laravel application and want to reuse its view Factory).
+     */
+    public function __construct(array $options = [])
+    {
+        $this->jsonEncoder = $options['json_encoder'] ?? [self::class, 'defaultJsonEncoder'];
+
+        if (isset($options['factory'])) {
+            $this->factory = $options['factory'];
+            return;
+        }
+
+        $paths = $options['paths'] ?? [];
+        $cacheDir = $options['cache_dir'] ?? (sys_get_temp_dir() . '/barefootjs-blade-cache');
+        if (!is_dir($cacheDir)) {
+            mkdir($cacheDir, 0777, true);
+        }
+
+        $files = new Filesystem();
+        $compiler = new BladeCompiler($files, $cacheDir);
+        $resolver = new EngineResolver();
+        $resolver->register('blade', static fn () => new CompilerEngine($compiler, $files));
+        $resolver->register('php', static fn () => new PhpEngine($files));
+
+        $finder = new FileViewFinder($files, $paths);
+        $events = new Dispatcher();
+
+        $this->factory = new Factory($resolver, $finder, $events);
+    }
+
+    public function factory(): ViewFactory
+    {
+        return $this->factory;
+    }
+
+    /**
+     * Thin delegation to the shared canonical encoder (`packages/adapter-php`'s
+     * `Barefoot\Json::canonicalEncode`) -- kept as a static method on this
+     * class (rather than removed outright) because tests/integrations
+     * reference `BladeBackend::defaultJsonEncoder` directly.
+     */
+    public static function defaultJsonEncoder($data): string
+    {
+        return Json::canonicalEncode($data);
+    }
+
+    public function encode_json($data): string
+    {
+        return ($this->jsonEncoder)($data);
+    }
+
+    /** Mark a string as already-safe so a plain `{{ }}` echo emits it
+     * verbatim (no auto-escape) -- see the file header for how
+     * `Illuminate\Support\e()`'s `Htmlable` fast path makes this work
+     * without a `{!! !!}` at the call site. */
+    public function mark_raw($s): HtmlString
+    {
+        return new HtmlString($s === null ? '' : (string) $s);
+    }
+
+    /** JSX children captured by the adapter resolve to a string (or an
+     * `HtmlString`) here -- the ONE uniform children/fallback capture
+     * mechanism (`@php(ob_start())` ... `@php($NAME = $bf->backend->mark_raw(ob_get_clean()))`,
+     * see `blade-adapter.ts`'s file header) already produces a rendered
+     * value directly, but `materialize` still supports a callable for
+     * parity with the Perl/Python/Twig ports' contract and any lazy-render
+     * composition built on top of this backend. */
+    public function materialize($value)
+    {
+        return is_callable($value) ? $value() : $value;
+    }
+
+    /**
+     * Render `<name>.blade.php` with `$childBf` bound as the `bf` variable
+     * for the nested render, plus the supplied template vars. Reserved-word
+     * mangling (`blade_ident`) is applied here -- the ONE point every props
+     * value is turned into template variables -- so a prop literally named
+     * e.g. `bf` or `this` doesn't collide with the render-time PHP scope
+     * (see `naming.php`'s docstring for the full rationale and reserved set).
+     */
+    public function render_named(string $name, $childBf, $variables): string
+    {
+        $varsArr = $variables instanceof \stdClass ? get_object_vars($variables) : (is_array($variables) ? $variables : []);
+        $mangled = [];
+        foreach ($varsArr as $k => $v) {
+            $mangled[blade_ident((string) $k)] = $v;
+        }
+        $mangled['bf'] = $childBf;
+        return $this->factory->make($name, $mangled)->render();
+    }
+
+    /**
+     * Mangle a template-variable name for Blade -- delegates to
+     * `blade_ident` (`naming.php`, engine-specific, frozen reserved-word
+     * set). Called by `BarefootJS::render_child` (the runtime,
+     * `packages/adapter-php`) so the ONE mangling point for props turned
+     * into `render_child` template variables stays engine-pluggable rather
+     * than hard-coding Blade's reserved-word set into the engine-agnostic
+     * runtime.
+     */
+    public function ident(string $name): string
+    {
+        return blade_ident($name);
+    }
+}

package/php/src/naming.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Barefoot;
+
+/**
+ * Reserved-word mangling for Blade template variable names -- SIBLING of
+ * `packages/adapter-twig/php/src/naming.php` (`twig_ident`/`TWIG_RESERVED_WORDS`)
+ * but with a COMPLETELY DIFFERENT reserved-word set, because the underlying
+ * mechanism is different: Twig resolves a bare `name` through its own
+ * expression-language variable lookup, so Twig KEYWORDS (`for`, `filter`,
+ * `if`, `in`, ...) collide with template syntax and must be mangled. Blade
+ * compiles a template straight to a plain PHP file and binds template
+ * variables as REAL PHP variables via `extract()` (illuminate/view's
+ * `PhpEngine`/`CompilerEngine`) -- so Twig's keyword list is IRRELEVANT here
+ * (`$for`, `$filter`, `$if` are all perfectly legal PHP variable names).
+ *
+ * What DOES collide for Blade is anything the render-time PHP SCOPE already
+ * binds to a name other than the incoming prop, or any name PHP itself
+ * forbids as a variable:
+ *
+ *   - `bf`     -- the runtime binding this adapter's every `bf.method(...)`
+ *                 call compiles to `$bf->method(...)`; a prop named `bf`
+ *                 would silently overwrite the runtime handle.
+ *   - `this`   -- PHP does not allow assigning to `$this` at all outside an
+ *                 object context (`Cannot re-assign $this` fatal error).
+ *   - `__env`  -- illuminate/view's `Factory` binds `$__env` in every
+ *                 compiled view's scope (used by `@section`/`@yield`/etc).
+ *   - `__data` -- `PhpEngine::evaluatePath()` / `Illuminate\View\View` use
+ *                 `$__data` as the internal name for the variable bag before
+ *                 `extract()`; a same-named prop would collide with the
+ *                 extraction mechanism itself.
+ *   - `__path` -- same layer, `PhpEngine::evaluatePath()` binds `$__path` to
+ *                 the compiled-template file path being included.
+ *   - `app`    -- Blade/illuminate conventionally expose the container as
+ *                 `$app` in many integrations' base view scope; kept reserved
+ *                 defensively even though this adapter's standalone
+ *                 `Factory` (no framework container) does not bind it itself.
+ *   - `loop`   -- Blade's `@foreach` directive injects a `$loop` variable
+ *                 (iteration metadata) into the loop body scope; this
+ *                 adapter does not itself rely on Blade's `$loop`, but a
+ *                 same-named prop landing in an ancestor scope could still
+ *                 be shadowed by a NESTED `@foreach`'s own `$loop` -- reserved
+ *                 to avoid ANY ambiguity.
+ *
+ * `blade_ident(name)` is the single mangling point: every props dict handed
+ * to a Blade template as top-level variables (`BladeBackend::render_named`,
+ * `BarefootJS::render_child`'s prop passing) is mangled through this
+ * function first, so a prop with one of the names above doesn't collide with
+ * the Blade/illuminate render-time scope. The mangling MUST match, byte for
+ * byte, `packages/adapter-blade/src/adapter/lib/blade-naming.ts`'s
+ * `BLADE_RESERVED_WORDS` list and `bladeIdent()` -- the TS side additionally
+ * runs a parity test against this file's list.
+ *
+ * This file is registered as a composer "files" autoload entry (loaded
+ * unconditionally on every request via a plain `require`, not
+ * `require_once`) AND is `require_once`'d directly by
+ * `php/tests/_harness.php::bf_require_runtime()` for the Blade-independent
+ * test files. `define()`/`function_exists()` guards (rather than a bare
+ * top-level `const`/`function`, which cannot appear inside a conditional in
+ * PHP) make loading this file twice -- regardless of which mechanism gets
+ * there first -- a safe no-op instead of a "Cannot redeclare" fatal error.
+ */
+
+if (!defined(__NAMESPACE__ . '\\BLADE_RESERVED_WORDS')) {
+    /** @var list<string> BLADE_RESERVED_WORDS */
+    define(__NAMESPACE__ . '\\BLADE_RESERVED_WORDS', [
+        'bf', 'this', '__env', '__data', '__path', 'app', 'loop',
+    ]);
+}
+
+if (!function_exists(__NAMESPACE__ . '\\blade_ident')) {
+    /**
+     * Mangle a JS identifier (prop name, signal getter, loop param, ...)
+     * into a Blade-safe (i.e. render-time-PHP-scope-safe) variable name:
+     * reserved words get a trailing `_` suffix, everything else passes
+     * through unchanged.
+     */
+    function blade_ident(string $name): string
+    {
+        return in_array($name, BLADE_RESERVED_WORDS, true) ? $name . '_' : $name;
+    }
+}

package/php/tests/test_render.php

@@ -0,0 +1,159 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Real end-to-end Blade render, modeled on packages/adapter-xslate/t/render.t
+ * and the Python port's test_render.py.
+ *
+ * Writes a `.blade.php` template equivalent to what the `@barefootjs/blade`
+ * compile-time adapter emits, then renders it through the runtime +
+ * BladeBackend. Exercises scope markers, hydration attrs, text slots via
+ * HTML comment markers, autoescaping, `spread_attrs`, and (being the one
+ * place a REAL BladeBackend is available) Blade-specific reserved-word
+ * mangling end-to-end.
+ *
+ * Needs `illuminate/view` installed (`composer install`); skips gracefully
+ * with a notice (not a failure) when `vendor/autoload.php` is absent, per
+ * the design doc.
+ *
+ * This is the only test file left in this package (the engine-agnostic
+ * runtime's test suite moved to `packages/adapter-php/tests`, see #2100) --
+ * it requires that package's `_harness.php` directly via a relative path
+ * rather than keeping a local copy or a single-file `run.php` here, and
+ * still runs standalone via `php test_render.php` (`bf_finish()` prints +
+ * `exit()`s when `BF_RUNNER` is undefined, which it is here).
+ */
+
+require_once __DIR__ . '/../../../adapter-php/tests/_harness.php';
+bf_require_runtime();
+bf_reset();
+
+$vendorAutoload = __DIR__ . '/../vendor/autoload.php';
+if (!is_file($vendorAutoload)) {
+    bf_skip_file('illuminate/view not installed -- run `composer install --working-dir=' . dirname(__DIR__) . '` to enable this test');
+    return bf_finish();
+}
+require_once $vendorAutoload;
+
+use Barefoot\BarefootJS;
+use Barefoot\BladeBackend;
+
+$tmpDir = sys_get_temp_dir() . '/barefoot-blade-render-test-' . bin2hex(random_bytes(6));
+mkdir($tmpDir, 0777, true);
+register_shutdown_function(function () use ($tmpDir) {
+    foreach (glob($tmpDir . '/*') ?: [] as $f) {
+        @unlink($f);
+    }
+    @rmdir($tmpDir);
+});
+
+// Blade idiom note: helpers that return already-safe HTML syntax but are NOT
+// wrapped by the backend's `mark_raw` (`scope_attr`, `hydration_attrs`,
+// `text_start`, `text_end`, `comment`, `scope_comment`) need the explicit
+// `{!! ... !!}` raw-echo form at the call site -- the Blade-syntax
+// equivalent of Twig's `| raw` filter / Kolon's `| mark_raw` pipe.
+// `spread_attrs` already returns an `Illuminate\Support\HtmlString` value
+// (via `backend.mark_raw`), which `Illuminate\Support\e()` passes through
+// unescaped when handed to plain `{{ }}` (the `Htmlable` fast path), so it
+// needs no `{!! !!}`.
+$widgetTemplate = '<div bf-s="{{ $bf->scope_attr() }}" {!! $bf->hydration_attrs() !!}>'
+    . "count: {!! \$bf->text_start('s0') !!}{{ \$count }}{!! \$bf->text_end() !!} "
+    . '<span {{ $bf->spread_attrs($attrs) }}>{{ $label }}</span>'
+    . '</div>';
+
+file_put_contents($tmpDir . '/widget.blade.php', $widgetTemplate);
+
+$backend = new BladeBackend(['paths' => [$tmpDir]]);
+$bf = new BarefootJS(null, ['backend' => $backend]);
+$bf->_scope_id('Widget_test');
+
+$vars = ['count' => 7, 'label' => '<x>', 'attrs' => ['id' => 'n', 'class' => 'c']];
+
+bf_test('scope and hydration markers', function () use ($backend, $bf, $vars) {
+    $out = $backend->render_named('widget', $bf, $vars);
+    bf_assert(str_contains($out, 'bf-s="Widget_test" bf-r=""'), "got: {$out}");
+});
+
+bf_test('reactive text slot with comment markers', function () use ($backend, $bf, $vars) {
+    $out = $backend->render_named('widget', $bf, $vars);
+    bf_assert(str_contains($out, 'count: <!--bf:s0-->7<!--/-->'), "got: {$out}");
+});
+
+bf_test('plain interpolation is autoescaped', function () use ($backend, $bf, $vars) {
+    $out = $backend->render_named('widget', $bf, $vars);
+    bf_assert(str_contains($out, '&lt;x&gt;'), "got: {$out}");
+});
+
+bf_test('spread_attrs renders raw with sorted keys', function () use ($backend, $bf, $vars) {
+    $out = $backend->render_named('widget', $bf, $vars);
+    bf_assert(str_contains($out, '<span class="c" id="n">'), "got: {$out}");
+});
+
+bf_test('backend unit operations', function () use ($backend) {
+    bf_assert_eq($backend->materialize('plain'), 'plain');
+    bf_assert_eq($backend->materialize(fn () => 'lazy'), 'lazy');
+    $encoded = $backend->encode_json(['b' => 2, 'a' => 1]);
+    bf_assert_eq($encoded, '{"a":1,"b":2}'); // canonical (sorted) key order
+});
+
+bf_test('render_named mangles reserved-word props', function () use ($backend, $bf, $tmpDir) {
+    file_put_contents($tmpDir . '/kw.blade.php', '{{ $bf_ }}-{{ $this_ }}');
+    $out = $backend->render_named('kw', $bf, ['bf' => 'X', 'this' => 'Y']);
+    bf_assert_eq($out, 'X-Y');
+});
+
+bf_test('render_child end-to-end (parent -> renderer -> render_named)', function () use ($backend, $bf, $tmpDir) {
+    file_put_contents($tmpDir . '/parent.blade.php', "parent:{!! \$bf->render_child('child', 'bf', 'c1', 'label', 'hi') !!}");
+    file_put_contents($tmpDir . '/child.blade.php', '[{{ $bf_ }}:{{ $label }}]');
+
+    $childRenderer = function ($props, $caller) use ($backend) {
+        $childBf = new BarefootJS(null, ['backend' => $backend]);
+        return $backend->render_named('child', $childBf, $props);
+    };
+    $bf->register_child_renderer('child', $childRenderer);
+    $out = $backend->render_named('parent', $bf, []);
+    bf_assert_eq($out, 'parent:[c1:hi]');
+});
+
+bf_test('render_child mangles reserved-word props via backend->ident (Blade-specific)', function () use ($backend, $bf) {
+    // `BarefootJS::render_child` (packages/adapter-php) delegates key
+    // mangling to the backend's `ident()` rather than hard-coding Blade's
+    // reserved-word set. This probes that delegation directly (a renderer
+    // that reads its raw `$props`, not routed back through
+    // `render_named`'s OWN mangling pass) so the contract is verified in
+    // isolation, not just as an accidental side effect of `render_named`
+    // mangling everything a second time. Uses `bf` and `this`, the
+    // Blade-specific reserved words (naming.php's BLADE_RESERVED_WORDS,
+    // frozen per the design doc) -- Blade templates bind raw PHP variables
+    // via `extract()`, so Twig/Jinja keywords like `for`/`class` are NOT
+    // reserved here; instead the render-time PHP scope itself (`$bf`, and
+    // PHP's own `$this` restriction) is what a prop name must avoid.
+    $seen = [];
+    $bf->register_child_renderer('probe', function ($props, $caller) use (&$seen) {
+        $seen['props'] = $props;
+        return 'ok';
+    });
+    $bf->render_child('probe', 'bf', 'x', 'this', 'y');
+    bf_assert_eq($seen['props']['bf_'], 'x');
+    bf_assert_eq($seen['props']['this_'], 'y');
+    bf_assert(!array_key_exists('bf', $seen['props']), 'expected the raw "bf" key to be gone after mangling');
+});
+
+// Custom-escaper sanity check (design doc §2): plain `{{ }}` interpolation
+// uses Blade's OWN default `e()` escaper (named entities), while the
+// runtime's mark_raw-wrapped helpers (spread_attrs) use numeric entities.
+// Both are exercised here on a `"` and a `'`.
+bf_test('autoescape vs. spread_attrs escaping on quote characters', function () use ($tmpDir) {
+    file_put_contents($tmpDir . '/quotes.blade.php', '{{ $raw }} | <span {{ $bf->spread_attrs($attrs) }}></span>');
+    $backend2 = new BladeBackend(['paths' => [$tmpDir]]);
+    $bf2 = new BarefootJS(null, ['backend' => $backend2]);
+    $out = $backend2->render_named('quotes', $bf2, ['raw' => "he said \"hi\" & 'bye'", 'attrs' => ['title' => "quote\" and 'apos'"]]);
+    // Blade's default `e()` escaper: &quot;/&#039; (htmlspecialchars,
+    // ENT_QUOTES); the runtime's own spread_attrs escaper: &#34;/&#39;
+    // (numeric, both sides).
+    bf_assert(str_contains($out, '&amp;'), "expected an escaped '&' in: {$out}");
+    bf_assert(str_contains($out, 'title="quote&#34; and &#39;apos&#39;"'), "expected numeric-entity escaping from spread_attrs in: {$out}");
+});
+
+return bf_finish();