@barefootjs/cli 0.35.5 → 0.35.6

package/dist/docs/core/README.mdx

@@ -60,7 +60,7 @@
 
 - [IR Schema Reference](./advanced/ir-schema.md) — Node types, metadata, hydration markers
 - [Compiler Internals](./advanced/compiler-internals.md) — Pipeline phases, reactivity analysis, code generation
-- [Error Codes Reference](./advanced/error-codes.md) — All BF001–BF043 errors with solutions
+- [Error Codes Reference](./advanced/error-codes.md) — All BF-prefixed errors with solutions
 - [Performance Optimization](./advanced/performance.md) — Minimal client JS, fast hydration, efficient reactivity
 
 ---

package/dist/docs/core/advanced/compiler-internals.md

@@ -75,17 +75,32 @@ Files with reactive APIs but no `"use client"` emit **BF001**:
 error[BF001]: 'use client' directive required for components with createSignal
 ```
 
-### Props Destructuring Detection
+### Destructured Props Stay Live
 
 ```tsx
-// ⚠️ BF043: Destructuring captures values once — may lose reactivity
 function Child({ count }: Props) { ... }
 
-// ✅ No warning — direct access maintains reactivity
+// Compiles identically to direct access:
 function Child(props: Props) { ... }
 ```
 
-Suppress with `// @bf-ignore props-destructuring`.
+Both forms record the same `propsParams` metadata in Phase 1. Phase 2 (client JS emission)
+rewrites every value-position read of a name bound by the destructured PARAMETER — inside
+effects, memos, handlers, text, reactive attributes, anywhere in the generated `init*` body —
+to a live `_p.<key>` read, the same read `props.xxx` compiles to. See
+`rewriteDestructuredPropReads` (`ir-to-client-js/rewrite-destructured-props.ts`) and
+`livePropReadExpr` (`props-binding.ts`).
+
+Destructuring in the function BODY (`const { count } = props`, or the equivalent `const count
+= props.count`) is a pure single-prop alias — the analyzer's IR can't tell the two shapes
+apart, and treats them identically — and is ALSO rewritten live, via the same
+`rewriteDestructuredPropReads` door's `rewriteBodyAliasReads` branch
+(`resolveBodyPropAliases`, `props-binding.ts`): the local's own extraction is deleted from the
+emitted body (it would otherwise shadow the very references the rewrite is trying to make
+live) and every reference to it becomes `_p.count`, same as the parameter form. This does NOT
+apply once the local does a real computation of its own (`const doubled = count * 2` stays an
+ordinary once-evaluated local) or is reassigned (`let { count } = props` is never treated as
+a live alias).
 
 ---
 

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

@@ -317,64 +317,41 @@ See [JSX Compatibility](../rendering/jsx-compatibility.md) for the full worked e
 
 ---
 
-## Component Errors (BF043–BF049)
+## Component Errors (BF044–BF049)
 
-<a id="bf043"></a>
-
-### BF043 — Props Destructuring (Warning)
-
-**Trigger:** Props destructured in function parameter.
-
-```tsx
-// ⚠️ BF043
-function Child({ count }: Props) {
-  return <span>{count}</span>  // count is captured once
-}
-```
-
-```
-warning[BF043]: Destructuring props in function parameters captures values once.
-   = help: Use `props.count` for reactive access, or suppress with // @bf-ignore props-destructuring
-```
-
-**Fix options:**
-
-1. Use direct props access:
-
-```tsx
-function Child(props: Props) {
-  return <span>{props.count}</span>  // Reactive
-}
-```
-
-2. Suppress if intentional (static initial value):
-
-```tsx
-// @bf-ignore props-destructuring
-function Child({ initialCount }: Props) {
-  const [count, setCount] = createSignal(initialCount)
-  return <span>{count()}</span>
-}
-```
+<!--
+  BF043 (Props Destructuring warning) is retired: destructured props read
+  live, the same as `props.xxx` access, so there is no reactivity difference
+  left to warn about. See [Props Reactivity](../reactivity/props-reactivity.md).
+-->
 
 <a id="bf044"></a>
 
 ### BF044 — Signal/Memo Getter Not Called
 
-**Trigger:** Signal/memo getter passed without calling it.
+**Trigger:** Signal/memo getter passed without calling it in a RENDERED
+position — a DOM element attribute or a JSX text child, where the value
+becomes literal output.
 
 ```tsx
 // ❌ BF044
-<Child count={count} />  // Passing getter function, not the value
+<div count={count} />  // Passing getter function, not the value
 ```
 
 **Fix:**
 
 ```tsx
 // ✅ Fixed
-<Child count={count()} />
+<div count={count()} />
 ```
 
+**Not triggered on a component prop:** `<Child count={count} />` compiles —
+a component prop is an opaque value handed to the child, not rendered
+output, and passing a live getter there is this codebase's deliberate
+Context-Provider idiom (the child calls it at its own read site). See
+[`spec/compiler.md`'s BF044 section](https://github.com/piconic-ai/barefootjs/blob/main/spec/compiler.md#signalmemo-getter-not-called-bf044)
+for the full rule.
+
 <a id="bf049"></a>
 
 ### BF049 — Rich-Typed Prop Not Hydratable
@@ -457,25 +434,6 @@ export function Page() {
 
 ---
 
-## Suppressing Warnings
-
-Suppress with `@bf-ignore`:
-
-```tsx
-// @bf-ignore props-destructuring
-function Component({ checked }: Props) {
-  // Warning suppressed
-}
-```
-
-**Available rules:**
-
-| Rule ID | Error Code | Description |
-|---------|------------|-------------|
-| `props-destructuring` | BF043 | Props destructuring in function parameters |
-
----
-
 ## Error Code Quick Reference
 
 | Code | Severity | Description |
@@ -486,7 +444,6 @@ function Component({ checked }: Props) {
 | BF013 | Error | Reactive primitive called through an unresolved namespace import |
 | BF021 | Error | Unsupported JSX pattern for SSR |
 | BF023 | Error | Missing key in list |
-| BF043 | Warning | Props destructuring breaks reactivity |
 | BF044 | Error | Signal/memo getter passed without calling it |
 | BF049 | Error | Rich-typed prop read by client code cannot survive hydration |
 | BF054 | Error | Built-in `<Async>` / `<Region>` used without `@barefootjs/client` import |

package/dist/docs/core/components/props-type-safety.md

@@ -35,10 +35,11 @@ function Button(props: { variant?: 'default' | 'primary'; children?: Child }) {
 }
 ```
 
-For initial-value-only props, default parameter syntax works. Add `@bf-ignore` to suppress the `BF043` destructuring warning:
+For initial-value-only props, default parameter syntax works — destructuring is fully
+reactive (see [Props Reactivity](../reactivity/props-reactivity.md)), so there is nothing to
+suppress:
 
 ```tsx
-// @bf-ignore props-destructuring
 function Counter({ initial = 0 }: { initial?: number }) {
   const [count, setCount] = createSignal(initial)
   return <button onClick={() => setCount(n => n + 1)}>{count()}</button>

package/dist/docs/core/quick-start.mdx

@@ -88,7 +88,7 @@ export function Counter(props: CounterProps) {
 }
 ```
 
-See [Client Directive](./rendering/client-directive.md), [`createSignal`](./reactivity/create-signal.md), and [`createMemo`](./reactivity/create-memo.md) for what each piece does. Props are read via `props.initial`, not destructured — destructuring captures the value once and breaks reactivity, so the compiler emits warning [`BF043`](./advanced/error-codes.md) when it sees that form on a `"use client"` component. [Props Reactivity](./reactivity/props-reactivity.md) covers the full rule.
+See [Client Directive](./rendering/client-directive.md), [`createSignal`](./reactivity/create-signal.md), and [`createMemo`](./reactivity/create-memo.md) for what each piece does. Props are read via `props.initial` here, but destructuring them in the function parameter (`function Counter({ initial }: CounterProps)`) works identically — both forms compile to the same live read, so pick whichever reads better. [Props Reactivity](./reactivity/props-reactivity.md) covers the full rule.
 
 The Counter is mounted in `server.tsx`:
 

package/dist/docs/core/reactivity/props-reactivity.md

@@ -5,10 +5,13 @@ description: How prop access patterns determine whether reactive updates propaga
 
 # Props Reactivity
 
-**How you access props determines whether updates propagate.** The compiler wraps dynamic prop expressions in getters.
+**`props.xxx` access, destructuring the props parameter, and destructuring the props object
+inside the function body are all equally reactive.** The compiler wraps dynamic prop
+expressions in getters, and every value-position read of a prop — written any of the three
+ways — compiles to a live read of that getter.
 
 
-## Direct Access — Reactive
+## Direct Access
 
 `props.xxx` maintains reactivity. Each access calls the underlying getter:
 
@@ -22,55 +25,87 @@ function Display(props: { value: number }) {
 ```
 
 
-## Destructuring — Captures Once
+## Destructuring In The Parameter
 
-Destructuring calls the getter once and stores the result. The value does not update:
+Destructuring the props **parameter** is also fully reactive. Every reference to a
+destructured prop name — in a `createEffect` body, a `createMemo` computation, an event
+handler, a reactive attribute, plain text, anywhere — compiles to the same live read
+`props.xxx` would:
 
 ```tsx
 function Display({ value }: { value: number }) {
   createEffect(() => {
-    console.log(value) // Stale — captured at component init
+    console.log(value) // Re-runs when parent updates value
   })
   return <span>{value}</span>
 }
 ```
 
-The compiler emits `BF043` when it detects props destructuring in a client component:
+There is no local variable holding a stale, captured-at-mount copy — `value` above compiles
+to a live read of the parent's getter at every reference site, the same as `props.value`
+would. A destructure default (`{ value = 0 }`) is evaluated live too: it re-applies on every
+read, not just once at mount.
 
-```
-warning[BF043]: Props destructuring breaks reactivity
-
-  --> src/components/Display.tsx:1:18
-   |
- 1 | function Display({ value }: { value: number }) {
-   |                  ^^^^^^^^^
-   |
-   = help: Access props via `props.value` to maintain reactivity
+
+## Destructuring In The Body
+
+Destructuring inside the function body is also fully reactive, as long as the destructured
+name is a **pure alias** of a single prop — nothing computed from it:
+
+```tsx
+function Display(props: { value: number }) {
+  const { value } = props
+  createEffect(() => {
+    console.log(value) // Re-runs when parent updates value
+  })
+  return <span>{value}</span>
+}
 ```
 
-Suppress with `@bf-ignore` when capturing intentionally (e.g., initial values):
+The compiler recognizes `const { value } = props` (and the equivalent `const value =
+props.value`) as a pure passthrough, drops the local extraction entirely, and rewrites every
+reference to `value` to a live `props.value` read instead — the same rewrite the parameter
+form gets. A destructure default (`const { value = 0 } = props`) and a renamed binding
+(`const { value: v } = props`) are both covered the same way.
+
+This does NOT apply once the local does its own computation, or is reassigned:
 
 ```tsx
-// @bf-ignore props-destructuring
-function Counter({ initial }: { initial: number }) {
-  const [count, setCount] = createSignal(initial)
-  return <button onClick={() => setCount(n => n + 1)}>{count()}</button>
+function Display(props: { value: number }) {
+  const { value } = props
+  const doubled = value * 2 // `doubled` is an ordinary once-evaluated local
+  let { count } = props
+  count += 1               // `count` is reassigned, so it can't be a live alias either
+  return <span>{doubled}</span>
 }
 ```
 
+`doubled` is a real computation, not a passthrough — it is an ordinary local, evaluated once
+at its declaration (same as it would be with any other access pattern). A `let` binding is
+never treated as a live alias, since rewriting a later assignment to it would mean silently
+writing through to the caller's prop.
 
-## When Destructuring Is Safe
 
-Destructuring is safe for **initial values** of local state and for values that never change (`id`, static labels).
+## When To Prefer Which
+
+The three reactive forms — `props.xxx`, parameter destructuring, and body destructuring —
+behave identically at runtime, so the choice between them is style, not correctness:
+
+- Destructuring (parameter or body) reads naturally and is usually the better default for
+  components with a handful of named props.
+- `props.xxx` avoids repeating a long prop list at the call site, and is the natural fit for
+  a component that mostly forwards its props (`...rest`) rather than naming each one.
 
 
 ## Summary
 
-| Pattern | Reactive? | Use when |
-|---------|-----------|----------|
-| `props.value` | Yes | You need live updates from parent |
-| `const { value } = props` | No | Value is used once (e.g., initial state) |
-| `createSignal(props.value)` | `props.value` is reactive, signal is independent | Creating local state from a prop |
+| Pattern | Reactive? |
+|---------|-----------|
+| `props.value` | Yes |
+| `function C({ value }: Props)` — parameter destructuring | Yes |
+| `const { value } = props` — body destructuring (pure alias) | Yes |
+| `const doubled = value * 2` — a computation, not a pure alias | No, evaluated once at declaration (same as any other once-evaluated local) |
+| `createSignal(props.value)` | `props.value` is reactive, the signal it seeds is independent thereafter |
 
 
 ## How It Works
@@ -85,7 +120,10 @@ The compiler transforms dynamic prop expressions into getters:
 { get value() { return count() } }
 ```
 
-- `props.value` → calls getter → calls `count()` → dependency tracked
-- `const { value } = props` → calls getter once → stores the number → no further tracking
-
-This is the same model as SolidJS. If you are coming from React, this is the key behavioral difference.
+`props.value` calls the getter directly. A `value` destructured in the PARAMETER, or aliased
+by a pure body destructure, compiles to the exact same getter call at every reference site —
+the compiler rewrites each one, rather than binding a plain local that would only read the
+getter once. This is the same reactive-getter model as SolidJS; unlike SolidJS, BarefootJS
+performs that rewrite for both the parameter form and the body-alias form, so there is no
+"don't destructure props" caveat left — only the ordinary rule that a real computation
+(`value * 2`) is evaluated once, same as it would be anywhere else in the function.