@barefootjs/blade 0.1.0

package/src/adapter/lib/blade-naming.ts

@@ -0,0 +1,180 @@
+/**
+ * Blade/PHP identifier, hash-key, and member/index-access conventions for
+ * the Blade adapter.
+ *
+ * Ported from `packages/adapter-twig/src/adapter/lib/twig-naming.ts`
+ * (`twigIdent`/`twigHashKey`/`twigLoopBindingAccessor`), adjusted for the
+ * real syntax divergences between Twig and Blade that matter here:
+ *
+ * 1. **Every variable reference needs the `$` sigil.** Twig has no sigil —
+ *    `twigIdent(name)` returned the bare (possibly mangled) name, used
+ *    directly as both a read and a `{% set %}` assignment target. Blade
+ *    compiles straight to raw PHP, where every variable — read OR write —
+ *    is `$name`. `bladeIdent(name)` (this file) mirrors `twigIdent`'s
+ *    mangling-only role (used for the PHP array KEY a prop is threaded
+ *    through as, e.g. `naming.php`'s `blade_ident`); `bladeVar(name)` is the
+ *    NEW wrapper that additionally prepends `$` — every place the Blade
+ *    adapter emits a bare variable REFERENCE (identifier read, loop-binding
+ *    `@php($x = ...)` target, hash-entry value, …) uses `bladeVar`, not
+ *    `bladeIdent` alone.
+ * 2. **Hash-literal keys are always quoted, but the literal itself is a PHP
+ *    array, not a Twig hash.** `{'k': v}` → `['k' => v]` (mapping table) —
+ *    `bladeHashKey` still always quotes (same bareword-key trap Twig/Jinja
+ *    have), but every CALL SITE joins entries with `=>` and wraps them in
+ *    `[...]`, never `{...}` / `: `.
+ * 3. **Member/index access has no raw-PHP polymorphic equivalent.** Twig's
+ *    `.`/`[]` transparently resolve an object property, an array key, OR a
+ *    getter method on ANY of {stdClass, array, null} under
+ *    `strict_variables: false`. Raw PHP has no single operator with that
+ *    property — `$x->prop` fatals on a non-object, `$x['key']` warns on
+ *    `null`/scalar, and dynamic keys need yet another form. This adapter
+ *    uses Laravel's `data_get($target, $key)` (from `illuminate/support`,
+ *    already a transitive dependency of `illuminate/view`) uniformly for
+ *    BOTH member access (`a.b` → `data_get($a, 'b')`) and index access
+ *    (`a[i]` → `data_get($a, $i)`) — verified empirically (see
+ *    `bladeMemberAccess`'s docstring) to be null-safe over the same
+ *    {stdClass, array, null} value shapes Twig's dot/bracket cover, with NO
+ *    runtime helper added to `packages/adapter-php` (the `data_get`
+ *    lowering point is entirely on the TS emit side).
+ * 4. **Reserved-word set is COMPLETELY DIFFERENT, and for a different
+ *    reason.** Twig keywords (`for`, `filter`, `if`, …) collide with Twig's
+ *    OWN expression grammar — irrelevant here, since Blade variables are
+ *    real PHP variables (`$for`, `$filter` are legal). What collides
+ *    instead is anything the Blade/illuminate RENDER-TIME PHP SCOPE already
+ *    binds to a different meaning, or a name PHP itself forbids — see
+ *    `RESERVED_WORDS`'s docstring below and `php/src/naming.php`'s (this
+ *    adapter's PHP-side twin, which MUST mirror this list exactly; each
+ *    side carries a parity test against the other).
+ */
+
+import type { LoopBindingPathSegment } from '@barefootjs/jsx'
+
+/**
+ * Escape a string for a PHP/Blade single-quoted literal: backslash first (so
+ * it doesn't double-escape the quote we add next), then the quote. PHP's
+ * single-quoted string escaping rules are `\\` and `\'` ONLY (verified:
+ * `php -r "echo 'a\\'b';"` → `a'b`) — byte-identical to Twig's own
+ * single-quoted escaping, so this function's body is unchanged from
+ * `escapeTwigSingleQuoted`.
+ */
+export function escapeBladeSingleQuoted(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")
+}
+
+/**
+ * Quote an array-literal KEY for Blade/PHP. Always quotes — a bareword key
+ * in a PHP array literal (`[key => value]`) is a syntax error, not a
+ * variable lookup (unlike Twig's hash literal, where an unquoted key reads
+ * as a variable reference) — but this adapter quotes unconditionally anyway
+ * for one uniform rule across every adapter in the family (mirrors
+ * `twigHashKey`/`jinjaHashKey`).
+ */
+export function bladeHashKey(name: string): string {
+  return `'${escapeBladeSingleQuoted(name)}'`
+}
+
+/**
+ * Blade-reserved bare words: names that collide with the Blade/illuminate
+ * RENDER-TIME PHP SCOPE (not Blade template syntax — see the file header,
+ * divergence 4). Frozen by the adapter design doc; mirrored EXACTLY by
+ * `php/src/naming.php`'s `BLADE_RESERVED_WORDS` (parity test on both sides):
+ *
+ *   - `bf`     — the runtime binding every `$bf->method(...)` call resolves
+ *                against; a same-named prop would silently overwrite it.
+ *   - `this`   — PHP forbids assigning to `$this` outside object context.
+ *   - `__env`  — illuminate/view's `Factory` binds `$__env` in every
+ *                compiled view's scope.
+ *   - `__data` — `PhpEngine`/`View`'s internal name for the variable bag
+ *                before `extract()`.
+ *   - `__path` — `PhpEngine::evaluatePath()`'s compiled-file-path variable.
+ *   - `app`    — conventionally the container in many Blade/illuminate
+ *                integrations' base view scope (defensive; this adapter's
+ *                own standalone `Factory` does not bind it).
+ *   - `loop`   — Blade's `@foreach` directive injects `$loop` (iteration
+ *                metadata) into the loop body scope.
+ */
+const RESERVED_WORDS = new Set(['bf', 'this', '__env', '__data', '__path', 'app', 'loop'])
+
+/**
+ * Mangle a JS identifier (prop name, signal getter, loop param, …) into a
+ * Blade-safe NAME: reserved words get a trailing `_` suffix, everything else
+ * passes through unchanged. This is the BARE (no `$`) form — used for a PHP
+ * array KEY a prop is threaded through as (`naming.php`'s `blade_ident`,
+ * `BladeBackend::render_named`'s per-prop mangling). Every place the adapter
+ * emits an actual Blade VARIABLE REFERENCE uses `bladeVar` (below), which
+ * wraps this with the `$` sigil Twig's `twigIdent` never needed.
+ */
+export function bladeIdent(name: string): string {
+  return RESERVED_WORDS.has(name) ? `${name}_` : name
+}
+
+/**
+ * Mangle a JS identifier into a Blade VARIABLE REFERENCE (`$name` or
+ * `$name_` when reserved) — the sigil-bearing counterpart of `bladeIdent`,
+ * used at every point the adapter emits a bare variable read OR a
+ * `@php($NAME = ...)` assignment target (mirrors every `twigIdent(...)`
+ * call site in the Twig port, since Twig had no sigil to add).
+ */
+export function bladeVar(name: string): string {
+  return `$${bladeIdent(name)}`
+}
+
+/**
+ * Member access lowering: `a.b` → `data_get($a, 'b')`. Uniform, null-safe
+ * over `stdClass` (JSON-decoded objects), PHP assoc arrays (runtime helper
+ * outputs), and `null` — verified empirically:
+ *
+ *   php -r 'require "vendor/autoload.php";
+ *     $o = json_decode("{\"a\":{\"b\":1}}");
+ *     var_dump(data_get($o, "a.b"));        // int(1)
+ *     var_dump(data_get($o, "missing.x"));  // NULL (no warning)
+ *     var_dump(data_get(null, "a.b"));      // NULL (no warning)'
+ *
+ * `data_get` treats a key with no `.` as ONE top-level segment (not a
+ * multi-hop path), so a literal property name that itself happens to
+ * contain a `.` character would be misread as a nested path — accepted as a
+ * known, narrow limitation (JS field/prop names essentially never contain a
+ * literal dot; no adapter-conformance fixture does).
+ */
+export function bladeMemberAccess(objectExpr: string, property: string): string {
+  return `data_get(${objectExpr}, '${escapeBladeSingleQuoted(property)}')`
+}
+
+/**
+ * Index access lowering: `a[i]` → `data_get($a, $i)`. `data_get` accepts a
+ * non-string (int, or a PHP expression evaluating to int/string) segment
+ * directly — verified empirically: `data_get(['a','b','c'], $i)` with
+ * `$i = 1` → `'b'`. Same null-safety as `bladeMemberAccess`.
+ */
+export function bladeIndexAccess(objectExpr: string, indexExpr: string): string {
+  return `data_get(${objectExpr}, ${indexExpr})`
+}
+
+/**
+ * Build a Blade/PHP accessor expression that walks a `.map()` destructure
+ * binding's structured `segments` path (#2087 Phase A, `LoopBindingPathSegment`)
+ * off `base` — the per-iteration loop var (`$__bf_item`) for a fixed binding
+ * or a top-level rest binding, or an already-built PARENT accessor for a
+ * nested rest binding (`segments` there is the prefix up to, not including,
+ * the rest token).
+ *
+ * UNLIKE `twigLoopBindingAccessor` (which branches on bracket-subscript vs.
+ * dot-access vs. the `attribute()` builtin depending on whether a `field`
+ * segment's key is identifier-safe), every segment here — `index` OR `field`,
+ * ident-safe or not — routes through the SAME uniform `data_get` accessor
+ * (see the file header, divergence 3): there is no raw-PHP polymorphic
+ * operator to special-case around in the first place, so there is nothing to
+ * branch on. This is strictly SIMPLER than the Twig port.
+ */
+export function bladeLoopBindingAccessor(
+  base: string,
+  segments: readonly LoopBindingPathSegment[],
+): string {
+  let acc = base
+  for (const seg of segments) {
+    acc = seg.kind === 'index'
+      ? `data_get(${acc}, ${seg.index})`
+      : bladeMemberAccess(acc, seg.key)
+  }
+  return acc
+}

package/src/adapter/lib/constants.ts

@@ -0,0 +1,33 @@
+/**
+ * Compile-time constant tables for the Blade template adapter.
+ *
+ * Ported from `packages/adapter-jinja/src/adapter/lib/constants.ts`.
+ */
+
+import type { PrimitiveSpec } from './types.ts'
+
+/**
+ * Single source of truth for the Blade adapter's template-primitive surface.
+ * Each entry pairs the expected arity with the emit function.
+ *
+ * The emit fn returns a Blade/PHP expression (no surrounding `{{ }}`)
+ * suitable for embedding inside an interpolation — `$bf->json($val)`,
+ * `$bf->floor($val)`, etc. Same primitive names and keys as the Jinja/Twig
+ * adapters; every `bf.xxx(...)` call becomes `$bf->xxx(...)` (mapping table).
+ */
+export const BLADE_TEMPLATE_PRIMITIVES: Record<string, PrimitiveSpec> = {
+  'JSON.stringify': { arity: 1, emit: (args) => `$bf->json(${args[0]})` },
+  'String':         { arity: 1, emit: (args) => `$bf->string(${args[0]})` },
+  'Number':         { arity: 1, emit: (args) => `$bf->number(${args[0]})` },
+  'Math.floor':     { arity: 1, emit: (args) => `$bf->floor(${args[0]})` },
+  'Math.ceil':      { arity: 1, emit: (args) => `$bf->ceil(${args[0]})` },
+  'Math.round':     { arity: 1, emit: (args) => `$bf->round(${args[0]})` },
+}
+
+/**
+ * Module-scope `templatePrimitives` map derived once from the spec record.
+ */
+export const BLADE_PRIMITIVE_EMIT_MAP: Record<string, (args: string[]) => string> =
+  Object.fromEntries(
+    Object.entries(BLADE_TEMPLATE_PRIMITIVES).map(([k, v]) => [k, v.emit])
+  )

package/src/adapter/lib/ir-scope.ts

@@ -0,0 +1,83 @@
+/**
+ * IR traversal helpers for the Blade template adapter.
+ *
+ * Ported from `packages/adapter-twig/src/adapter/lib/ir-scope.ts`.
+ * `resolveJsxChildrenProp` and `collectRootScopeNodes` are byte-identical
+ * (adapter-agnostic IR walks).
+ *
+ * `extractTopLevelIdentifiers` is SIMPLER than the Twig port's. Twig
+ * identifiers have no sigil, so that port had to strip quoted strings first,
+ * exclude dotted property/method names, and drop a closed set of Twig-
+ * grammar keywords the adapter's own codegen could emit (`is`, `defined`,
+ * `and`, `not`, `null`, `true`, `false`, `bf`) to avoid false-matching one of
+ * those as a genuine context-var reference. Blade variables carry PHP's `$`
+ * sigil — the SAME property that made Kolon's own `\$([A-Za-z_]\w*)` scan
+ * trivially safe (see the Twig port's file header, which calls this out
+ * explicitly as the thing Twig's sigil-less grammar lacked). So this port
+ * needs no quote-stripping, no dotted-name exclusion (member/index access
+ * here is `data_get(...)`, a function call, not a `.`/`[]` postfix that
+ * could attach to a preceding bare word), and no keyword-exclusion set at
+ * all — the ONLY non-context-var `$name` this adapter's own codegen ever
+ * emits is `$bf` (the runtime handle), excluded explicitly below.
+ */
+
+import type { IRNode, IRProp, IRIfStatement, IRFragment } from '@barefootjs/jsx'
+
+/**
+ * Extract the set of "top-level identifier" tokens (bare `$name` references,
+ * `$bf` excluded) from a rendered Blade expression. `memo/seed.ts` uses this
+ * to detect a constant lowering (no real variable reference at all) that
+ * should keep the static ssr-defaults seed instead of an in-template
+ * `@php($x = ...)`; scope AVAILABILITY itself is the shared
+ * `computeSsrSeedPlan`'s job (packages/jsx/src/ssr-seed-plan.ts), not this
+ * module's.
+ */
+export function extractTopLevelIdentifiers(bladeExpr: string): string[] {
+  // Strip single-quoted string literals (this adapter only ever emits
+  // single-quoted string literals, backslash-escaped) so a literal `$name`-
+  // shaped substring inside one can't leak into the scan.
+  const stripped = bladeExpr.replace(/'(?:\\.|[^'\\])*'/g, ' ')
+  const out: string[] = []
+  for (const m of stripped.matchAll(/\$([A-Za-z_]\w*)/g)) {
+    if (m[1] !== 'bf') out.push(m[1])
+  }
+  return out
+}
+
+/**
+ * Find the `children` prop's `jsx-children` payload. Narrowed via the
+ * AttrValue `kind` discriminator so adapter code stays type-safe if the IR
+ * shape evolves.
+ */
+export function resolveJsxChildrenProp(props: readonly IRProp[]): IRNode[] {
+  const prop = props.find(p => p.name === 'children')
+  if (!prop) return []
+  if (prop.value.kind !== 'jsx-children') return []
+  return prop.value.children
+}
+
+/**
+ * Collect the component's root scope element node(s) — the elements that
+ * become the rendered root and so carry `data-key` for a keyed loop item. A
+ * plain element root is itself; an `if-statement` (early-return) root
+ * contributes the top element of each branch, since exactly one renders at
+ * runtime. (#1297)
+ */
+export function collectRootScopeNodes(node: IRNode): Set<IRNode> {
+  const out = new Set<IRNode>()
+  const visit = (n: IRNode | null): void => {
+    if (!n) return
+    if (n.type === 'element') { out.add(n); return }
+    if (n.type === 'if-statement') {
+      const s = n as IRIfStatement
+      visit(s.consequent)
+      visit(s.alternate)
+      return
+    }
+    if (n.type === 'fragment') {
+      for (const c of (n as IRFragment).children) visit(c)
+    }
+  }
+  visit(node)
+  return out
+}

package/src/adapter/lib/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared type aliases for the Blade template adapter.
+ *
+ * Ported from `packages/adapter-jinja/src/adapter/lib/types.ts`: pure type
+ * declarations — no runtime behaviour — so the extracted emit modules and
+ * the main adapter share one definition rather than re-declaring the
+ * render context / options shape.
+ */
+
+/** A template-primitive spec: expected call arity + the emit fn. */
+export interface PrimitiveSpec {
+  arity: number
+  emit: (args: string[]) => string
+}
+
+/**
+ * Blade adapter's IRNode render context. Like the Jinja adapter, Blade's
+ * lowering doesn't consume any render-position flags, so the Ctx is empty.
+ * Kept as a named alias so future flags can extend it without changing the
+ * `IRNodeEmitter` interface.
+ */
+export type BladeRenderCtx = Record<string, never>
+
+export interface BladeAdapterOptions {
+  /** Base path for client JS files (default: '/static/components/') */
+  clientJsBasePath?: string
+
+  /** Path to barefoot.js runtime (default: '/static/components/barefoot.js') */
+  barefootJsPath?: string
+}

package/src/adapter/memo/seed.ts

@@ -0,0 +1,135 @@
+/**
+ * In-template memo / context seeding for the Blade template adapter.
+ *
+ * Ported from `packages/adapter-twig/src/adapter/memo/seed.ts`. Free
+ * functions taking a `BladeMemoContext` (built by the adapter's `memoCtx`
+ * getter) so the cluster depends only on the recursive expression entry, not
+ * the whole adapter class. These emit the `@php($x = ...)` statements that
+ * let the body's bare `$x` resolve to a derived signal/memo value or an
+ * active context value at SSR time.
+ *
+ * One deliberate behavioural IMPROVEMENT over the Kolon port, carried
+ * through from the Twig/Jinja ports unchanged: Kolon's `my` declares a NEW
+ * lexical, so `: my $x = … $x …;` reads the not-yet-assigned lexical on its
+ * own right-hand side — broken. Blade's `@php($x = ...)` compiles to a
+ * plain PHP assignment statement — PHP has function-level (not block-level)
+ * scope, and the view-rendering method already `extract()`ed the incoming
+ * template vars into real PHP variables before this statement runs, so
+ * `@php($x = $x + 1)` simply reads-then-reassigns the SAME `$x` — no
+ * shadowing hazard (verified empirically:
+ * `$factory->make('t', ['x' => 5])->render()` over a template whose body is
+ * `@php($x = $x + 1)\n{{ $x }}` → `"6"`, not an error or a stale `5` — same
+ * behaviour Twig/Jinja exhibit). This adapter therefore seeds a same-name
+ * signal/memo too, which is strictly more correct — the seed then
+ * re-derives from the already-bound prop instead of leaving the render var
+ * on its static (possibly per-callsite-wrong) default. No self-ref guard is
+ * ported for this reason (same as the Twig port's divergence 8).
+ */
+
+import {
+  type ComponentIR,
+  type ContextConsumer,
+  collectContextConsumers,
+  computeSsrSeedPlan,
+  materializeGetterCalls,
+} from '@barefootjs/jsx'
+
+import type { BladeMemoContext } from '../emit-context.ts'
+import { extractTopLevelIdentifiers } from '../lib/ir-scope.ts'
+import { bladeVar, escapeBladeSingleQuoted } from '../lib/blade-naming.ts'
+
+/** Blade/PHP literal for a context-consumer's `createContext` default. */
+export function contextDefaultBlade(c: ContextConsumer): string {
+  const d = c.defaultValue
+  if (d === null || d === undefined) return 'null'
+  if (typeof d === 'string') return `'${escapeBladeSingleQuoted(d)}'`
+  if (typeof d === 'boolean') return d ? 'true' : 'false'
+  return String(d)
+}
+
+/**
+ * Emit one `@php($local = $bf->use_context(...))` statement per context
+ * consumer so the body's bare `$local` resolves to the active provider
+ * value (or the `createContext` default). (#1297)
+ */
+export function generateContextConsumerSeed(ir: ComponentIR): string {
+  const consumers = collectContextConsumers(ir.metadata)
+  if (consumers.length === 0) return ''
+  return (
+    consumers
+      .map(
+        c =>
+          `@php(${bladeVar(c.localName)} = $bf->use_context('${c.contextName}', ${contextDefaultBlade(c)}))`,
+      )
+      .join('\n') + '\n'
+  )
+}
+
+/**
+ * Emit `@php($name = <blade>)` statements for every `derived` step of the
+ * backend-neutral SSR seed plan — the scope/availability/ordering analysis
+ * lives in `computeSsrSeedPlan` (packages/jsx/src/ssr-seed-plan.ts); this
+ * only lowers each step's expression to Blade and applies the
+ * backend-specific emit guards: skip an empty lowering, and skip a lowering
+ * that references no top-level identifier at all (a constant init/body —
+ * e.g. a `derived` step with empty `frees` — keeps the existing static
+ * ssr-defaults seed instead). Unlike the Kolon port there is no self-ref
+ * guard — see the file header. `env-reader` and `opaque` steps emit nothing
+ * (the runtime supplies the reader, or the adapter's ssr-defaults path
+ * already covers it). (#1297, #2075)
+ *
+ * `convertExpressionToBlade` can still fail DEEPER than the plan's
+ * structural `isSupported` pre-check — e.g. a `.filter(predicate)` whose
+ * predicate isn't evaluator-serializable has NO lambda fallback on this
+ * adapter (`expr/emitters.ts`'s file header, divergence 9: unlike Kolon/Perl,
+ * Blade has no lambda-expression form), so the lowering records a HARD
+ * BF101 as a side effect rather than degrading. That's correct for every
+ * OTHER `convertExpressionToBlade` call site (which commit to using the
+ * lowered text), but wrong here: this is a SPECULATIVE "recompute the memo
+ * in-template, else keep the static ssrDefault seed" attempt, so a deeper
+ * refusal must degrade silently, not fail the whole component compile.
+ * Snapshot the diagnostic list and roll back any errors appended during each
+ * step's attempt before moving on.
+ *
+ * A second, related divergence opens up: a predicate referencing a SIBLING
+ * getter (`props.items.filter((p) => !tag() || …)`, `tag` a sibling memo)
+ * contains a zero-arg CALL node (`tag()`), which the evaluator's pure-
+ * expression surface refuses (`toEvalNode`'s `call` arm only allows a
+ * builtin callee, e.g. `Math.floor`) — with no lambda fallback to fall back
+ * to, the whole predicate would refuse. Kolon/Perl never hit this: their
+ * lambda form closes over the sibling's ALREADY-SEEDED lexical directly,
+ * without going through the evaluator at all. Go hits the identical gap (it
+ * also has no closures at SSR-constructor time) and fixes it the same way
+ * its `memo/memo-compute.ts` (`matchFilterArmMemo`) does:
+ * `materializeGetterCalls` rewrites a getter call into a bare identifier
+ * BEFORE serialization, so the evaluator captures it as a free-var read from
+ * `base_env` instead of an unsupported call node — and that free var then
+ * resolves against the sibling's own `@php($x = ...)` line, which (being an
+ * EARLIER step per the plan's ordering guarantee) is always already bound.
+ * `env-reader` names are excluded from the materializable set — the runtime
+ * supplies those via the per-request reader, not a template-var lexical, so
+ * a call to one (`searchParams()`) must stay a real call, not a bare var.
+ */
+export function generateDerivedMemoSeed(ctx: BladeMemoContext, ir: ComponentIR): string {
+  // Package G attached this to metadata at compile time; the `??` fallback
+  // only covers hand-built metadata in older tests that predate the attached
+  // plan — same shared function, so there's no divergence from the compiler.
+  const plan = ir.metadata.ssrSeedPlan ?? computeSsrSeedPlan(ir.metadata)
+  const knownGetterNames = new Set<string>(
+    plan.steps.filter(s => s.kind !== 'env-reader').map(s => s.name),
+  )
+  const lines: string[] = []
+  for (const step of plan.steps) {
+    if (step.kind !== 'derived') continue
+    const materialized = materializeGetterCalls(step.parsed, knownGetterNames)
+    const errorsBefore = ctx.errors.length
+    const blade = ctx.convertExpressionToBlade('', materialized)
+    if (ctx.errors.length > errorsBefore) {
+      ctx.errors.length = errorsBefore
+      continue
+    }
+    if (blade === '' || extractTopLevelIdentifiers(blade).length === 0) continue
+    lines.push(`@php(${bladeVar(step.name)} = ${blade})`)
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : ''
+}

package/src/adapter/props/prop-classes.ts

@@ -0,0 +1,66 @@
+/**
+ * Prop classification for the Blade template adapter.
+ *
+ * Ported from `packages/adapter-jinja/src/adapter/props/prop-classes.ts`.
+ * Pure functions over `ir.metadata` that derive the per-compile prop/name
+ * sets the adapter consults during lowering. No adapter instance state.
+ */
+
+import type { ComponentIR } from '@barefootjs/jsx'
+import { isStringTypeInfo, isBareStringLiteral } from '../value/parsed-literal.ts'
+
+/**
+ * Props whose declared TS type is boolean — a bare binding of one
+ * (`data-active={props.isActive}`) must stringify as JS `String(boolean)`
+ * ("true"/"false"), not PHP's `(string) bool` ("1"/"") (#1897, pagination's
+ * data-active).
+ */
+export function collectBooleanTypedProps(ir: ComponentIR): Set<string> {
+  return new Set(
+    ir.metadata.propsParams
+      .filter(prop => prop.type?.primitive === 'boolean' || prop.type?.raw === 'boolean')
+      .map(prop => prop.name),
+  )
+}
+
+/**
+ * Bare references to optional, no-default, non-primitive props (e.g.
+ * textarea's `rows`) are `null` when omitted → guarded with
+ * `is defined and is not null` in `emitExpression`. See the
+ * `nullableOptionalProps` field docstring in `blade-adapter.ts`.
+ */
+export function collectNullableOptionalProps(ir: ComponentIR): Set<string> {
+  return new Set(
+    ir.metadata.propsParams
+      .filter(
+        p =>
+          p.defaultValue === undefined &&
+          !p.isRest &&
+          p.type?.kind !== 'primitive',
+      )
+      .map(p => p.name),
+  )
+}
+
+/**
+ * String-typed signals and props. A signal is string-typed when its inferred
+ * type is `string` (or, defensively, when its initial value is a bare string
+ * literal); a prop when its annotated type is `string`. In the Mojo adapter
+ * this drives `eq`/`ne` selection for string equality; the Blade emitters
+ * don't consume the distinction — `===`/`!==` ALWAYS route through
+ * `bf.eq`/`bf.neq` regardless of operand type (see
+ * `expr/emitters.ts`'s file header, divergence 4) — so this set is carried
+ * only for parity with the Perl-family adapters.
+ */
+export function collectStringValueNames(ir: ComponentIR): Set<string> {
+  const names = new Set<string>()
+  for (const s of ir.metadata.signals) {
+    if (isStringTypeInfo(s.type) || isBareStringLiteral(s.initialValue)) {
+      names.add(s.getter)
+    }
+  }
+  for (const p of ir.metadata.propsParams) {
+    if (isStringTypeInfo(p.type)) names.add(p.name)
+  }
+  return names
+}