unplugin-react-fine-grained-signals 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 akazawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,250 @@
+# unplugin-react-fine-grained-signals
+
+[English](README.md) | [日本語](README.ja.md)
+
+[`react-fine-grained-signals`](https://www.npmjs.com/package/react-fine-grained-signals)（npmへまだ公開されていません）
+向けの、`useSignals()` 自動挿入と任意のmanaged render scope変換を提供する汎用
+bundler integrationです。
+
+このpackageは意図的に唯一のbuild-time integrationです。Babel実装は内部に
+閉じ込め、利用側はbundlerごとのentry pointだけを設定します。
+
+## インストール
+
+```sh
+pnpm add -D unplugin-react-fine-grained-signals
+```
+
+`react-fine-grained-signals` はpeer dependencyです。このpackageはESM-onlyです。
+CommonJSの`require()`ではなく、ESM設定から`import`してください。
+
+## Vite
+
+```ts
+import { defineConfig } from "vite";
+import signals from "unplugin-react-fine-grained-signals/vite";
+
+export default defineConfig({
+  plugins: [signals({ mode: "auto" })],
+});
+```
+
+## その他のbundler
+
+対応するentry pointを同様の要領で使用します。
+
+| Bundler | Entry point |
+| --- | --- |
+| Rollup | `unplugin-react-fine-grained-signals/rollup` |
+| Webpack | `unplugin-react-fine-grained-signals/webpack` |
+| Rspack | `unplugin-react-fine-grained-signals/rspack` |
+| esbuild | `unplugin-react-fine-grained-signals/esbuild` |
+
+```ts
+import signals from "unplugin-react-fine-grained-signals/webpack";
+
+export default {
+  plugins: [signals({ mode: "auto" })],
+};
+```
+
+## オプション
+
+- `mode`
+  - `"manual"`: 先頭文にあるimport済みの `useSignals()`、または
+    `@useSignals` を付けた名前付きcomponent/custom hookだけを変換します。
+  - `"auto"`（既定）: さらに `.value` を読む名前付きJSX componentと
+    名前付き `useX` custom hookを変換します。
+  - `"all"`: さらにすべての名前付きJSX componentを変換します。ネストした
+    callbackの読み取りは親componentが収集しますが、callback自体は変換しません。
+- `transform`
+  - `"managed"`（既定）: 厳密な `try` / `finally` 境界を追加します。
+    `/runtime` からimportし、componentの関数がreturnする時点でrender
+    tracking windowを同期的に閉じます。
+  - `"inject"`: best-effortなopt-in向けに変換なしの `useSignals()` を
+    追加します。制御フローを書き換えず、通常の `useSignals()` を先頭hook
+    として挿入するため、手書きと同じbest-effort境界になります。この
+    modeが露呈し得るsibling誤帰属の既知の制約については、
+    [境界設計の検討docs](../../docs/design/use-signals-boundary-design.ja.md)
+    を参照してください。
+- `reactCompiler`
+  - `"auto"`（既定）: 変換したすべての関数に `"use no memo"` を付け、render
+    trackingが必要とするsignal読み取りをReact Compilerがmemoizationで
+    消さないようにします。付けない場合、compile済みcomponentはJSXをcacheし、
+    最初のsignal書き込み以降、無言で更新が止まります。
+  - `"off"`: directiveを付けません。React Compilerをbuildで使っていない場合か、
+    対象componentを[互換性の検討docs](../../docs/design/react-compiler-compatibility.ja.md)
+    に照らして確認済みの場合だけ選んでください。
+- `importSource`: `react-fine-grained-signals` 互換wrapperへの置き換えです。
+- `reactImportSource`: wrapされた関数をcomponentと判定する際に、`memo` /
+  `forwardRef` をReact由来とみなすmodule specifierを追加します。置き換えでは
+  なく追加であり、`"react"` からのdirect importは常に認識されます。つまり
+  設定しても既存のdirect importの認識が外れることはありません。
+- `include` / `exclude`: source module IDを絞る関数です。
+
+## Render callbackの検出
+
+自動検出はrender callback（配列のiteration method `map`、`flatMap`、`forEach`
+へ渡す関数）を変換しません。呼び出し元の1回のrenderの中で実行回数が変わるため、
+Rules of Hooksに反するからです。認識するのは、定義箇所にinlineで書いた場合
+（`items.map((item) => …)`）、変数に切り出してその束縛名で参照して渡す場合
+（`const` の `const Row = …; items.map(Row)` でも、function宣言の
+`function Row() {…}` … `items.map(Row)` でも）、およびそれぞれのoptional
+chaining形（`items?.map(Row)`）です。こうしたcallback自体は変換せず、そのJSXと
+`.value` 読み取りは呼び出し元のcomponentが収集します。callbackが同じmodule内の
+別の場所で定義されている場合も同様で、呼び出し元componentの本体自体がsignalを
+読んでいなくても、そのcomponentが変換対象になります。
+
+対象objectの実行時の型はbuild時にはわからないため、判定材料はmethod名だけです。
+そのため認識する集合は意図的に最小限にしています。`map` と `flatMap` は要素ごとに
+elementを組み立て、`forEach` は蓄積用の配列へelementを積む呼び出しで、callbackを
+component風の名前で切り出す典型がこの3つです。述語・畳み込み系（`filter`、
+`reduce`、`find`、`some`、`every`）は意図的に除外しています。これらのcallbackは
+そもそも変換対象にならない小文字のhelperであり、含めても得るものがない一方、
+同名の無関係なmethodに誤って一致する余地だけが広がるからです。しかもその向きの
+誤りのほうが高くつきます。実在のcomponentからsubscriptionを無言で奪うためです。
+したがって、それ以外の呼び出しへ名前で渡す参照は通常のcomponent登録として扱い、
+変換対象のままにします。従来どおりの `memo(Row)` / `forwardRef(Row)` に加えて、
+`observer(Row)` や `connect(…)(Row)` のようなサードパーティのwrapperも同じです。
+これらが返すcomponentは、Reactが独自のfiberとして、独自のhook contextで
+instance化します。同じ登録はinlineで書いても機能します。関数自身が
+PascalCaseの名前を持っていればよく、`observer(function Row() { … })` は
+`observer(Row)` とまったく同様に認識されます。同じ形でもanonymousな関数や
+arrow関数（`observer((props) => …)`）は、boundaryを結び付けるための名前を
+持たないため、変換されないままです。
+
+この検出には既知の制約が4つあります。
+
+- 再代入したaliasはたどりません。`const RowAlias = Row; items.map(RowAlias)`
+  経由で渡したPascalCaseのhelperは、componentとして扱われたままになります。
+- JSXのprop値として渡すrender callbackは認識しません。`<Grid renderItem={Row} />`
+  は、`Grid` が1回のrenderで `renderItem(item)` を可変回数呼ぶ場合（render prop。
+  hook挿入は安全ではありません）でも、`Row` を独立したcomponentとしてinstance化
+  する場合（hook挿入こそが更新を成立させます）でも構文が同一で、そのファイルだけ
+  では区別できません。そのため `Row` は、単独で変換条件を満たすなら自分のhookを
+  持ったままになります。呼び出し箇所にcallbackをinlineで書くか
+  （`<Grid renderItem={(item) => <li>{item.value}</li>} />`。上記のinline検出が
+  呼び出し元componentに正しく帰属させます）、参照先の関数に `@useSignals` /
+  `@noUseSignals` コメントで意図を明示してください。
+- 別moduleからimportしたcallbackはたどりません。変換は1ファイルずつ処理する
+  ためです。
+- 2つの役割を兼ねる関数は、除外されたままになります。`Row` をmodule内のどこかで
+  `map` / `flatMap` / `forEach` に渡していて、なおかつ別の場所でJSXタグとして
+  単独でrenderしている（`<Row item={x} />`）場合、render callbackとしての用法が
+  優先され、`Row` は自分のhookを持ちません。これはクラッシュしない側の選択です
+  （hookを持たせると、callbackとしての用法でhookの順序が壊れます）。ただし単独で
+  renderされるほうはsubscriptionを持たないため、以降のsignalの書き換えで
+  内容が古いままになります。役割ごとに別名の2つの関数へ分けるか、単独で
+  renderするほうの関数を `@useSignals` コメントで明示的にopt-inしてください。
+
+判断に迷う場合は、そうしたhelperを明示的に保ってください。小文字で `use`
+始まりでない名前にするか、実際にcomponentとしてrenderされるときにだけ手動で
+opt-inします。
+
+## Higher-order component (HOC)
+
+higher-order component（HOC）が返すcomponentは、自分自身の名前を持たなくても
+認識します。
+
+```jsx
+export const withCount = (Base) => (props) => <Base {...props} count={count.value} />;
+```
+
+ここでcomponentは内側の関数であり、その識別子はfactory自身のbinding
+（`withCount`）から継承します。したがって `auto` modeはこれをsubscribeし、
+`@useSignals`（`@noUseSignals` も同様）コメントは、返される関数側とfactoryの
+宣言側のどちらに書いても適用されます。通常のclosureを巻き込まないための条件は
+3つです。囲む関数から直接returnされていること（明示的な `return`、または
+arrowの簡潔なbody）、返される関数自身がJSXをrenderしていること、そして囲む
+関数の名前がhookの名前（`useX`）でないこと — あるいはcomponentの名前
+（PascalCase）である場合は、その囲む関数自身が後述のhigher-order component
+factoryの条件を満たしていることです。その条件を満たさないcomponentが返す
+関数、またはhookが返す関数は、そのownerのrender内で動くrender propであって、
+独立したcomponentではありません。
+
+PascalCaseの名前を持つfactoryは、componentらしきものを自分の引数として
+受け取り — destructureされていない、PascalCaseの名前を持つ単なる識別子の
+引数 — 、かつ自分自身はJSXをrenderしない場合に該当します。
+
+```jsx
+export const WithCount = (Base) => (props) => <Base {...props} count={count.value} />;
+```
+
+`WithCount` 自体は変換されません。返されるcomponentは、上記のcamelCase形と
+まったく同様に `WithCount` の名前を継承します。`useX` という名前のfactoryが
+返すclosureには、これに相当する例外は意図的にありません。Reactはすでに進行中の
+renderの中からhookを呼び出すため、そのhookが返すものはまさにそのrender中に
+呼び出される可能性があり、それを否定する材料がここには何もないからです。
+このことはhook自体には影響しません。hookそのものは、signalを読む・JSXを
+renderするといった条件を満たす限り、他のhookとまったく同様に変換対象のまま
+です。名前を継承しないのは、返されるclosureだけです。
+
+名前の継承はちょうど1段だけたどるため、factoryを返すfactory
+（`(a) => (b) => (props) => …`）は解決せず、そこに書いた `@useSignals` コメントは
+無言で消えるのではなく警告として報告されます。唯一区別できない形は、factoryの
+戻り値をそのままiteration methodへ渡す場合（`items.map(makeRow(prefix))`）です。
+これは構文上componentを返すHOCそのものなので、独自のboundaryを持ちます。その
+ようなcallbackは参照で渡すか（`items.map(Row)`）、inlineで書いて呼び出し元の
+componentに収集させてください。
+
+componentは、自分自身のbindingを持たなくても名前を得られる場合があります。
+objectやclassのproperty — `Card.Header = () => <p>{count.value}</p>` や、
+`class Holder { Row = () => <p>{count.value}</p> }` のようなfield — として
+保持されているcomponentは、`<Card.Header />` や `<ns.Row />` がそこへ到達する
+のと同じ、そのkeyから名前を得ます（小文字のkeyは、小文字のbindingと同様に
+除外されたままです）。また、名前を持たないdefault export
+（`export default (props) => <p>{count.value}</p>`）は、moduleのファイル名から
+名前を得ます。これは `import App from "./App"` が実際にそのcomponentへ与えて
+いる識別子そのものです。ただし、class内での `this.Row = …` という代入
+（たとえばconstructor内）は意図的に対象外です。そうした `this` を束縛する
+rendererには、この機能が存在する以前と同様、明示的な `useSignals()` 呼び出し
+か `@useSignals` コメントが必要です。
+
+## `memo` / `forwardRef` の認識
+
+`memo` / `forwardRef` の自動認識は、`"react"` または `reactImportSource` から
+のdirect importだけに一致します。ローカルのbarrelやre-export module経由の
+import（`import { memo } from "./some-local-module"`）は、その moduleが最終的に
+`"react"` をre-exportしていても解決しません。変換は1ファイルずつ処理し、
+re-exportの連鎖をたどらないためです。認識できなかった場合もエラーにはならず、
+そのcomponentは無言でスキップされるため、signalを書き換えても再renderされなく
+なります。回避策は次の3つです。
+
+- 単一の安定したmodule pathでimportしているなら、`reactImportSource` にその
+  specifierを設定する（`"@app/react"` のようなbare specifierはどのファイルでも
+  一致します。相対pathは同じ綴りのファイルにしか一致しません）。
+- 該当箇所で `memo` / `forwardRef` を `"react"` から直接importする。
+- `@useSignals` コメントか手書きの `useSignals()` 呼び出しで明示的にopt-inする。
+
+## `useSignals()` のopt-inと書き換え
+
+`@useSignals` と `@noUseSignals` は、その関数だけに適用されます。pluginが
+二重の `useSignals()` 呼び出しを挿入することはありません。既存のdirect
+import、namespace import、barrel import経由の呼び出しは、その関数のopt-inと
+みなします。先頭文でない呼び出しと、barrel import経由の呼び出しは、いずれの
+変換モードでもそのまま残ります。`importSource` からdirect importまたは
+namespace importした先頭文の呼び出しは、`"inject"` ではそのまま残りますが、
+`"managed"`（既定）では生成する境界に吸収されます。つまりその文は削除され、
+managed storeの宣言と `try` / `finally` scopeに置き換わるため、関数本体は
+そのまま残るのではなく書き換えられます。
+
+先頭文での `useSignals()` 呼び出しが `async` 関数やgenerator関数の中にあると、
+既定の `"managed"` 変換ではbuildが失敗し、
+`useSignals transform only supports synchronous, non-generator functions`
+というエラーになります。この組み合わせはそもそもReactとして不正です
+（hookは同期のfunction componentを必要とします）。関数側を直すのが望ましく、
+どうしても現状のままbuildを通す必要がある場合は `transform: "inject"` を
+使うと、関数を書き換えずにこの呼び出しを受け入れます。
+
+## Buildへの組み込み
+
+いずれの変換モードも再適用するとno-opです。この変換は、対応するbundler
+（Vite、webpack、Rspack）では `enforce: "pre"` によって他のplugin変換より
+先に実行されます。Rollupにはこの概念がないため、このpluginを最初にlistして
+ください。また、依存関係やJavaScript/TypeScript以外のmoduleはskipします。
+`.ts` はJSXなしのTypeScriptとして、`.tsx`、`.jsx`、JavaScriptはJSXを含めて
+解析します。
+
+## License
+
+MIT © akazawa。[LICENSE](LICENSE) を参照してください。

package/README.md

@@ -0,0 +1,261 @@
+# unplugin-react-fine-grained-signals
+
+[English](README.md) | [日本語](README.ja.md)
+
+Universal bundler integration for automatic `useSignals()` insertion and the
+optional managed render-scope transform in
+[`react-fine-grained-signals`](https://www.npmjs.com/package/react-fine-grained-signals) (not yet published to npm).
+
+This package is deliberately the only build-time integration. It keeps the
+Babel implementation private, so application configuration is the same across
+supported bundlers.
+
+## Installation
+
+```sh
+pnpm add -D unplugin-react-fine-grained-signals
+```
+
+`react-fine-grained-signals` is a peer dependency. This package is ESM-only:
+use an ESM build configuration and `import`, not CommonJS `require()`.
+
+## Vite
+
+```ts
+import { defineConfig } from "vite";
+import signals from "unplugin-react-fine-grained-signals/vite";
+
+export default defineConfig({
+  plugins: [signals({ mode: "auto" })],
+});
+```
+
+## Other bundlers
+
+Use the matching entry point in the same way:
+
+| Bundler | Entry point |
+| --- | --- |
+| Rollup | `unplugin-react-fine-grained-signals/rollup` |
+| Webpack | `unplugin-react-fine-grained-signals/webpack` |
+| Rspack | `unplugin-react-fine-grained-signals/rspack` |
+| esbuild | `unplugin-react-fine-grained-signals/esbuild` |
+
+```ts
+import signals from "unplugin-react-fine-grained-signals/webpack";
+
+export default {
+  plugins: [signals({ mode: "auto" })],
+};
+```
+
+## Options
+
+- `mode`:
+  - `"manual"`: only an explicit first-statement imported `useSignals()` call
+    or a `@useSignals` comment on a named component/custom hook opts it in.
+  - `"auto"` (default): additionally transforms named JSX components and
+    named `useX` custom hooks that read `.value`.
+  - `"all"`: additionally transforms every named JSX component. Nested
+    callbacks are collected by their owning component but are never transform
+    targets themselves.
+- `transform`:
+  - `"managed"` (default): adds an exact `try` / `finally` boundary, importing
+    from the package's `/runtime` entry and closing the render-tracking
+    window synchronously at the point the component function returns.
+  - `"inject"`: adds bare `useSignals()` for best-effort opt-in. It inserts a
+    normal `useSignals()` call without rewriting control flow, so it has the
+    same best-effort tracking boundary as a handwritten call — see
+    [the boundary design investigation](../../docs/design/use-signals-boundary-design.md)
+    for the known sibling-misattribution limitation this mode can expose.
+- `reactCompiler`:
+  - `"auto"` (default): marks every transformed function with `"use no memo"`,
+    so React Compiler does not memoize away the signal reads render tracking
+    depends on. Without it, a compiled component caches its JSX and silently
+    stops updating after the first signal write.
+  - `"off"`: omits the directive. Choose it only when React Compiler is not in
+    the build, or when the affected components were verified against
+    [the compatibility note](../../docs/design/react-compiler-compatibility.md).
+- `importSource`: overrides `react-fine-grained-signals` for a compatible wrapper.
+- `reactImportSource`: an additional module specifier whose `memo` and
+  `forwardRef` exports count as React's own when the plugin decides whether a
+  wrapped function is a component. Recognition is additive, not a replacement:
+  a direct import from `"react"` is always recognized, so setting this only
+  widens detection and never turns off an existing direct import.
+- `include` / `exclude`: functions that filter source module IDs.
+
+## Render callback detection
+
+Automatic detection never transforms a render callback — a function handed to
+one of the array iteration methods `map`, `flatMap`, or `forEach` — because it
+runs a variable number of times inside one render of its owner, which the Rules
+of Hooks forbid. Recognition covers the inline definition site
+(`items.map((item) => …)`), a callback factored out and referenced by its own
+binding, whether that binding is a `const` (`const Row = …; items.map(Row)`) or
+a function declaration (`function Row() {…}` … `items.map(Row)`), and the
+optional-chained form of either (`items?.map(Row)`). Such a callback is left
+alone, and its JSX and `.value` reads are collected by the component that
+invokes it — including when the callback is defined elsewhere in the same
+module, so that component is transformed even when its own body reads no
+signal.
+
+The method name is the whole signal here, because a build-time transform cannot
+know the object's runtime type. The recognized set is deliberately minimal:
+`map` and `flatMap` build an element per item and `forEach` pushes elements into
+an accumulator, which are the calls whose callbacks are routinely factored out
+under a component-shaped name. Predicate and accumulator methods (`filter`,
+`reduce`, `find`, `some`, `every`) are excluded on purpose — their callbacks are
+lowercase helpers that are never transform targets anyway, so including them
+would only widen the chance of matching an unrelated method of the same name,
+and that direction of error is the expensive one: it silently denies a real
+component its subscription. A reference passed to any other call is therefore
+ordinary component registration and stays eligible — `memo(Row)` and
+`forwardRef(Row)` as before, and equally third-party wrappers such as
+`observer(Row)` or `connect(…)(Row)`, where React instantiates the returned
+component as its own fiber with its own hooks. The same registration works
+written inline too, as long as the function keeps its own PascalCase name:
+`observer(function Row() { … })` is recognized exactly as `observer(Row)` is.
+An anonymous or arrow function passed the same way —
+`observer((props) => …)` — carries no name for a boundary to attach to, and is
+left untransformed.
+
+This detection has four known limitations:
+
+- A re-assigned alias is not followed, so a PascalCase helper reached through
+  `const RowAlias = Row; items.map(RowAlias)` is still treated as a component.
+- A render callback passed as a JSX prop value is not recognized.
+  `<Grid renderItem={Row} />` is syntactically identical whether `Grid` calls
+  `renderItem(item)` a variable number of times per render (a render prop,
+  where hook injection is unsafe) or instantiates `Row` as its own component
+  (where hook injection is what makes it update), and nothing in the file says
+  which — so `Row` keeps its own hook whenever it is independently eligible.
+  Prefer inlining the callback at the call site
+  (`<Grid renderItem={(item) => <li>{item.value}</li>} />`), which the inline
+  detection above already attributes to the owning component, or state the
+  intent explicitly on the referenced function with a `@useSignals` /
+  `@noUseSignals` comment.
+- A callback imported from another module is not followed, because the
+  transform sees one file at a time.
+- A function used in both roles keeps the exclusion. If `Row` is passed to
+  `map` / `flatMap` / `forEach` anywhere in the module and is *also* rendered
+  independently as a JSX tag (`<Row item={x} />`), the render-callback usage
+  wins: `Row` gets no hook of its own. That is the crash-safe direction — a
+  hook there would break hook order in the callback usage — but the
+  independently rendered instance then has no subscription and goes stale on
+  later signal writes. Split the two roles into two differently named
+  functions, one per role, or opt the independently rendered function in
+  explicitly with a `@useSignals` comment.
+
+When in doubt, keep such helpers explicit: name them lowercase and without a
+`use` prefix, or opt them in manually only when they are genuinely rendered as
+components.
+
+## Higher-order components
+
+A component a higher-order component returns is recognized even though it has no
+name of its own:
+
+```jsx
+export const withCount = (Base) => (props) => <Base {...props} count={count.value} />;
+```
+
+The inner function is the component here, and it inherits its identity from the
+factory's own binding — `withCount` — so `auto` mode subscribes it and a
+`@useSignals` (or `@noUseSignals`) comment on either the returned function or the
+factory's declaration applies to it. Three conditions keep ordinary closures out:
+the function must be returned directly by the enclosing function (an explicit
+`return`, or an arrow's concise body); the returned function must render JSX
+itself; and the enclosing function's name must not be a hook name (`useX`) — or,
+if it is a component name (PascalCase), the enclosing function must itself
+qualify as a higher-order component factory (described next). A function
+returned by a component that fails that test, or by a hook, is instead a render
+prop that runs inside that owner's render, not a component of its own.
+
+A PascalCase-named factory qualifies when it takes what looks like a component
+as its own parameter — a plain (not destructured) identifier parameter with a
+PascalCase name — and renders no JSX itself:
+
+```jsx
+export const WithCount = (Base) => (props) => <Base {...props} count={count.value} />;
+```
+
+`WithCount` is never transformed itself; the component it returns inherits
+`WithCount`'s name exactly as the camelCase form above does. A `useX`-named
+factory gets no equivalent exception for the closure it returns, deliberately:
+React calls a hook from inside a render already in progress, so anything the
+hook hands back may be invoked during that very render, and nothing here can
+rule that out. The hook itself is unaffected by this and is still transformed
+normally whenever it qualifies — reading a signal, rendering JSX — exactly like
+any other hook; only the returned closure inherits no name from it.
+
+The name is inherited from exactly one level out, so a factory returning a
+factory (`(a) => (b) => (props) => …`) resolves to nothing, and a `@useSignals`
+comment there reports that rather than silently doing nothing. The one shape
+this cannot tell apart is a factory whose result is handed straight to an
+iteration method (`items.map(makeRow(prefix))`): that is syntactically a HOC
+returning a component, so it gets a boundary of its own. Pass such a callback by
+reference (`items.map(Row)`) or write it inline, so the owning component
+collects it.
+
+A component can also carry no binding of its own and still be named: one held
+as an object or class property — `Card.Header = () => <p>{count.value}</p>`, or
+a `class Holder { Row = () => <p>{count.value}</p> }` field — is named by its
+key, the same way `<Card.Header />` or `<ns.Row />` reaches it (a lowercase key
+stays excluded, exactly as a lowercase binding does), and a nameless default
+export (`export default (props) => <p>{count.value}</p>`) is named after the
+module's own file — the identity an `import App from "./App"` already gives it.
+A `this.Row = …` assignment inside a class is deliberately excluded, though —
+such a `this`-bound renderer still needs an explicit `useSignals()` call or
+`@useSignals` comment, as before this feature existed.
+
+## `memo` / `forwardRef` recognition
+
+Automatic `memo` / `forwardRef` recognition matches only a direct import from
+`"react"` or from `reactImportSource`. Importing them through a local
+barrel or re-export module (`import { memo } from "./some-local-module"`) is
+not resolved automatically, even when that module ultimately re-exports from
+`"react"`: the transform sees one file at a time and does not follow re-export
+chains. An unrecognized wrapper is not an error — the component is silently
+skipped, so signal writes stop re-rendering it. Three workarounds:
+
+- set `reactImportSource` to that module's specifier, if the codebase imports
+  through one stable module path (a bare specifier such as `"@app/react"`
+  works everywhere; a relative path only matches files that spell it the same
+  way);
+- import `memo` / `forwardRef` directly from `"react"` at the affected call
+  sites;
+- opt the component in explicitly with a `@useSignals` comment or a manual
+  `useSignals()` call.
+
+## `useSignals()` opt-in and rewriting
+
+`@useSignals` and `@noUseSignals` apply only to their owning function; they do
+not affect nested functions. The plugin never adds a second `useSignals()`
+call: a direct, namespace, or barrel-imported call it finds is treated as the
+function's existing opt-in. A call that is not the function's first statement,
+and any barrel-imported call, is left alone in both transform modes. A
+first-statement call imported directly or as a namespace from `importSource` is
+left in place under `"inject"`, but under `"managed"` (the default) it is
+absorbed into the generated boundary: the statement is removed and replaced by
+the managed store declaration plus the `try` / `finally` scope, so the function
+body is rewritten rather than left byte-for-byte untouched.
+
+A first-statement `useSignals()` call inside an `async` or generator function
+fails the build under the default `"managed"` transform, with
+`useSignals transform only supports synchronous, non-generator functions`. That
+combination is already invalid React — hooks require a synchronous function
+component — so prefer fixing the function; `transform: "inject"` accepts it
+without rewriting the function, if the file must keep building unchanged.
+
+## Build integration
+
+Reapplying either transform mode is a no-op. The transform runs before other
+plugin transforms via `enforce: "pre"` on bundlers that support it (Vite,
+webpack, Rspack) — Rollup has no such concept, so list this plugin first there
+instead — and skips dependencies and non-JavaScript/TypeScript modules.
+Plain `.ts` files are parsed as TypeScript without JSX, while `.tsx`, `.jsx`,
+and JavaScript files may use JSX.
+
+## License
+
+MIT © akazawa. See [LICENSE](LICENSE).

package/dist/esbuild.d.ts

@@ -0,0 +1,10 @@
+import { a as createBundlerPlugin, c as resolveEsbuildLoader, d as ReactFineGrainedSignalsTransform, i as canTransform, l as ReactFineGrainedSignalsMode, n as EsbuildLoaderName, o as pluginName, r as ReactFineGrainedSignalsOptions, s as reactFineGrainedSignals, t as BundlerTransformOutput, u as ReactFineGrainedSignalsReactCompiler } from "./unplugin-CG9_mdcA.js";
+//#region src/esbuild.d.ts
+/** The plugin contract consumed by esbuild. */
+interface EsbuildPlugin {
+  name: string;
+  setup(build: unknown): void | Promise<void>;
+}
+declare const _default: (options?: ReactFineGrainedSignalsOptions) => EsbuildPlugin;
+//#endregion
+export { BundlerTransformOutput, EsbuildLoaderName, EsbuildPlugin, type ReactFineGrainedSignalsMode, ReactFineGrainedSignalsOptions, type ReactFineGrainedSignalsReactCompiler, type ReactFineGrainedSignalsTransform, canTransform, createBundlerPlugin, _default as default, pluginName, reactFineGrainedSignals, resolveEsbuildLoader };

package/dist/esbuild.js

@@ -0,0 +1,5 @@
+import { a as resolveEsbuildLoader, i as reactFineGrainedSignals, n as createBundlerPlugin, r as pluginName, t as canTransform } from "./unplugin-B2_q8KNi.js";
+//#region src/esbuild.ts
+var esbuild_default = createBundlerPlugin("esbuild");
+//#endregion
+export { canTransform, createBundlerPlugin, esbuild_default as default, pluginName, reactFineGrainedSignals, resolveEsbuildLoader };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { a as createBundlerPlugin, c as resolveEsbuildLoader, d as ReactFineGrainedSignalsTransform, i as canTransform, l as ReactFineGrainedSignalsMode, n as EsbuildLoaderName, o as pluginName, r as ReactFineGrainedSignalsOptions, s as reactFineGrainedSignals, t as BundlerTransformOutput, u as ReactFineGrainedSignalsReactCompiler } from "./unplugin-CG9_mdcA.js";
+export { BundlerTransformOutput, EsbuildLoaderName, type ReactFineGrainedSignalsMode, ReactFineGrainedSignalsOptions, type ReactFineGrainedSignalsReactCompiler, type ReactFineGrainedSignalsTransform, canTransform, createBundlerPlugin, reactFineGrainedSignals as default, reactFineGrainedSignals, pluginName, resolveEsbuildLoader };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as resolveEsbuildLoader, i as reactFineGrainedSignals, n as createBundlerPlugin, r as pluginName, t as canTransform } from "./unplugin-B2_q8KNi.js";
+export { canTransform, createBundlerPlugin, reactFineGrainedSignals as default, reactFineGrainedSignals, pluginName, resolveEsbuildLoader };

package/dist/loader.d.ts

@@ -0,0 +1,15 @@
+//#region src/loader.d.ts
+type LoaderCallback = (error: Error | null, content?: string, sourceMap?: unknown) => void;
+/** The slice of webpack's/rspack's loader context this loader uses. */
+interface LoaderContext {
+  async(): LoaderCallback;
+  query: unknown;
+  resource: string;
+  addDependency?: ((file: string) => void) | undefined;
+  getDependencies?: (() => string[]) | undefined;
+  emitWarning?: ((warning: Error) => void) | undefined;
+  emitError?: ((error: Error) => void) | undefined;
+}
+declare function reactFineGrainedSignalsLoader(this: LoaderContext, source: string, map?: unknown): void;
+//#endregion
+export { reactFineGrainedSignalsLoader as default };