unplugin-react-fine-grained-signals 0.1.0

package/dist/unplugin-B2_q8KNi.js

@@ -0,0 +1,1341 @@
+import { fileURLToPath } from "node:url";
+import { createUnplugin } from "unplugin";
+import { declare } from "@babel/helper-plugin-utils";
+import { transformSync } from "@babel/core";
+import * as t from "@babel/types";
+//#region src/internal/transform.ts
+const useSignalsComment = /(^|\s)@useSignals(\s|$)/;
+const noUseSignalsComment = /(^|\s)@noUseSignals(\s|$)/;
+const transformedMetadataKey = "reactFineGrainedSignalsTransformed";
+const noMemoDirective = "use no memo";
+const memoizationDirectives = /* @__PURE__ */ new Set([
+	"use memo",
+	"use forget",
+	"use no memo",
+	"use no forget"
+]);
+/** Adds the opt-out unless the author already stated a memoization choice. */
+function addNoMemoDirective(body) {
+	if (body.directives.some(({ value }) => memoizationDirectives.has(value.value))) return false;
+	body.directives.unshift(t.directive(t.directiveLiteral(noMemoDirective)));
+	return true;
+}
+function hasLeadingComment(path, pattern) {
+	return path.node.leadingComments?.some((comment) => pattern.test(comment.value)) ?? false;
+}
+function hasOwnedLeadingComment(path, pattern) {
+	let current = path;
+	while (current !== null && !current.isProgram()) {
+		if (hasLeadingComment(current, pattern)) return true;
+		if (current.isStatement()) {
+			const parent = current.parentPath;
+			return parent !== null && (parent.isExportNamedDeclaration() || parent.isExportDefaultDeclaration()) && hasLeadingComment(parent, pattern);
+		}
+		current = current.parentPath;
+	}
+	return false;
+}
+const reactPackageSource = "react";
+function isReactSource(source, reactImportSource) {
+	return source === reactPackageSource || source === reactImportSource;
+}
+/**
+* Resolves `name` back to the import specifier and source module it is bound
+* to, or `undefined` if `name` isn't bound by a value-level import at all
+* (not imported, a type-only specifier, or a type-only declaration).
+*
+* Every import-recognition predicate in this file -- React's `memo`/
+* `forwardRef` wrappers, a default-or-namespace React import, a named or
+* namespace `useSignals` import -- reduces to "does this resolved binding
+* have the right specifier kind and source", so they all build on this one
+* binding walk instead of each repeating
+* `getBinding` -> specifier-kind -> `importKind` -> parent-declaration.
+*/
+function resolveImportedBinding(path, name) {
+	const binding = path.scope.getBinding(name);
+	if (binding === void 0) return void 0;
+	const specifier = binding.path;
+	if (!specifier.isImportSpecifier() && !specifier.isImportDefaultSpecifier() && !specifier.isImportNamespaceSpecifier()) return;
+	if (specifier.isImportSpecifier() && specifier.node.importKind === "type") return void 0;
+	const declaration = specifier.parentPath;
+	if (!declaration.isImportDeclaration() || declaration.node.importKind === "type") return;
+	return {
+		specifier,
+		source: declaration.node.source.value
+	};
+}
+/** Is `name` bound by `import { memo } from "react"` (or `forwardRef`, possibly aliased)? */
+function isReactNamedImport(path, name, importedName, reactImportSource) {
+	const resolved = resolveImportedBinding(path, name);
+	if (resolved === void 0 || !resolved.specifier.isImportSpecifier()) return false;
+	return t.isIdentifier(resolved.specifier.node.imported, { name: importedName }) && isReactSource(resolved.source, reactImportSource);
+}
+/** Is `name` bound by `import * as React from "react"` or `import React from "react"`? */
+function isReactDefaultOrNamespaceImport(path, name, reactImportSource) {
+	const resolved = resolveImportedBinding(path, name);
+	return resolved !== void 0 && (resolved.specifier.isImportNamespaceSpecifier() || resolved.specifier.isImportDefaultSpecifier()) && isReactSource(resolved.source, reactImportSource);
+}
+function isKnownComponentWrapper(path, reactImportSource) {
+	const callee = path.get("callee");
+	if (callee.isIdentifier()) {
+		const name = callee.node.name;
+		return isReactNamedImport(path, name, "memo", reactImportSource) || isReactNamedImport(path, name, "forwardRef", reactImportSource);
+	}
+	if (!callee.isMemberExpression()) return false;
+	const propertyName = getReadPropertyName(callee.node);
+	if (propertyName !== "memo" && propertyName !== "forwardRef") return false;
+	const object = callee.get("object");
+	return object.isIdentifier() && isReactDefaultOrNamespaceImport(path, object.node.name, reactImportSource);
+}
+/**
+* The static name of an object property's or class field's key. A computed key
+* is only readable when it is a string literal (`{ ["Home"]: ... }`), exactly as
+* `getReadPropertyName` reads `items["map"]`; anything else is decided at
+* runtime and stays unnamed, which leaves the function untransformed.
+*/
+function getPropertyKeyName(node) {
+	const key = unwrapTransparent(node.key);
+	if (node.computed) return t.isStringLiteral(key) ? key.value : void 0;
+	if (t.isIdentifier(key)) return key.name;
+	return t.isStringLiteral(key) ? key.value : void 0;
+}
+/**
+* The component/hook name a function held in a *keyed slot* takes from its key:
+*
+* ```js
+* Card.Header = () => <h1>{count.value}</h1>;          // a compound component
+* export const ns = { Home: () => <p>{count.value}</p> };  // an object namespace
+* class Holder { Row = () => <li>{count.value}</li>; }     // a class field
+* ```
+*
+* All three are ordinary ways to hold a component that no *binding* names, so
+* without this they resolved to no identity at all and `auto` mode passed over
+* them in silence. The key is the name the rest of the module reaches them by
+* (`<ns.Home />`, `<Card.Header />`), which is precisely what the PascalCase /
+* `useX` conventions are asked to classify -- so a lowercase key (`{ render:
+* ... }`, `obj.onClick = ...`) resolves to a lowercase identity and is filtered
+* out by those same conventions, exactly as a lowercase binding is.
+*
+* Reading the key *before* the function's own `id` is the same precedence the
+* enclosing binding already takes: `Card.onSelect = function Row() {}` is a
+* handler named for debugging, not a component, and the slot it was put in says
+* so more reliably than the label it carries.
+*
+* An identifier-target assignment (`Row = (props) => ...` after a separate
+* `let Row`) is deliberately not named here: the declaration is the binding, and
+* routing it through this would give a re-assignment the same authority as a
+* declaration. It keeps resolving through `getBindingIdentityName`'s own
+* branches exactly as before.
+*
+* An assignment target is required to root in a plain identifier
+* (`getStaticMemberPath`), which is what excludes `this.Row = ...` in a class
+* component's constructor. That shape is genuinely ambiguous here: it is just as
+* often a per-item row renderer invoked through `this.props.items.map(this.Row)`
+* as it is a component, and `this` is not a binding, so the reference walk that
+* disqualifies every other keyed slot (`isKeyedRenderCallback`) cannot see those
+* uses at all -- there would be no way to take the boundary back once given. So
+* the ambiguous case resolves the way this file always resolves one: name
+* nothing, transform nothing. Class components stay a manual `useSignals()` /
+* `@useSignals` opt-in.
+*/
+function getKeyedIdentityName(parent) {
+	if (parent.isAssignmentExpression()) {
+		const left = parent.node.left;
+		if (!t.isMemberExpression(left)) return void 0;
+		return getStaticMemberPath(left)?.keys.at(-1);
+	}
+	if (parent.isObjectProperty() || parent.isClassProperty()) return getPropertyKeyName(parent.node);
+}
+/**
+* A member expression read as a root binding plus the chain of static keys
+* taken from it: `a.b.Row` gives `a` / `["b", "Row"]`. Every link has to be a
+* statically readable key and the innermost object a plain identifier, so a
+* computed runtime key (`a[k].Row`) and a `this`-rooted path (`this.Row`) both
+* yield nothing rather than a partial answer.
+*
+* The chain, rather than just the last key, is what lets `isKeyedRenderCallback`
+* match a use site against the definition site: a one-level walk saw
+* `const a = { b: { Row } }` handed to `items.map(a.b.Row)` as an unrelated
+* reference and let the per-item callback keep a hook boundary of its own.
+*/
+function getStaticMemberPath(node) {
+	const keys = [];
+	let current = node;
+	while (t.isMemberExpression(current)) {
+		const key = getReadPropertyName(current);
+		if (key === void 0) return void 0;
+		keys.unshift(key);
+		current = current.object;
+	}
+	return t.isIdentifier(current) ? {
+		root: current.name,
+		keys
+	} : void 0;
+}
+function getBindingIdentityName(path, reactImportSource, climbedParent = climbComponentWrappers(path, reactImportSource).parentPath) {
+	const parent = climbedParent;
+	if (parent !== null) {
+		if (parent.isVariableDeclarator() && t.isIdentifier(parent.node.id)) return parent.node.id.name;
+		const keyed = getKeyedIdentityName(parent);
+		if (keyed !== void 0) return keyed;
+	}
+	if ((path.isFunctionDeclaration() || path.isFunctionExpression()) && path.node.id !== null && path.node.id !== void 0) return path.node.id.name;
+}
+/** Does a name read as a React component -- PascalCase -- by convention? */
+function isComponentName(name) {
+	return /^[A-Z]/.test(name);
+}
+/** Does a name read as a custom hook -- `useX` -- by convention? */
+function isHookName(name) {
+	return /^use[A-Z]/.test(name);
+}
+/**
+* Does `path` render JSX *itself*, rather than merely containing some?
+*
+* Nested functions are skipped, because their JSX is their own output and not
+* this function's: `(Base) => (props) => <Base />` renders nothing at all, it
+* returns a function that does. That distinction is the whole difference
+* between a factory and a component here, so without it a factory of factories
+* would be mistaken for the component at the bottom of the chain and have a
+* hook injected into a function React never renders.
+*
+* The cost of the stricter reading is a component whose only JSX lives inside a
+* callback (`(props) => items.map((i) => <li />)`) -- it renders JSX, but not
+* itself. That direction is the safe one: it declines to derive an identity,
+* leaving behavior exactly as it was, rather than injecting an invalid hook.
+*/
+function rendersJsx(path) {
+	let found = false;
+	path.traverse({
+		Function(nested) {
+			nested.skip();
+		},
+		JSXElement(jsx) {
+			found = true;
+			jsx.stop();
+		},
+		JSXFragment(jsx) {
+			found = true;
+			jsx.stop();
+		}
+	});
+	return found;
+}
+/**
+* Is `path` a higher-order component factory -- a function that *produces* a
+* component rather than being one, and that React itself therefore never
+* renders?
+*
+* The evidence is the parameter list. React calls a component with exactly one
+* props object, and a `forwardRef` render function with `(props, ref)`; neither
+* of those parameters is ever PascalCase, and a destructured one is a pattern
+* rather than a plain identifier. A PascalCase *identifier* parameter is
+* therefore a component being handed in, which only a factory receives. That is
+* the same naming convention this file already reads to classify `Counter` as a
+* component and `useCount` as a hook, applied one position further in -- not a
+* new kind of guess.
+*
+* The second half -- rendering no JSX of its own (`rendersJsx`, which looks past
+* nested functions) -- keeps a genuine component out no matter how its
+* parameters are spelled: a function that renders is a component.
+*
+* Two consequences follow, and together they are the whole policy for a
+* PascalCase factory such as
+* `export const WithCount = (Base) => (props) => <Base count={count.value} />`:
+*
+* - the factory is never transformed itself (`decideTransform` withholds both
+*   the automatic and the annotated route from it), and
+* - the function it returns inherits the factory's name (`getIdentityFactory`)
+*   exactly as a camelCase `withCount` factory's returned component already did.
+*
+* The first half is the load-bearing one. Without it the factory looked like an
+* ordinary component from every angle -- a PascalCase binding, and (because the
+* component it returns owned no identity, so `inspectFunction` never skipped it)
+* the returned component's JSX and `.value` reads credited to the factory's own
+* body. `auto` mode injected the boundary into the factory, `all` mode did so
+* with no `.value` read needed at all, and since `WithCount(Foo)` is normally
+* called at module scope the injected `useSignals()` ran with no React
+* dispatcher and threw at import time -- the unrecoverable direction this file
+* steers away from everywhere else.
+*/
+function isHigherOrderComponentFactory(path) {
+	return path.node.params.some((param) => {
+		const name = getSimpleParameterName(param);
+		return name !== void 0 && isComponentName(name);
+	}) && !rendersJsx(path);
+}
+/**
+* The name a parameter binds, seen through a default value. `(Base)` and
+* `(Base = Fallback)` bind the very same `Base`, but a default makes the node an
+* `AssignmentPattern` wrapping the identifier rather than an identifier itself
+* -- so matching only `Identifier` let a defaulted parameter fall through and
+* put the factory straight back in front of the import-time crash
+* `isHigherOrderComponentFactory` exists to prevent.
+*
+* A destructured or rest parameter binds no single name and yields nothing,
+* which is what keeps a component's `({ Icon })` prop out.
+*/
+function getSimpleParameterName(param) {
+	if (t.isIdentifier(param)) return param.name;
+	if (t.isAssignmentPattern(param) && t.isIdentifier(param.left)) return param.left.name;
+}
+/**
+* The higher-order-component factory whose identity `path` inherits, when
+* `path` is the component that factory returns:
+*
+* ```js
+* export const withCount = (Base) => (props) => <Base count={count.value} />;
+* export function withCount(Base) { return (props) => <Base ... />; }
+* ```
+*
+* The inner function is the real component in both, but it has no name of its
+* own: its only identity comes from being what `withCount` returns. Left
+* unresolved it is not a component to `auto` mode and not an annotatable
+* function to `@useSignals`, so a signal write silently stops re-rendering it
+* -- no error, just a stale UI.
+*
+* Three things have to hold, tested cheapest-first:
+*
+* - `path` sits in a return position of the enclosing function: an explicit
+*   `return`, or an arrow's concise body, which returns just as literally.
+*   Missing the second is what made the concise form fail even when annotated.
+* - The enclosing function has a resolvable name that is not a hook name, and
+*   -- if it is a *component* name -- is a function `isHigherOrderComponentFactory`
+*   independently identifies as a factory. A function returned by a component or
+*   a hook is otherwise a render prop or a callback that runs inside that owner's
+*   render rather than an independently mounted component, and a hook boundary of
+*   its own would be an invalid hook call. Factories are camelCase by convention
+*   (`withCount`, `connect`, `observer`), so the plain name test reads as
+*   "returned from a plain factory"; the PascalCase escape hatch exists because
+*   `WithCount` is an equally common spelling of the very same thing, and there
+*   the convention alone was not merely unhelpful but actively harmful (see
+*   `isHigherOrderComponentFactory`).
+*
+*   A `useX` name gets no such escape hatch, deliberately. React calls a hook
+*   from inside a render that is already in progress, so anything the hook hands
+*   back is a closure the caller may invoke during that same render -- no
+*   structural evidence in this file can rule that out, and the safe reading of
+*   an ambiguous case is to leave the returned function unresolved rather than
+*   give it a boundary that would be an invalid hook call.
+* - `path` renders JSX itself (`rendersJsx`). A factory handing back a
+*   comparator, a reducer or any other plain closure returns no component and
+*   must not be swept up -- and neither must the middle link of a factory
+*   chain, whose JSX is all inside the function *it* returns.
+*
+* Only the immediately enclosing function is consulted, so the inherited name
+* is always a real module binding. A factory that returns a factory
+* (`(a) => (b) => (props) => <p />`) deliberately leaves the innermost
+* function unresolved rather than inventing a name for a middle function that
+* has none -- an `@useSignals` annotation there still warns
+* (`warnUnnamedUseSignalsAnnotation`) instead of silently doing nothing.
+*/
+function getIdentityFactory(path, reactImportSource, climbedParent) {
+	if (climbedParent === null) return void 0;
+	let enclosing;
+	if (climbedParent.isArrowFunctionExpression()) enclosing = climbedParent;
+	else if (climbedParent.isReturnStatement()) enclosing = climbedParent.getFunctionParent();
+	else return;
+	if (enclosing === null) return void 0;
+	const name = getBindingIdentityName(enclosing, reactImportSource);
+	if (name === void 0 || isHookName(name)) return void 0;
+	if (!rendersJsx(path)) return void 0;
+	if (isComponentName(name) && !isHigherOrderComponentFactory(enclosing)) return void 0;
+	return {
+		path: enclosing,
+		name
+	};
+}
+function resolveComponentIdentity(path, reactImportSource, climbedParent = climbComponentWrappers(path, reactImportSource).parentPath) {
+	const own = getBindingIdentityName(path, reactImportSource, climbedParent);
+	if (own !== void 0) return {
+		kind: "binding",
+		name: own
+	};
+	const factory = getIdentityFactory(path, reactImportSource, climbedParent);
+	if (factory === void 0) return void 0;
+	return {
+		kind: "hoc-return",
+		name: `${factory.name}()`,
+		factory: factory.path
+	};
+}
+function isComponentIdentity(identity) {
+	if (identity === void 0) return false;
+	return identity.kind === "hoc-return" || isComponentName(identity.name);
+}
+function isHookIdentity(identity) {
+	if (identity === void 0) return false;
+	return identity.kind === "binding" && isHookName(identity.name);
+}
+/**
+* A PascalCase identity derived from the module's own file name.
+*
+* `export default (props) => <p>{count.value}</p>` is a perfectly ordinary way
+* to write a component and the only component position in a module that carries
+* no name at all: there is no binding, no key, and no function `id` for
+* `getBindingIdentityName` to read, so the export resolved to no identity and
+* `auto` and `all` alike passed straight over it in silence -- while the named
+* `export default function App()` one line away was transformed.
+*
+* The file name is the name such a module actually has: `Counter.tsx` is
+* imported as `Counter`, which is exactly the identity the rest of the codebase
+* refers to it by. Only its *shape* is ever used -- the derived string
+* classifies the export through `isComponentName`/`isHookName` and is never
+* emitted into the output -- so sanitizing punctuation away (`my-widget.tsx` ->
+* `MyWidget`) costs nothing and cannot collide with anything.
+*
+* A name that does not come out PascalCase (`123.tsx`, a module with no usable
+* stem) yields nothing rather than something invented, and the caller reports
+* that rather than silently skipping the export.
+*/
+function deriveModuleIdentityName(filename) {
+	if (filename === void 0) return void 0;
+	const base = filename.replace(/[?#].*$/, "").replace(/\\/g, "/");
+	const name = base.slice(base.lastIndexOf("/") + 1).replace(/\.[^.]*$/, "").split(/[^A-Za-z0-9]+/).filter((part) => part.length > 0).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+	return isComponentName(name) ? name : void 0;
+}
+/**
+* The derived identity for an anonymous `export default`, and nothing else.
+* Reached only after `resolveComponentIdentity` has found no real name, so a
+* named default export (`export default function App()`, `export default memo(
+* function App() {})`) keeps the name it wrote for itself.
+*/
+function getDefaultExportIdentity(climbedParent, filename) {
+	if (climbedParent === null || !climbedParent.isExportDefaultDeclaration()) return void 0;
+	const name = deriveModuleIdentityName(filename);
+	return name === void 0 ? void 0 : {
+		kind: "binding",
+		name
+	};
+}
+function isVerifiedUseSignalsSource(source, importSource) {
+	return source === importSource || source === `${importSource}/runtime`;
+}
+function isNamedUseSignalsImport(functionPath, name, importSource) {
+	const resolved = resolveImportedBinding(functionPath, name);
+	if (resolved === void 0 || !resolved.specifier.isImportSpecifier()) return false;
+	return t.isIdentifier(resolved.specifier.node.imported, { name: "useSignals" }) && (importSource === void 0 || isVerifiedUseSignalsSource(resolved.source, importSource));
+}
+function isNamespaceUseSignalsImport(functionPath, name, importSource) {
+	const resolved = resolveImportedBinding(functionPath, name);
+	return resolved !== void 0 && resolved.specifier.isImportNamespaceSpecifier() && (importSource === void 0 || isVerifiedUseSignalsSource(resolved.source, importSource));
+}
+function isUseSignalsCallee(functionPath, callee, importSource, allowBarrel = true) {
+	if (callee.isIdentifier()) return isNamedUseSignalsImport(functionPath, callee.node.name, allowBarrel ? void 0 : importSource);
+	if (!callee.isMemberExpression()) return false;
+	const object = callee.get("object");
+	if (!object.isIdentifier()) return false;
+	return getReadPropertyName(callee.node) === "useSignals" && isNamespaceUseSignalsImport(functionPath, object.node.name, allowBarrel ? void 0 : importSource);
+}
+const renderCallbackMethods = /* @__PURE__ */ new Set([
+	"map",
+	"flatMap",
+	"forEach"
+]);
+function isTransparentWrapper(node) {
+	return t.isTSNonNullExpression(node) || t.isTSAsExpression(node) || t.isTSSatisfiesExpression(node) || t.isTSTypeAssertion(node) || t.isTSInstantiationExpression(node);
+}
+/** The value-level node behind any chain of transparent TypeScript wrappers. */
+function unwrapTransparent(node) {
+	let current = node;
+	while (isTransparentWrapper(current)) current = current.expression;
+	return current;
+}
+/**
+* The path of the syntactic slot `path` really occupies. A reference wrapped in
+* `Row!` or `Row as Fn` sits one or more nodes below the argument list it is
+* actually part of, so climbing past those wrappers is what makes the enclosing
+* call -- and the node that genuinely sits in its argument list -- visible.
+*/
+function climbTransparentWrappers(path) {
+	let current = path;
+	for (let parent = current.parentPath; parent !== null && isTransparentWrapper(parent.node) && parent.node.expression === current.node; parent = current.parentPath) current = parent;
+	return current;
+}
+/**
+* The mirror image of `climbTransparentWrappers`: the path of the value a
+* chain of transparent wrappers is wrapped *around*. A declarator's initializer
+* is such a chain in `const Row = ((item) => <li />) as Fn`, so a check that
+* asks whether a binding was initialized with a function has to descend past
+* the wrappers to find it.
+*/
+function unwrapTransparentPath(path) {
+	let current = path;
+	while (isTransparentWrapper(current.node)) current = current.get("expression");
+	return current;
+}
+/**
+* The syntactic slot a function really occupies, past every wrapper that leaves
+* both its value and its identity alone: transparent TypeScript wrappers and
+* React's own `memo()` / `forwardRef()` calls. The two interleave freely --
+* `memo(((props) => <p />) as Fn)` puts the wrapper inside the call and
+* `(memo((props) => <p />)) as Fn` puts it outside -- so one loop alternates
+* between them rather than two separate passes, which would each stop at the
+* first wrapper of the other kind.
+*
+* Only argument 0 -- the component itself -- may climb. `memo`'s second
+* argument is an `areEqual` comparator that React calls during reconciliation,
+* outside any component's render: letting it inherit the wrapper's binding name
+* would classify `memo(Row, (a, b) => a.id === b.id)`'s comparator as the
+* component `MemoRow`, inject a full hook boundary into it, and throw
+* "Invalid hook call" on the first re-render. `forwardRef` takes only one
+* argument, so the same rule costs it nothing.
+*/
+function climbComponentWrappers(path, reactImportSource) {
+	let current = climbTransparentWrappers(path);
+	for (let parent = current.parentPath; parent !== null && parent.isCallExpression() && parent.node.arguments[0] === current.node && isKnownComponentWrapper(parent, reactImportSource); parent = current.parentPath) current = climbTransparentWrappers(parent);
+	return current;
+}
+/** The callee and arguments of a plain or optional-chained call. */
+function getCallParts(node) {
+	if (t.isCallExpression(node) || t.isOptionalCallExpression(node)) return {
+		callee: node.callee,
+		arguments: node.arguments
+	};
+}
+/**
+* Is `callee` a member access naming one of the known iteration methods
+* (`items.map`, `items?.flatMap`, `items["forEach"]`)? The object's runtime
+* type cannot be known statically, so this stays a heuristic on the method
+* name -- but a targeted one. `memo`/`forwardRef` can never match it: a bare
+* `memo(Row)` has an identifier callee, and `React.memo(Row)` names a property
+* that is not in the set, so React's wrappers keep their wrapped component
+* eligible for the transform without needing a special case here.
+*/
+function isRenderCallbackCallee(callee) {
+	const node = unwrapTransparent(callee);
+	if (!t.isMemberExpression(node) && !t.isOptionalMemberExpression(node)) return false;
+	const name = getReadPropertyName(node);
+	return name !== void 0 && renderCallbackMethods.has(name);
+}
+/**
+* The single notion of "this reference means the function runs synchronously,
+* repeatedly, as part of the caller's render": `callback` is *the* callback
+* argument of a call to a known array iteration method. Both the render-callback
+* exclusion and the read propagation in `inspectFunction` ask this same
+* question, so they cannot drift apart.
+*
+* `map`, `flatMap` and `forEach` all have the signature `(callbackFn, thisArg?)`,
+* so only argument 0 is ever invoked. Accepting any position would read the
+* `thisArg` of `items.map(String, Row)` as a render callback and strip `Row` --
+* a component this call never invokes at all -- of its own subscription, leaving
+* it stale on every later signal write.
+*
+* `callback` is matched against the node that literally sits in the argument
+* list, wrappers included, so a caller holding `Row!` compares equal while a
+* caller holding the inner `Row` does not; use `climbTransparentWrappers` to
+* reach the former from the latter.
+*/
+function isRenderCallbackInvocation(call, callback) {
+	const parts = getCallParts(call);
+	if (parts === void 0 || !isRenderCallbackCallee(parts.callee)) return false;
+	return parts.arguments[0] === callback;
+}
+/**
+* The name other statements can reach this function's own binding by. The
+* declarator is reached from the climbed position rather than the immediate
+* parent, because a wrapper on the initializer -- `const Row = ((item) =>
+* <li />) as Fn` -- stands between the function and the binding it names.
+*
+* This is `getBindingIdentityName`'s twin, deliberately not shared with it:
+* that function asks what a function *is* (its public component/hook
+* identity, where the enclosing binding always outranks the function's own
+* name and a `memo()`/`forwardRef()` wrapper is climbed through to reach it);
+* this one asks what other code in the module can *call it by* (a function
+* declaration's own name is authoritative the instant it exists, and only a
+* transparent TypeScript wrapper -- never a component wrapper -- sits between
+* a reference and the binding, since `items.map(memo(Row))` does not hand
+* `map` the plain `Row` reference). Each direction was its own past
+* regression, so keep them separate rather than reconciling the priority or
+* the climb depth.
+*/
+function getOwnBindingName(path) {
+	if (path.isFunctionDeclaration() && path.node.id !== null && path.node.id !== void 0) return path.node.id.name;
+	const parent = climbTransparentWrappers(path).parentPath;
+	if (parent !== null && parent.isVariableDeclarator() && t.isIdentifier(parent.node.id)) return parent.node.id.name;
+}
+/**
+* The full path a function in a keyed slot is reached by, from a root binding
+* down: `const ns = { Row: ... }` gives `ns` / `["Row"]`, `Card.Row = ...` gives
+* `Card` / `["Row"]`, and `const a = { b: { Row: ... } }` gives `a` /
+* `["b", "Row"]`.
+*
+* Nesting has to be followed all the way out rather than one level, because the
+* path is matched against use sites: stopping early left `items.map(a.b.Row)`
+* unrecognized, so the per-item callback kept a boundary that React would run
+* once per item inside a single render.
+*
+* A class field is deliberately absent -- it is reached through an instance
+* (`new Holder().Row`), which no binding walk can follow.
+*/
+function getKeyedAccessPath(parent) {
+	if (parent.isAssignmentExpression()) {
+		const left = parent.node.left;
+		if (!t.isMemberExpression(left)) return void 0;
+		const path = getStaticMemberPath(left);
+		return path === void 0 ? void 0 : {
+			origin: parent,
+			...path
+		};
+	}
+	if (!parent.isObjectProperty()) return void 0;
+	const key = getPropertyKeyName(parent.node);
+	if (key === void 0) return void 0;
+	const keys = [key];
+	for (let container = parent.parentPath; container.isObjectExpression();) {
+		const holder = container.parentPath;
+		if (holder === null) return void 0;
+		if (holder.isVariableDeclarator() && t.isIdentifier(holder.node.id)) return {
+			origin: parent,
+			root: holder.node.id.name,
+			keys
+		};
+		if (holder.isAssignmentExpression() && t.isMemberExpression(holder.node.left)) {
+			const path = getStaticMemberPath(holder.node.left);
+			return path === void 0 ? void 0 : {
+				origin: parent,
+				root: path.root,
+				keys: [...path.keys, ...keys]
+			};
+		}
+		if (!holder.isObjectProperty() || holder.node.value !== container.node) return void 0;
+		const outerKey = getPropertyKeyName(holder.node);
+		if (outerKey === void 0) return void 0;
+		keys.unshift(outerKey);
+		container = holder.parentPath;
+	}
+}
+/**
+* The keyed-slot twin of the by-reference check below: is a function held at
+* `ns.Row` / `Card.Row` handed to an iteration method anywhere in the module
+* (`items.map(ns.Row)`)?
+*
+* A keyed component has no binding of its own, so `getOwnBindingName` can say
+* nothing about it and the ordinary reference walk never runs. Naming such a
+* slot (`getKeyedIdentityName`) is what made it eligible for a boundary in the
+* first place, so this is the exclusion that has to come with it: without it,
+* `const handlers = { Row: (item) => <li>{item.value}</li> }` passed to `map`
+* would be the one keyed shape that gets a hook injected into a per-item
+* callback.
+*
+* The walk goes through the *root* binding rather than the function's, then
+* follows the same chain of keys back down from each reference, so only a use
+* that reads this exact slot counts. A JSX use (`<ns.Row />`) is a
+* `JSXMemberExpression`, not a member expression, so it never matches and a
+* genuine compound component keeps its boundary.
+*/
+function isKeyedRenderCallback(parent) {
+	const access = getKeyedAccessPath(parent);
+	if (access === void 0) return false;
+	const binding = access.origin.scope.getBinding(access.root);
+	if (binding === void 0) return false;
+	return binding.referencePaths.some((rootPath) => {
+		let current = rootPath;
+		for (const key of access.keys) {
+			const member = current.parentPath;
+			if (member === null || !member.isMemberExpression() || member.node.object !== current.node || getReadPropertyName(member.node) !== key) return false;
+			current = member;
+		}
+		const slot = climbTransparentWrappers(current);
+		return slot.parentPath !== null && isRenderCallbackInvocation(slot.parentPath.node, slot.node);
+	});
+}
+function isRenderCallback(path, visited = /* @__PURE__ */ new Set()) {
+	if (visited.has(path.node)) return false;
+	visited.add(path.node);
+	const argument = climbTransparentWrappers(path);
+	const enclosing = argument.parentPath;
+	if (enclosing !== null && isRenderCallbackInvocation(enclosing.node, argument.node)) return true;
+	if (enclosing !== null && isKeyedRenderCallback(enclosing)) return true;
+	const name = getOwnBindingName(path);
+	if (name === void 0 || enclosing === null) return false;
+	const binding = enclosing.scope.getBinding(name);
+	if (binding === void 0) return false;
+	if (binding.path.node !== path.node && binding.path.node !== enclosing.node) return false;
+	return binding.referencePaths.some((reference) => {
+		const slot = climbTransparentWrappers(reference);
+		if (slot.parentPath !== null && isRenderCallbackInvocation(slot.parentPath.node, slot.node)) return true;
+		return isCalledFromRenderCallback(slot, visited);
+	});
+}
+/**
+* Is `slot` the callee of a call that happens inside a render callback --
+* `items.map((item) => Row(item))` rather than `items.map(Row)`?
+*
+* Both forms run `Row` once per item inside the owner's single render pass, so
+* both must keep `Row` off a boundary of its own: `Row` called as a plain
+* function is never mounted as a fiber, so three hooks injected into it would
+* run in a loop and crash with "Rendered more hooks than during the previous
+* render" the moment the array length changes. The by-reference form is caught
+* by `isRenderCallbackInvocation`; this is the direct-call twin of it.
+*/
+function isCalledFromRenderCallback(slot, visited) {
+	const call = slot.parentPath;
+	if (call === null) return false;
+	const parts = getCallParts(call.node);
+	if (parts === void 0 || parts.callee !== slot.node) return false;
+	const owner = call.getFunctionParent();
+	return owner !== null && isRenderCallback(owner, visited);
+}
+/** The function `name`, referenced from `origin`'s scope, is bound to. */
+function resolveReferencedFunction(origin, name) {
+	const binding = origin.scope.getBinding(name);
+	if (binding === void 0) return void 0;
+	const bindingPath = binding.path;
+	if (bindingPath.isFunctionDeclaration()) return bindingPath;
+	if (bindingPath.isVariableDeclarator()) {
+		const init = bindingPath.get("init");
+		if (init.isExpression()) {
+			const value = unwrapTransparentPath(init);
+			if (value.isArrowFunctionExpression() || value.isFunctionExpression()) return value;
+		}
+	}
+}
+/**
+* Is `path` a component defined inline as a call argument --
+* `observer(function App() { return <p>{count.value}</p>; })`?
+*
+* The by-reference form is already eligible and documented as such: `const App
+* = ...; observer(App)` is named by its binding, and a reference passed to any
+* call that is not a known iteration method is "ordinary component
+* registration", where React instantiates the result as its own fiber with its
+* own hooks. The inline form is the same registration written in one
+* expression, and left out it was the one shape a third-party HOC could take
+* that went untransformed *and* unreported.
+*
+* Admitting it needs a discriminator with no ambiguity left in it, so all four
+* of these hold:
+*
+* - a function *expression carrying its own PascalCase name*. An arrow or an
+*   anonymous function expression has no identity for a boundary to attach to
+*   anyway, and the written-out name is the author's own statement that this is
+*   a component -- the same statement `const App = ...` makes.
+* - it renders JSX itself. A named callback that renders nothing is a
+*   comparator, a reducer, or a test body.
+* - it sits in an *argument* slot, never the callee, so the IIFE
+*   `(function App() { ... })()` -- which runs once at module scope, outside any
+*   render, exactly where a hook call throws -- is excluded.
+* - it is not the callback of a deferred hook (`useMemo(function Rows() {...},
+*   [])`), which runs inside the caller's render and must carry no hook of its
+*   own. The render-callback form (`items.map(function Row() {...})`) is
+*   excluded before this is ever reached, by `isRenderCallback`.
+*/
+function isInlineNamedComponentArgument(path, call, reactImportSource) {
+	if (!path.isFunctionExpression()) return false;
+	const id = path.node.id;
+	if (id === null || id === void 0 || !isComponentName(id.name)) return false;
+	const slot = climbComponentWrappers(path, reactImportSource);
+	if (!call.node.arguments.some((argument) => argument === slot.node)) return false;
+	if (isDeferredCallbackArgument(path)) return false;
+	return rendersJsx(path);
+}
+function isAutomaticTransformCandidate(path, reactImportSource, climbedParent) {
+	if (isRenderCallback(path)) return false;
+	if (path.isFunctionDeclaration()) return true;
+	const parent = climbedParent === void 0 ? climbComponentWrappers(path, reactImportSource).parentPath : climbedParent;
+	return parent !== null && (parent.isVariableDeclarator() || parent.isReturnStatement() || parent.isArrowFunctionExpression() || parent.isExportDefaultDeclaration() || parent.isObjectProperty() || parent.isClassProperty() || parent.isAssignmentExpression() && t.isMemberExpression(parent.node.left) && getStaticMemberPath(parent.node.left) !== void 0 || parent.isCallExpression() && isInlineNamedComponentArgument(path, parent, reactImportSource));
+}
+function isNestedTrackingBoundary(path, reactImportSource) {
+	const climbedParent = climbComponentWrappers(path, reactImportSource).parentPath;
+	if (!isAutomaticTransformCandidate(path, reactImportSource, climbedParent)) return false;
+	const identity = resolveComponentIdentity(path, reactImportSource, climbedParent);
+	return isComponentIdentity(identity) || isHookIdentity(identity);
+}
+const deferredCallbackHooks = /* @__PURE__ */ new Set([
+	"useEffect",
+	"useLayoutEffect",
+	"useInsertionEffect",
+	"useCallback",
+	"useMemo"
+]);
+/**
+* The property name a member expression reads, for the forms this file
+* tracks. A wrapper can sit around the key alone -- `items["map" as
+* const](Row)` is a plain member expression whose property is the wrapped
+* node -- so a computed property still needs unwrapping to reach the name.
+*/
+function getReadPropertyName(node) {
+	if (!node.computed) return t.isIdentifier(node.property) ? node.property.name : void 0;
+	const property = unwrapTransparent(node.property);
+	return t.isStringLiteral(property) ? property.value : void 0;
+}
+const nonSignalValueReceivers = /* @__PURE__ */ new Set([
+	"target",
+	"currentTarget",
+	"current"
+]);
+function isNonSignalValueReceiver(object) {
+	const receiver = unwrapTransparent(object);
+	if (!t.isMemberExpression(receiver) && !t.isOptionalMemberExpression(receiver)) return false;
+	const name = getReadPropertyName(receiver);
+	return name !== void 0 && nonSignalValueReceivers.has(name);
+}
+/**
+* Is `path` the value of a JSX event-handler attribute -- `onClick={() => ...}`,
+* `onChange={(e) => ...}`?
+*
+* The `on[A-Z]` naming convention is what separates the two kinds of function
+* a JSX attribute can carry. A handler runs from the event loop, long after the
+* render that created it, so `e.target.value` inside one is not a render read.
+* A render prop (`renderItem={(item) => ...}`) is invoked by the receiver
+* during the very same render and stays deliberately included -- it is the
+* documented workaround for the render-prop limitation, and excluding it would
+* leave a component that only reads through one with no subscription at all.
+*/
+function isJsxEventHandlerValue(path) {
+	const container = climbTransparentWrappers(path).parentPath;
+	if (container === null || !container.isJSXExpressionContainer()) return false;
+	const attribute = container.parentPath;
+	if (attribute === null || !attribute.isJSXAttribute()) return false;
+	const name = attribute.node.name;
+	return t.isJSXIdentifier(name) && /^on[A-Z]/.test(name.name);
+}
+/** Is `path` the callback argument of `useEffect`/`useMemo`/one of their kin? */
+function isDeferredCallbackArgument(path) {
+	const slot = climbTransparentWrappers(path);
+	const call = slot.parentPath;
+	if (call === null) return false;
+	const parts = getCallParts(call.node);
+	if (parts === void 0 || parts.arguments[0] !== slot.node) return false;
+	const callee = unwrapTransparent(parts.callee);
+	if (t.isIdentifier(callee)) return deferredCallbackHooks.has(callee.name);
+	if (!t.isMemberExpression(callee) && !t.isOptionalMemberExpression(callee)) return false;
+	const property = getReadPropertyName(callee);
+	return property !== void 0 && deferredCallbackHooks.has(property);
+}
+/**
+* Does a read at `path` sit inside a nested function that `functionPath`'s
+* render never runs -- an event handler, a deferred hook callback, or an async
+* body? Only the functions between the read and `functionPath` are examined:
+* the enclosing component is already known to be synchronous by the time any of
+* this matters, and anything further out owns its own inspection.
+*/
+function isDeferredReadContext(path, functionPath) {
+	for (let current = path.getFunctionParent(); current !== null && current.node !== functionPath.node; current = current.getFunctionParent()) {
+		if (current.node.async) return true;
+		if (isJsxEventHandlerValue(current)) return true;
+		if (isDeferredCallbackArgument(current)) return true;
+	}
+	return false;
+}
+function inspectFunction(functionPath, importSource, reactImportSource, visited = /* @__PURE__ */ new Set([functionPath.node])) {
+	const inspection = {
+		containsJSX: false,
+		readsValue: false,
+		hasUseSignalsCall: false
+	};
+	const foldReferencedRenderCallbacks = (call) => {
+		const argument = call.node.arguments[0];
+		if (argument === void 0) return;
+		const reference = unwrapTransparent(argument);
+		if (!t.isIdentifier(reference)) return;
+		if (!isRenderCallbackInvocation(call.node, argument)) return;
+		const target = resolveReferencedFunction(call, reference.name);
+		if (target === void 0 || target.isDescendant(functionPath)) return;
+		if (visited.has(target.node)) return;
+		visited.add(target.node);
+		const nested = inspectFunction(target, importSource, reactImportSource, visited);
+		if (nested.containsJSX) inspection.containsJSX = true;
+		if (nested.readsValue) inspection.readsValue = true;
+	};
+	const foldDirectlyCalledRenderCallbacks = (call) => {
+		const callee = unwrapTransparent(call.node.callee);
+		if (!t.isIdentifier(callee) || !isComponentName(callee.name) && !isHookName(callee.name)) return;
+		const owner = call.getFunctionParent();
+		if (owner === null || owner.node === functionPath.node || !isRenderCallback(owner)) return;
+		const target = resolveReferencedFunction(call, callee.name);
+		if (target === void 0 || target.isDescendant(functionPath)) return;
+		if (visited.has(target.node)) return;
+		visited.add(target.node);
+		const nested = inspectFunction(target, importSource, reactImportSource, visited);
+		if (nested.containsJSX) inspection.containsJSX = true;
+		if (nested.readsValue) inspection.readsValue = true;
+	};
+	const recordValueRead = (node, path) => {
+		if (getReadPropertyName(node) !== "value") return;
+		if (isNonSignalValueReceiver(node.object)) return;
+		if (isDeferredReadContext(path, functionPath)) return;
+		inspection.readsValue = true;
+	};
+	functionPath.traverse({
+		Function(path) {
+			if (isNestedTrackingBoundary(path, reactImportSource)) path.skip();
+		},
+		JSXElement(_path) {
+			inspection.containsJSX = true;
+		},
+		JSXFragment(_path) {
+			inspection.containsJSX = true;
+		},
+		MemberExpression(path) {
+			recordValueRead(path.node, path);
+		},
+		OptionalMemberExpression(path) {
+			recordValueRead(path.node, path);
+		},
+		CallExpression(path) {
+			foldReferencedRenderCallbacks(path);
+			foldDirectlyCalledRenderCallbacks(path);
+			if (path.getFunctionParent()?.node !== functionPath.node) return;
+			if (isUseSignalsCallee(functionPath, path.get("callee"), importSource)) inspection.hasUseSignalsCall = true;
+		},
+		OptionalCallExpression(path) {
+			foldReferencedRenderCallbacks(path);
+			foldDirectlyCalledRenderCallbacks(path);
+		}
+	});
+	return inspection;
+}
+function findRuntimeImports(programPath, runtimeSource) {
+	const imports = [];
+	for (const statement of programPath.get("body")) {
+		if (!statement.isImportDeclaration() || statement.node.importKind === "type" || statement.node.source.value !== runtimeSource) continue;
+		for (const specifier of statement.get("specifiers")) if (specifier.isImportSpecifier() && specifier.node.importKind !== "type" && t.isIdentifier(specifier.node.imported, { name: "useSignals" })) imports.push({
+			identifier: t.cloneNode(specifier.node.local),
+			bindingPath: specifier
+		});
+	}
+	return imports;
+}
+function addRuntimeImport(programPath, runtimeSource, functionPath) {
+	const local = functionPath.scope.generateUidIdentifier("useSignals");
+	const declaration = t.importDeclaration([t.importSpecifier(t.cloneNode(local), t.identifier("useSignals"))], t.stringLiteral(runtimeSource));
+	const imports = programPath.get("body").filter((path) => path.isImportDeclaration());
+	const inserted = (imports.length === 0 ? programPath.unshiftContainer("body", declaration) : imports.at(-1).insertAfter(declaration))[0];
+	if (inserted === void 0 || !inserted.isImportDeclaration()) throw new Error("Failed to insert the useSignals import");
+	programPath.scope.registerDeclaration(inserted);
+	const specifier = inserted.get("specifiers")[0];
+	if (specifier === void 0 || !specifier.isImportSpecifier()) throw new Error("Failed to register the useSignals import");
+	return {
+		identifier: local,
+		bindingPath: specifier
+	};
+}
+/**
+* Is `statements`' first entry a bare zero-argument call whose callee resolves
+* to `useSignals`, with `allowBarrel` controlling whether a barrel/re-export
+* chain counts (see `isUseSignalsCallee`)? Shared by `isExplicitUseSignals`
+* (`allowBarrel: false`, the verified boundary) and
+* `isUnverifiableBarrelUseSignals` (`allowBarrel: true`, to detect the exact
+* call the former rejects).
+*/
+function isFirstStatementUseSignalsCall(functionPath, statements, importSource, allowBarrel) {
+	const first = statements[0];
+	if (first === void 0 || !first.isExpressionStatement()) return false;
+	const expression = first.get("expression");
+	if (!expression.isCallExpression() || expression.node.arguments.length !== 0) return false;
+	return isUseSignalsCallee(functionPath, expression.get("callee"), importSource, allowBarrel);
+}
+function isExplicitUseSignals(functionPath, statements, importSource) {
+	return isFirstStatementUseSignalsCall(functionPath, statements, importSource, false);
+}
+/**
+* The named import specifier the absorbed explicit `useSignals()` call resolves
+* to, when the call is a bare identifier bound by one. `applyManaged` replaces
+* that call with its own store declaration, which can leave the import behind
+* with nothing referencing it -- so `Program.exit` needs the specifier to check
+* and drop. A namespace import is deliberately not returned: the namespace
+* object may be used for other exports of the same module.
+*/
+function getAbsorbedUseSignalsImport(functionPath, statements) {
+	const first = statements[0];
+	if (first === void 0 || !first.isExpressionStatement()) return void 0;
+	const expression = first.get("expression");
+	if (!expression.isCallExpression()) return void 0;
+	const callee = expression.get("callee");
+	if (!callee.isIdentifier()) return void 0;
+	const resolved = resolveImportedBinding(functionPath, callee.node.name);
+	if (resolved === void 0 || !resolved.specifier.isImportSpecifier()) return void 0;
+	return resolved.specifier;
+}
+function isUnverifiableBarrelUseSignals(functionPath, statements, importSource, explicit) {
+	if (explicit) return false;
+	return isFirstStatementUseSignalsCall(functionPath, statements, importSource, true);
+}
+function warnUnverifiableBarrelUseSignals(path, importSource) {
+	const warning = path.buildCodeFrameError(`This useSignals() call cannot be verified as "${importSource}"'s own export: it resolves only through a barrel/re-export module, and a single-file transform cannot follow that chain to confirm the target. The component stays on the bare, best-effort useSignals() boundary. Import useSignals directly from "${importSource}" or "${importSource}/runtime" instead to get the verified boundary.`);
+	console.warn(warning.message);
+}
+function warnUnnamedUseSignalsAnnotation(path) {
+	const warning = path.buildCodeFrameError("This @useSignals annotation is ignored: the transform could not resolve a component or hook identity for the annotated function, and the boundary is attached to that identity. Give it a PascalCase (component) or useX (hook) name -- a binding, a named function declaration, or an object/class property key -- to opt it in.");
+	console.warn(warning.message);
+}
+function warnUnnamedDefaultExport(path) {
+	const warning = path.buildCodeFrameError("This anonymous default export is left untransformed: its component identity is derived from the module's file name, and this module's name does not yield a PascalCase identifier. Name the function (`export default function App() { ... }`), or assign it to a PascalCase binding and export that binding, to opt it in.");
+	console.warn(warning.message);
+}
+function shouldAutomaticallyTransform(mode, inspection, identity) {
+	if (isHookIdentity(identity)) return mode !== "manual" && inspection.readsValue;
+	if (!isComponentIdentity(identity) || !inspection.containsJSX) return false;
+	return mode === "all" || mode === "auto" && inspection.readsValue;
+}
+/** Marks the current file as having produced at least one real change. */
+function markTransformed(state) {
+	state.file.metadata[transformedMetadataKey] = true;
+}
+/**
+* Resolves what, if anything, `path` needs done to it: the opt-out check,
+* explicit/annotated/automatic eligibility (plus the barrel-useSignals
+* warning that eligibility check surfaces along the way), the
+* async/generator guard, and -- once a function is confirmed eligible for
+* real codegen -- acquiring the runtime `useSignals` import it will call.
+* Pure decision-making: no AST mutation happens here, so every early return is
+* just a `return`, not a `return` guarding mutations already made.
+*/
+function decideTransform(path, state, options, reactImportSource) {
+	const climbedParent = climbComponentWrappers(path, reactImportSource).parentPath;
+	const identity = resolveComponentIdentity(path, reactImportSource, climbedParent) ?? getDefaultExportIdentity(climbedParent, state.filename);
+	const factory = identity?.kind === "hoc-return" ? identity.factory : void 0;
+	const ownsLeadingComment = (pattern) => hasOwnedLeadingComment(path, pattern) || factory !== void 0 && hasOwnedLeadingComment(factory, pattern);
+	if (ownsLeadingComment(noUseSignalsComment)) return { kind: "skip" };
+	const body = path.get("body");
+	const statements = body.isBlockStatement() ? body.get("body") : [];
+	const explicit = isExplicitUseSignals(path, statements, options.importSource);
+	if (isUnverifiableBarrelUseSignals(path, statements, options.importSource, explicit)) warnUnverifiableBarrelUseSignals(path, options.importSource);
+	const inspection = inspectFunction(path, options.importSource, reactImportSource);
+	const annotation = ownsLeadingComment(useSignalsComment);
+	const isFactory = isHigherOrderComponentFactory(path) && !isHookIdentity(identity);
+	const annotated = annotation && !isFactory && (isComponentIdentity(identity) || isHookIdentity(identity));
+	const candidate = isAutomaticTransformCandidate(path, reactImportSource, climbedParent);
+	if (annotation && !annotated && rendersJsx(path)) {
+		const enclosing = path.getFunctionParent();
+		if (enclosing === null || !hasOwnedLeadingComment(enclosing, useSignalsComment)) warnUnnamedUseSignalsAnnotation(path);
+	}
+	if (options.mode !== "manual" && identity === void 0 && climbedParent !== null && climbedParent.isExportDefaultDeclaration() && rendersJsx(path)) warnUnnamedDefaultExport(path);
+	const automatic = !isFactory && candidate && shouldAutomaticallyTransform(options.mode, inspection, identity);
+	if (!explicit && !annotated && !automatic) return { kind: "skip" };
+	if (!explicit && inspection.hasUseSignalsCall) return { kind: "skip" };
+	if (options.transform === "inject" && explicit) return {
+		kind: "directive-only",
+		body
+	};
+	if (path.node.async || path.node.generator) {
+		if (!explicit && !annotated) return { kind: "skip" };
+		throw path.buildCodeFrameError("useSignals transform only supports synchronous, non-generator functions");
+	}
+	const managedRuntimeSource = `${options.importSource}/runtime`;
+	const importSource = options.transform === "managed" ? managedRuntimeSource : options.importSource;
+	const imports = options.transform === "managed" ? state.managedRuntimeImports : state.directImports;
+	let runtimeImport = imports.find(({ identifier, bindingPath }) => path.scope.getBinding(identifier.name)?.path === bindingPath);
+	if (runtimeImport === void 0) {
+		runtimeImport = addRuntimeImport(state.programPath, importSource, path);
+		imports.push(runtimeImport);
+	}
+	return {
+		kind: options.transform,
+		body,
+		statements,
+		explicit,
+		runtimeImport,
+		absorbedImport: explicit ? getAbsorbedUseSignalsImport(path, statements) : void 0
+	};
+}
+/** Codegen: inject a bare `useSignals()` call at the top of the function body. */
+function applyInject(path, { body, runtimeImport }, options, state) {
+	const call = t.expressionStatement(t.callExpression(t.cloneNode(runtimeImport.identifier), []));
+	if (body.isBlockStatement()) body.unshiftContainer("body", call);
+	else body.replaceWith(t.blockStatement([call, t.returnStatement(body.node)]));
+	const injectedBody = path.node.body;
+	if (options.reactCompiler === "auto" && t.isBlockStatement(injectedBody)) addNoMemoDirective(injectedBody);
+	path.scope.crawl();
+	markTransformed(state);
+}
+/** Codegen: wrap the function body in the managed try/finally render-tracking scope. */
+function applyManaged(path, { body, statements, explicit, runtimeImport, absorbedImport }, options, state) {
+	const store = path.scope.generateUidIdentifier("signals");
+	const declaration = t.variableDeclaration("const", [t.variableDeclarator(t.cloneNode(store), t.callExpression(t.cloneNode(runtimeImport.identifier), []))]);
+	const first = statements[0];
+	if (explicit && first !== void 0) t.inheritsComments(declaration, first.node);
+	const originalStatements = body.isBlockStatement() ? statements.slice(explicit ? 1 : 0).map((statement) => statement.node) : [t.returnStatement(body.node)];
+	const transformedBody = t.blockStatement([declaration, t.tryStatement(t.blockStatement(originalStatements), null, t.blockStatement([t.expressionStatement(t.callExpression(t.memberExpression(t.cloneNode(store), t.identifier("f")), []))]))]);
+	if (body.isBlockStatement()) transformedBody.directives = body.node.directives;
+	if (options.reactCompiler === "auto") addNoMemoDirective(transformedBody);
+	body.replaceWith(transformedBody);
+	path.scope.crawl();
+	if (absorbedImport !== void 0) state.absorbedImports.push(absorbedImport);
+	markTransformed(state);
+}
+/**
+* Drops an `import { useSignals } from "<importSource>"` the managed transform
+* absorbed and nothing else refers to any more, along with the whole
+* declaration once its last specifier goes. A reused `/runtime` import survives
+* this untouched: the emitted store declaration still calls it, so the binding
+* is still referenced.
+*/
+function removeAbsorbedImports(programPath, state) {
+	if (state.absorbedImports.length === 0) return;
+	programPath.scope.crawl();
+	for (const specifier of state.absorbedImports) {
+		if (specifier.removed) continue;
+		const binding = programPath.scope.getBinding(specifier.node.local.name);
+		if (binding === void 0 || binding.path.node !== specifier.node || binding.referenced) continue;
+		const declaration = specifier.parentPath;
+		specifier.remove();
+		if (declaration.isImportDeclaration() && declaration.node.specifiers.length === 0) declaration.remove();
+	}
+	state.absorbedImports = [];
+}
+const babelTransform = declare((api, options) => {
+	api.assertVersion(8);
+	const managedRuntimeSource = `${options.importSource}/runtime`;
+	const reactImportSource = options.reactImportSource;
+	return {
+		name: "unplugin-react-fine-grained-signals",
+		visitor: {
+			Program: {
+				enter(path, state) {
+					state.programPath = path;
+					state.managedRuntimeImports = findRuntimeImports(path, managedRuntimeSource);
+					state.directImports = findRuntimeImports(path, options.importSource);
+					state.absorbedImports = [];
+					state.file.metadata[transformedMetadataKey] = false;
+				},
+				exit(path, state) {
+					removeAbsorbedImports(path, state);
+				}
+			},
+			Function(path, state) {
+				const decision = decideTransform(path, state, options, reactImportSource);
+				switch (decision.kind) {
+					case "skip": return;
+					case "directive-only":
+						if (options.reactCompiler === "auto" && decision.body.isBlockStatement() && addNoMemoDirective(decision.body.node)) markTransformed(state);
+						return;
+					case "inject":
+						applyInject(path, decision, options, state);
+						return;
+					case "managed":
+						applyManaged(path, decision, options, state);
+						return;
+				}
+			}
+		}
+	};
+});
+/**
+* A raw-text screen run before the file is parsed at all. Parsing, walking,
+* printing and generating a source map is the whole cost of this transform, and
+* it is discarded outright for every file none of the three opt-in routes can
+* possibly apply to:
+*
+* - explicit and annotated opt-in both need the text `useSignals` (an aliased
+*   import, a namespace call and the `@useSignals` comment all still contain
+*   it);
+* - `auto` needs a `.value` read, so it needs the text `value`;
+* - `all` additionally wraps JSX components, so it needs a `<` -- but its
+*   custom-hook rule still needs a `.value` read.
+*
+* Each test is a plain substring scan and each one is deliberately wider than
+* what the AST check accepts, so this can only ever bail out on files the walk
+* would have rejected anyway.
+*/
+function mightTransform(code, mode) {
+	if (code.includes("useSignals")) return true;
+	if (mode === "manual") return false;
+	if (code.includes("value")) return true;
+	return mode === "all" && code.includes("<");
+}
+/** Runs the private Babel transform for the universal bundler adapter. */
+function transformReactFineGrainedSignals(code, id, options) {
+	if (!mightTransform(code, options.mode)) return null;
+	const cleanId = id.replace(/[?#].*$/, "");
+	const isTypeScript = /\.[cm]?tsx?$/i.test(cleanId);
+	const supportsJsx = /\.[cm]?(?:jsx?|tsx)$/i.test(cleanId);
+	const parserPlugins = [];
+	if (supportsJsx) parserPlugins.push("jsx");
+	if (isTypeScript) parserPlugins.push("typescript");
+	parserPlugins.push("decorators-legacy", "decoratorAutoAccessors");
+	let result;
+	try {
+		result = transformSync(code, {
+			babelrc: false,
+			configFile: false,
+			filename: id,
+			sourceFileName: cleanId,
+			parserOpts: { plugins: parserPlugins },
+			plugins: [[babelTransform, options]],
+			sourceMaps: true
+		});
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		throw new Error(`unplugin-react-fine-grained-signals could not parse ${cleanId} (Babel parser plugins: ${parserPlugins.join(", ") || "none"}): ${detail}`, { cause: error });
+	}
+	if (result === null || typeof result.code !== "string" || result.metadata?.[transformedMetadataKey] !== true) return null;
+	return {
+		code: result.code,
+		map: result.map
+	};
+}
+//#endregion
+//#region src/unplugin.ts
+const SCRIPT_MODULE = /\.m?[jt]sx?$/;
+const pluginName = "unplugin-react-fine-grained-signals";
+/**
+* `id` with the `?query`/`#fragment` a bundler appends taken off, which is
+* exactly what the transform strips before it picks its parser plugins.
+*
+* Deciding on the raw id instead diverges from that decision in both
+* directions. Vite's SFC sub-request `App.vue?vue&type=script&lang.tsx` ends in
+* `.tsx` only because its *query* does, so it would be claimed and then reach
+* the parser as `App.vue` -- with neither the `jsx` nor the `typescript` plugin
+* enabled -- and fail as though the author had written broken syntax.
+* `App.tsx#frag` ends in neither, so it would be skipped although the transform
+* handles it perfectly well. Cleaning here keeps the claim and the parse
+* looking at the same name.
+*/
+function cleanModuleId(id) {
+	return id.replace(/[?#].*$/, "");
+}
+function canTransform(id, options) {
+	if (id.startsWith("\0")) return false;
+	if (id.includes("/node_modules/") || id.includes("\\node_modules\\")) return false;
+	if (!SCRIPT_MODULE.test(cleanModuleId(id))) return false;
+	if (options.exclude?.(id)) return false;
+	return options.include?.(id) ?? true;
+}
+/**
+* `.js`/`.mjs` deliberately resolve to `"jsx"`. JavaScript commonly carries JSX
+* without a `.jsx` suffix -- the transform's own parser configuration says so,
+* and its output for such a file still contains that JSX -- but unplugin's
+* esbuild adapter labels every file it hands back with `guessLoader`, which
+* maps `.js` to `"js"` and so overrides a project's own
+* `loader: { ".js": "jsx" }` setting. Because that adapter returns
+* `{ contents, loader }` for every file passing `transformInclude`, even the
+* ones this transform declines to touch, a single wrong answer here breaks the
+* whole build rather than just one module.
+*/
+const ESBUILD_LOADERS = {
+	".js": "jsx",
+	".mjs": "jsx",
+	".jsx": "jsx",
+	".ts": "ts",
+	".mts": "ts",
+	".tsx": "tsx"
+};
+/**
+* The loader to label `id`'s contents with, deferring to the build's own
+* `loader` map first so a project that configured an extension keeps its
+* choice. Exported for the adapter tests, which exercise the decision without
+* needing esbuild itself.
+*/
+function resolveEsbuildLoader(id, configuredLoaders) {
+	const extension = /\.[^./\\]*$/.exec(cleanModuleId(id))?.[0].toLowerCase() ?? "";
+	return configuredLoaders?.[extension] ?? ESBUILD_LOADERS[extension] ?? "js";
+}
+let transformLoaderPath;
+/** The absolute path of this package's own webpack/rspack loader, if reachable. */
+function resolveTransformLoaderPath() {
+	if (transformLoaderPath === void 0) try {
+		transformLoaderPath = fileURLToPath(new URL("./loader.js", import.meta.url));
+	} catch {
+		transformLoaderPath = null;
+	}
+	return transformLoaderPath;
+}
+const patchedMarker = "__reactFineGrainedSignalsLoaderPatched";
+let loaderPatchReported = false;
+/**
+* Says, once per process, that the rewrite below found nothing to rewrite.
+*
+* That rewrite is deliberately shape-matched, so an unplugin release which
+* restructures its transform rule keeps its own behaviour rather than breaking
+* the build -- but its own behaviour is the dropped source map this package's
+* loader exists to avoid, and falling back to it in silence is precisely the
+* regression nobody would notice. One line is enough to find it; repeating it
+* per module or per rebuild would only teach people to ignore it.
+*/
+function reportLoaderPatchSkipped(reason) {
+	if (loaderPatchReported) return;
+	loaderPatchReported = true;
+	console.warn(`[${pluginName}] Source map fix not applied: ${reason}. Falling back to unplugin's own transform loader, whose output maps point at pre-transform line numbers.`);
+}
+/** Is this the bare `{ enforce, use(data) }` rule unplugin adds for `transform`? */
+function isUnpluginTransformRule(rule) {
+	if (rule === null || typeof rule !== "object") return false;
+	if (typeof rule.use !== "function") return false;
+	return Object.keys(rule).every((key) => key === "use" || key === "enforce");
+}
+/**
+* Repoints unplugin's webpack/rspack transform rule at this package's own
+* loader, which is the same loader with the source map passed through
+* correctly -- see `src/loader.ts` for why unplugin's copy drops it.
+*
+* The rule is rewritten rather than replaced: unplugin's `use(data)` still
+* decides *whether* this file is claimed (it applies `transformInclude` and
+* carries the plugin object along in `options`), and only the loader entries it
+* stamped with this plugin's `ident` have their module path swapped. Anything
+* that does not match that shape is left exactly as it was, so a future
+* unplugin release that restructures this simply gets its own behaviour back
+* instead of a broken build.
+*/
+function useOwnTransformLoader(compiler) {
+	const loaderPath = resolveTransformLoaderPath();
+	if (loaderPath === null) {
+		reportLoaderPatchSkipped("this package's own loader could not be located on disk");
+		return;
+	}
+	const rules = compiler?.options?.module?.rules;
+	if (!Array.isArray(rules)) {
+		reportLoaderPatchSkipped("the compiler exposes no `module.rules` array");
+		return;
+	}
+	let matched = false;
+	for (const rule of rules) {
+		if (!isUnpluginTransformRule(rule)) continue;
+		matched = true;
+		const original = rule.use;
+		if (original[patchedMarker] === true) continue;
+		const patched = (data) => {
+			const entries = original(data);
+			if (!Array.isArray(entries)) return entries;
+			return entries.map((entry) => entry !== null && typeof entry === "object" && entry.ident === "unplugin-react-fine-grained-signals" ? {
+				...entry,
+				loader: loaderPath
+			} : entry);
+		};
+		patched[patchedMarker] = true;
+		rule.use = patched;
+	}
+	if (!matched) reportLoaderPatchSkipped("unplugin's transform rule was not found in `module.rules`");
+}
+const reactFineGrainedSignals = createUnplugin((options = {}) => {
+	let configuredLoaders;
+	return {
+		name: pluginName,
+		enforce: "pre",
+		transformInclude(id) {
+			return canTransform(id, options);
+		},
+		transform(code, id) {
+			return transformReactFineGrainedSignals(code, id, {
+				importSource: options.importSource ?? "react-fine-grained-signals",
+				reactImportSource: options.reactImportSource ?? "react",
+				mode: options.mode ?? "auto",
+				transform: options.transform ?? "managed",
+				reactCompiler: options.reactCompiler ?? "auto"
+			});
+		},
+		esbuild: {
+			config(buildOptions) {
+				configuredLoaders = buildOptions.loader;
+			},
+			loader(_code, id) {
+				return resolveEsbuildLoader(id, configuredLoaders);
+			}
+		},
+		webpack: useOwnTransformLoader,
+		rspack: useOwnTransformLoader
+	};
+});
+/**
+* The one piece every per-bundler entry file (`vite.ts`, `webpack.ts`,
+* `rollup.ts`, `esbuild.ts`, `rspack.ts`) repeated: casting `reactFineGrainedSignals`'s
+* `bundler` property to a callable factory of its own bundler-specific plugin
+* type. Each entry file supplies only the two things that actually differ
+* between bundlers -- which property to read and what shape it returns.
+*/
+function createBundlerPlugin(bundler) {
+	return reactFineGrainedSignals[bundler];
+}
+//#endregion
+export { resolveEsbuildLoader as a, reactFineGrainedSignals as i, createBundlerPlugin as n, pluginName as r, canTransform as t };