@barefootjs/cli 0.35.4 → 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/adapters/hono-adapter.md

@@ -126,7 +126,7 @@ export function Counter(__allProps: { initial?: number } & { __instanceId?: stri
 A build-time post-processing step injects `useRequestContext()` calls into generated templates. `BfScripts` renders the collected `<script>` tags:
 
 ```tsx
-import { BfScripts } from '@barefootjs/hono'
+import { BfScripts } from '@barefootjs/hono/scripts'
 
 export function Layout({ children }) {
   return (
@@ -212,3 +212,158 @@ export default defineConfig({
   }),
 })
 ```
+
+## Adding to an Existing Project
+
+`npm create barefootjs@latest` scaffolds the layout above from scratch; this section retrofits it onto an existing Hono + Cloudflare Workers app that already renders with `hono/jsx-renderer` and deploys with `wrangler deploy`. The end state is the same as the scaffold's, so a freshly scaffolded project is a valid reference to diff against when something doesn't line up.
+
+### What changes
+
+`barefoot()` compiles **individual components** — each `.tsx` under `components` becomes an SSR template under `templates` plus hydration JS under `build.outDir`. It never bundles the server app into a single file. For a project that currently does that with a whole-app Vite bundler (e.g. `@hono/vite-build`), the consequence is:
+
+| | Before | After |
+|---|---|---|
+| Server build | Bundler plugin emits a single-file SSR bundle | Step removed; nothing replaces it |
+| `wrangler.jsonc` `main` | The pre-bundled output | The uncompiled entry file — wrangler's own esbuild bundles it at dev/deploy time |
+| `vite build` | Produces the server bundle | Produces compiled templates + hydration JS only |
+
+`barefoot()` takes the bundler plugin's place in `vite.config.ts`, and any `package.json` script or CI step that referenced the old bundle path goes with it.
+
+**Paths in this section are the scaffold's** (`components/`, `dist/components`, `public/components`, `server.tsx`, `renderer.tsx`). Substitute your own. Two that are easy to copy literally by mistake:
+
+- `wrangler.jsonc` `main` must be your app's actual Hono entry file (e.g. `src/index.tsx`). Copying `server.tsx` as-is fails immediately with `The entry-point file at "server.tsx" was not found`.
+- `import { renderer } from './renderer'` assumes `jsxRenderer` lives in its own module, as in the scaffold. If yours is defined inline in the entry file, edit it there and skip the import — there's no need to split it out.
+
+### 1. Install
+
+```sh
+npm install @barefootjs/client @barefootjs/hono @barefootjs/jsx @barefootjs/shared
+npm install -D @barefootjs/vite
+```
+
+> **Peer dependencies.** `@barefootjs/hono` peer-depends on `vite ^6.0.0` and `@barefootjs/jsx` on `typescript ^5.0.0`. A project already on a newer major of either (e.g. `vite@8`, `typescript@7`) fails `npm install` with an `ERESOLVE` error. Either install with `--legacy-peer-deps` or pin `typescript` to `^5`. The `typescript` range is the one that matters: a newer `vite` alone works in practice, but a newer `typescript` makes `vite build` crash at config-load time with `TypeError: ts.createPrinter is not a function` — an opaque runtime error, not a version check — because `@barefootjs/vite` calls the `typescript` package's compiler API directly.
+
+### 2. Config files
+
+#### `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@barefootjs/hono/jsx",
+    "baseUrl": ".",
+    "paths": {
+      "@/components/*": ["./dist/components/*", "./components/*"]
+    }
+  },
+  "exclude": ["node_modules", "dist/components"]
+}
+```
+
+`@/components/*` has two targets, tried in order by both TypeScript and wrangler: the compiled SSR template under `dist/components/` (carrying the hydration markers from Output Format above) whenever it exists, otherwise the raw source under `components/` so editor tooling and type-checking resolve before the first build. Excluding `dist/components` keeps the compiled copy out of type-checking. Everything else already in `compilerOptions` (`types`, `strict`, …) stays as it is.
+
+#### `vite.config.ts`
+
+```ts
+// vite.config.ts
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+import { barefoot } from '@barefootjs/hono/vite'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+export default defineConfig({
+  // Public URL prefix of the client build. Must match the path Workers
+  // Assets serves `build.outDir` under (wrangler.jsonc below).
+  base: '/components/',
+  resolve: {
+    // Required, not optional: Vite's dev-server dependency pre-scan runs
+    // before this plugin's `transform` hook and ignores tsconfig `paths`.
+    // Points at the SOURCE tree, never at `dist/components`.
+    alias: {
+      '@/components': resolve(HERE, 'components'),
+    },
+  },
+  // `build.outDir` sits inside `public/`, which Workers Assets already
+  // serves as-is. Vite's default `publicDir` would copy the rest of
+  // `public/` into `public/components` on every build for nothing.
+  publicDir: false,
+  build: {
+    outDir: 'public/components',   // hydration JS → served by Workers Assets
+    emptyOutDir: true,
+  },
+  plugins: barefoot({
+    components: ['components'],    // .tsx source directories to compile
+    templates: 'dist/components',  // compiled SSR templates → imported by the server, never served
+  }),
+})
+```
+
+Everything not shown (hashing, chunking, minification, dev server) is stock Vite. `adapterOptions`, `assets`, and `assetsOutputFile` (see Options above) are not needed for a retrofit.
+
+#### `wrangler.jsonc`
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "my-app",
+  // Your existing uncompiled Hono entry (see "Paths" above). Wrangler
+  // bundles it and follows the tsconfig `paths` mapping into dist/components/.
+  "main": "server.tsx",
+  "compatibility_date": "2025-01-01",
+  // Must cover `build.outDir` from vite.config.ts and must not include
+  // `templates` — see Deploying to Cloudflare Workers above.
+  "assets": {
+    "directory": "./public"
+  }
+}
+```
+
+### 3. Wire the app
+
+**Render `<BfScripts />` once** (from `@barefootjs/hono/scripts`) in the layout your `jsxRenderer` already defines — not inside individual components. It emits the `<script>` tags loading each compiled component's hydration JS exactly once per page, however many instances are rendered (see Script Collection above). Existing `ContextRenderer` augmentation and stylesheet links stay as they are.
+
+```tsx
+import { jsxRenderer } from 'hono/jsx-renderer'
+import { BfScripts } from '@barefootjs/hono/scripts'
+
+export const renderer = jsxRenderer(({ children, title }) => (
+  <html lang="en">
+    <head>
+      <meta charset="UTF-8" />
+      <title>{title ?? 'My app'}</title>
+    </head>
+    <body>
+      {children}
+      <BfScripts />
+    </body>
+  </html>
+))
+```
+
+**Import components through the alias**, not a relative path into the source tree, so the dist-first resolution from `tsconfig.json` applies:
+
+```tsx
+// server.tsx
+import { Hono } from 'hono'
+import { renderer } from './renderer'
+import { Counter } from '@/components/Counter'
+
+const app = new Hono()
+app.use('*', renderer)
+app.get('/', (c) => c.render(<main><Counter /></main>, { title: 'My app' }))
+export default app
+```
+
+Existing plain Hono JSX components can stay put and move under `components/` one at a time — only files under a configured `components` directory are compiled.
+
+### 4. Build and verify
+
+```sh
+npx vite build      # writes dist/components/ (templates) and public/components/ (hydration JS)
+npx wrangler dev    # or: npx wrangler deploy
+```
+
+Load a page that renders a converted `"use client"` component: its element carries a `bf` marker attribute (see Output Format above) and it responds to interaction. During development, run `vite dev` alongside `wrangler dev` so `dist/components/` keeps regenerating on change.

package/dist/docs/core/adapters.md

@@ -18,16 +18,20 @@ JSX Source
 
 ## Available Adapters
 
-| Adapter | Output | Backend | Package |
-|---------|--------|---------|---------|
-| [`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` |
+<!-- ADAPTER-TABLE:START (auto-generated by scripts/generate-adapter-docs.ts — do not edit by hand) -->
+| Language | Backend | Package |
+|----------|---------|---------|
+| TypeScript | [Hono](./adapters/hono-adapter.md) | `@barefootjs/hono` |
+| Go | [html/template](./adapters/go-template-adapter.md) | `@barefootjs/go-template` |
+| Perl | [Mojolicious](./adapters/perl-adapter.md) | `@barefootjs/mojolicious` |
+| Perl | [Text::Xslate](./adapters/perl-adapter.md) | `@barefootjs/xslate` |
+| Ruby | [ERB](./adapters/ruby-adapter.md) | `@barefootjs/erb` |
+| Python | [Jinja2](./adapters/python-adapter.md) | `@barefootjs/jinja` |
+| PHP | [Twig](./adapters/php-adapter.md) | `@barefootjs/twig` |
+| PHP | [Laravel Blade](./adapters/php-adapter.md) | `@barefootjs/blade` |
+| Rust | [minijinja](./adapters/rust-adapter.md) | `@barefootjs/rust` |
+| — | [CSR (browser only)](./adapters/csr.md) | `@barefootjs/client` |
+<!-- ADAPTER-TABLE:END -->
 
 > 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.
 

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/core-concepts/backend-freedom.md

@@ -13,19 +13,21 @@ BarefootJS compiles JSX at build time into your backend's native template format
 JSX → IR (backend-agnostic) → Adapter → Template
 ```
 
-| Language | Adapter | Notes |
-|----------|---------|-------|
-| TypeScript | [HonoAdapter](../adapters/hono-adapter.md) | Hono / JSX-based TS servers |
-| TypeScript | [TestAdapter](https://github.com/piconic-ai/barefootjs/tree/main/packages/test) | IR-based component testing |
-| Go | [GoTemplateAdapter](../adapters/go-template-adapter.md) | `html/template` |
-| Perl | [MojoliciousAdapter](https://github.com/piconic-ai/barefootjs/tree/main/packages/adapter-mojolicious) | Mojolicious EP templates |
-
-### Planned
-
-| Language | Adapter |
-|----------|---------|
-| Rust | (TBD) |
-| Python | Jinja2Adapter |
-| Ruby | ERBAdapter |
+<!-- ADAPTER-TABLE:START (auto-generated by scripts/generate-adapter-docs.ts — do not edit by hand) -->
+| Language | Backend | Package |
+|----------|---------|---------|
+| TypeScript | [Hono](../adapters/hono-adapter.md) | `@barefootjs/hono` |
+| Go | [html/template](../adapters/go-template-adapter.md) | `@barefootjs/go-template` |
+| Perl | [Mojolicious](../adapters/perl-adapter.md) | `@barefootjs/mojolicious` |
+| Perl | [Text::Xslate](../adapters/perl-adapter.md) | `@barefootjs/xslate` |
+| Ruby | [ERB](../adapters/ruby-adapter.md) | `@barefootjs/erb` |
+| Python | [Jinja2](../adapters/python-adapter.md) | `@barefootjs/jinja` |
+| PHP | [Twig](../adapters/php-adapter.md) | `@barefootjs/twig` |
+| PHP | [Laravel Blade](../adapters/php-adapter.md) | `@barefootjs/blade` |
+| Rust | [minijinja](../adapters/rust-adapter.md) | `@barefootjs/rust` |
+| — | [CSR (browser only)](../adapters/csr.md) | `@barefootjs/client` |
+<!-- ADAPTER-TABLE:END -->
+
+TypeScript also has an [IR-based `TestAdapter`](https://github.com/piconic-ai/barefootjs/tree/main/packages/test) for browser-free component testing — it isn't a serving-time backend, so it's outside the table above. See [Adapters](../adapters.md) for the full picture, including which adapters share one engine-agnostic runtime.
 
 The IR contract is stable. You can [write a custom adapter](../adapters/custom-adapter.md) for any backend.

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.