@soda-gql/core 0.13.1 → 0.14.0

package/dist/index.cjs

@@ -195,7 +195,7 @@ const buildArgumentValue = (value, enumLookup) => {
 		fields: Object.entries(value).map(([key, fieldValue]) => {
 			let fieldTypeSpecifier = null;
 			if (enumLookup.typeSpecifier?.kind === "input") {
-				const fieldSpec = enumLookup.schema.input[enumLookup.typeSpecifier.name]?.fields[key];
+				const fieldSpec = (enumLookup.schema.input?.[enumLookup.typeSpecifier.name])?.fields[key];
 				fieldTypeSpecifier = fieldSpec ? parseInputSpecifier(fieldSpec) : null;
 			}
 			const valueNode = buildArgumentValue(fieldValue, {
@@ -323,12 +323,12 @@ const isShorthand = (value) => {
 const expandShorthand = (schema, typeName, fieldName) => {
 	const typeDef = schema.object[typeName];
 	if (!typeDef) throw new Error(`Type "${typeName}" not found in schema`);
-	const fieldSpec = typeDef.fields[fieldName];
-	if (!fieldSpec) throw new Error(`Field "${fieldName}" not found on type "${typeName}"`);
+	const fieldDef = typeDef.fields[fieldName];
+	if (!fieldDef) throw new Error(`Field "${fieldName}" not found on type "${typeName}"`);
 	return {
 		parent: typeName,
 		field: fieldName,
-		type: fieldSpec,
+		type: typeof fieldDef === "string" ? fieldDef : fieldDef.spec,
 		args: {},
 		directives: [],
 		object: null,
@@ -337,8 +337,10 @@ const expandShorthand = (schema, typeName, fieldName) => {
 };
 const buildUnionSelection = (union, schema) => {
 	const { selections, __typename: hasTypenameFlag } = union;
-	const inlineFragments = Object.entries(selections).map(([typeName, object]) => {
-		if (!object || typeof object !== "object") return null;
+	const inlineFragments = Object.entries(selections).map(([typeName, member]) => {
+		if (!member || typeof member !== "object") return null;
+		const { fields, directives: memberDirectives } = member;
+		const builtDirectives = buildDirectives(memberDirectives, "INLINE_FRAGMENT", schema);
 		return {
 			kind: graphql.Kind.INLINE_FRAGMENT,
 			typeCondition: {
@@ -348,9 +350,10 @@ const buildUnionSelection = (union, schema) => {
 					value: typeName
 				}
 			},
+			...builtDirectives.length > 0 ? { directives: builtDirectives } : {},
 			selectionSet: {
 				kind: graphql.Kind.SELECTION_SET,
-				selections: buildField(object, schema, typeName)
+				selections: buildField(fields, schema, typeName)
 			}
 		};
 	}).filter((item) => item !== null);
@@ -426,7 +429,7 @@ const buildConstValueNode = (value, enumLookup) => {
 		fields: Object.entries(value).map(([key, fieldValue]) => {
 			let fieldTypeSpecifier = null;
 			if (enumLookup.typeSpecifier?.kind === "input") {
-				const fieldSpec = enumLookup.schema.input[enumLookup.typeSpecifier.name]?.fields[key];
+				const fieldSpec = (enumLookup.schema.input?.[enumLookup.typeSpecifier.name])?.fields[key];
 				fieldTypeSpecifier = fieldSpec ? parseInputSpecifier(fieldSpec) : null;
 			}
 			const valueNode = buildConstValueNode(fieldValue, {
@@ -470,10 +473,10 @@ const buildConstValueNode = (value, enumLookup) => {
 * followed by `[]?` or `[]!` pairs for lists.
 *
 * @example
-* - `"!"` → `String!`
-* - `"?"` → `String`
-* - `"![]!"` → `[String!]!`
-* - `"?[]?"` → `[String]`
+* - `"!"` -> `String!`
+* - `"?"` -> `String`
+* - `"![]!"` -> `[String!]!`
+* - `"?[]?"` -> `[String]`
 */
 const buildWithTypeModifier = (modifier, buildType) => {
 	const baseType = buildType();
@@ -532,6 +535,10 @@ const buildWithTypeModifier = (modifier, buildType) => {
 	}
 	return curr.type;
 };
+/**
+* Builds VariableDefinitionNode[] from VarSpecifier records.
+* Kept as private fallback for callers that don't provide pre-parsed nodes.
+*/
 const buildVariables = (variables, schema) => {
 	return Object.entries(variables).map(([name, varSpec]) => {
 		let defaultValue;
@@ -589,7 +596,8 @@ const buildOperationTypeNode = (operation) => {
 * @returns TypedDocumentNode with inferred input/output types
 */
 const buildDocument = (options) => {
-	const { operationName, operationType, operationTypeName, variables, fields, schema } = options;
+	const { operationName, operationType, operationTypeName, variableDefinitionNodes, variables, fields, schema } = options;
+	const varDefs = variableDefinitionNodes ?? buildVariables(variables, schema);
 	return {
 		kind: graphql.Kind.DOCUMENT,
 		definitions: [{
@@ -599,7 +607,7 @@ const buildDocument = (options) => {
 				kind: graphql.Kind.NAME,
 				value: operationName
 			},
-			variableDefinitions: buildVariables(variables, schema),
+			variableDefinitions: varDefs,
 			selectionSet: {
 				kind: graphql.Kind.SELECTION_SET,
 				selections: buildField(fields, schema, operationTypeName)
@@ -620,13 +628,13 @@ const buildDocument = (options) => {
 * @example
 * ```typescript
 * // In operation definition
-* query.operation({
-*   name: "GetData",
-*   fields: ({ $ }) => $colocate({
-*     userCard: userCardFragment.spread({ userId: $.userId }),
-*     posts: postsFragment.spread({ userId: $.userId }),
+* query("GetData")({
+*   variables: `($userId: ID!)`,
+*   fields: ({ f, $ }) => $colocate({
+*     userCard: { ...f("user", { id: $.userId })(() => ({ ...userCardFragment.spread() })) },
+*     posts: { ...f("posts", { userId: $.userId })(() => ({ ...postsFragment.spread() })) },
 *   }),
-* });
+* })({});
 *
 * // In parser definition (same labels)
 * createExecutionResultParser({
@@ -646,16 +654,6 @@ const createColocateHelper = () => {
 	return $colocate;
 };
 
-//#endregion
-//#region packages/core/src/types/element/compat-spec.ts
-/**
-* Type guard to distinguish TemplateCompatSpec from CompatSpec at runtime.
-* Uses structural discrimination (presence of `graphqlSource` field).
-*/
-const isTemplateCompatSpec = (spec) => {
-	return "graphqlSource" in spec && !("fieldsBuilder" in spec);
-};
-
 //#endregion
 //#region packages/core/src/utils/promise.ts
 /**
@@ -884,7 +882,7 @@ var GqlDefine = class GqlDefine extends GqlElement {
 /**
 * Represents a reusable GraphQL field selection on a specific type.
 *
-* Fragments are created via `gql(({ fragment }) => fragment.TypeName({ ... }))`.
+* Fragments are created via `gql(({ fragment }) => fragment("Name", "TypeName")\`{ ... }\`())`.
 * Use `spread()` to include the fragment's fields in an operation.
 *
 * @template TTypeName - The GraphQL type this fragment selects from
@@ -934,7 +932,7 @@ var Fragment = class Fragment extends GqlElement {
 /**
 * Represents a GraphQL operation (query, mutation, or subscription).
 *
-* Operations are created via `gql(({ query }) => query.operation({ ... }))`.
+* Operations are created via `gql(({ query }) => query("Name")\`{ ... }\`())`.
 * Produces a TypedDocumentNode for type-safe execution with GraphQL clients.
 *
 * @template TOperationType - 'query' | 'mutation' | 'subscription'
@@ -989,42 +987,10 @@ var Operation = class Operation extends GqlElement {
 	}
 };
 
-//#endregion
-//#region packages/core/src/composer/compat.ts
-/**
-* Compat composer factory for creating GraphQL operation specifications.
-* @module
-*/
-/**
-* Creates a factory for composing compat operation specifications.
-*
-* Returns a function that creates a `GqlDefine<CompatSpec<...>>` storing
-* the operation specification with unevaluated fieldsBuilder.
-*
-* @param schema - The GraphQL schema definition
-* @param operationType - The operation type ('query' | 'mutation' | 'subscription')
-* @returns Compat operation composer function
-*
-* @internal Used by `createGqlElementComposer`
-*/
-const createCompatComposer = (schema, operationType) => {
-	if (schema.operations[operationType] === null) throw new Error(`Operation type ${operationType} is not defined in schema roots`);
-	return (options) => {
-		return GqlDefine.create(() => ({
-			schema,
-			operationType,
-			operationName: options.name,
-			variables: options.variables ?? {},
-			fieldsBuilder: options.fields
-		}));
-	};
-};
-
 //#endregion
 //#region packages/core/src/composer/compat-tagged-template.ts
 /**
 * Compat tagged template function for creating deferred GraphQL operation specs.
-* Callback builder compat path is in compat.ts.
 * @module
 */
 /**
@@ -2231,14 +2197,14 @@ const ensureCacheMapBySchema = (schema) => {
 	return cacheMap;
 };
 /**
-* Creates field selection factories for a given object type.
+* Creates a field accessor function for a given object type.
 *
-* Returns an object with a factory for each field defined on the type.
+* Returns a function f("fieldName", args, extras) for building field selections.
 * Factories are cached per schema+type to avoid recreation.
 *
 * @param schema - The GraphQL schema definition
 * @param typeName - The object type name to create factories for
-* @returns Object mapping field names to their selection factories
+* @returns FieldAccessorFunction for building field selections
 *
 * @internal Used by operation and fragment composers
 */
@@ -2246,70 +2212,88 @@ const createFieldFactories = (schema, typeName) => {
 	const cacheMap = ensureCacheMapBySchema(schema);
 	const cached = cacheMap.get(typeName);
 	if (cached) return cached;
-	const factories = createFieldFactoriesInner(schema, typeName);
-	cacheMap.set(typeName, factories);
-	return factories;
+	const factory = createFieldFactoriesInner(schema, typeName);
+	cacheMap.set(typeName, factory);
+	return factory;
 };
 const createFieldFactoriesInner = (schema, typeName) => {
 	const typeDef = schema.object[typeName];
 	if (!typeDef) throw new Error(`Type ${typeName} is not defined in schema objects`);
-	const entries = Object.entries(typeDef.fields).map(([fieldName, typeSpecifier]) => {
+	return (fieldName, fieldArgs, extras) => {
+		if (fieldName === "__typename") {
+			const wrap$1 = (value) => require_schema_builder.wrapByKey(extras?.alias ?? fieldName, value);
+			return (() => wrap$1({
+				parent: typeName,
+				field: fieldName,
+				type: "s|String|!",
+				args: {},
+				directives: extras?.directives ?? [],
+				object: null,
+				union: null
+			}));
+		}
+		const fieldDef = typeDef.fields[fieldName];
+		if (!fieldDef) throw new Error(`Field "${fieldName}" is not defined on type "${typeName}"`);
+		const typeSpecifier = typeof fieldDef === "string" ? fieldDef : fieldDef.spec;
 		const parsedType = parseOutputField(typeSpecifier);
-		const factory = (fieldArgs, extras) => {
-			const wrap = (value) => require_schema_builder.wrapByKey(extras?.alias ?? fieldName, value);
-			const directives = extras?.directives ?? [];
-			if (parsedType.kind === "object") {
-				const factoryReturn = ((nest) => {
-					const nestedFields = withFieldPath(appendToPath(getCurrentFieldPath(), {
-						field: fieldName,
-						parentType: typeName,
-						isList: isListType(parsedType.modifier)
-					}), () => nest({ f: createFieldFactories(schema, parsedType.name) }));
-					return wrap({
-						parent: typeName,
-						field: fieldName,
-						type: typeSpecifier,
-						args: fieldArgs ?? {},
-						directives,
-						object: nestedFields,
-						union: null
-					});
+		const wrap = (value) => require_schema_builder.wrapByKey(extras?.alias ?? fieldName, value);
+		const directives = extras?.directives ?? [];
+		if (parsedType.kind === "object") {
+			const factoryReturn = ((nest) => {
+				const nestedFields = withFieldPath(appendToPath(getCurrentFieldPath(), {
+					field: fieldName,
+					parentType: typeName,
+					isList: isListType(parsedType.modifier)
+				}), () => nest({ f: createFieldFactories(schema, parsedType.name) }));
+				return wrap({
+					parent: typeName,
+					field: fieldName,
+					type: typeSpecifier,
+					args: fieldArgs ?? {},
+					directives,
+					object: nestedFields,
+					union: null
 				});
-				return factoryReturn;
-			}
-			if (parsedType.kind === "union") {
-				const factoryReturn = ((nest) => {
-					const newPath = appendToPath(getCurrentFieldPath(), {
-						field: fieldName,
-						parentType: typeName,
-						isList: isListType(parsedType.modifier)
-					});
-					const typenameFlag = nest.__typename;
-					const selections = withFieldPath(newPath, () => {
-						const result = {};
-						for (const [memberName, builder] of Object.entries(nest)) {
-							if (memberName === "__typename") continue;
-							if (typeof builder !== "function") continue;
-							result[memberName] = builder({ f: createFieldFactories(schema, memberName) });
-						}
-						return result;
-					});
-					return wrap({
-						parent: typeName,
-						field: fieldName,
-						type: typeSpecifier,
-						args: fieldArgs ?? {},
-						directives,
-						object: null,
-						union: {
-							selections,
-							__typename: typenameFlag === true
-						}
-					});
+			});
+			return factoryReturn;
+		}
+		if (parsedType.kind === "union") {
+			const factoryReturn = ((nest) => {
+				const newPath = appendToPath(getCurrentFieldPath(), {
+					field: fieldName,
+					parentType: typeName,
+					isList: isListType(parsedType.modifier)
 				});
-				return factoryReturn;
-			}
-			if (parsedType.kind === "scalar" || parsedType.kind === "enum") return wrap({
+				const typenameFlag = nest.__typename;
+				const selections = withFieldPath(newPath, () => {
+					const result = {};
+					for (const [memberName, builder] of Object.entries(nest)) {
+						if (memberName === "__typename") continue;
+						if (typeof builder === "function") result[memberName] = {
+							fields: builder({ f: createFieldFactories(schema, memberName) }),
+							directives: []
+						};
+						else if (builder && typeof builder === "object" && "fields" in builder) result[memberName] = builder;
+					}
+					return result;
+				});
+				return wrap({
+					parent: typeName,
+					field: fieldName,
+					type: typeSpecifier,
+					args: fieldArgs ?? {},
+					directives,
+					object: null,
+					union: {
+						selections,
+						__typename: typenameFlag === true
+					}
+				});
+			});
+			return factoryReturn;
+		}
+		if (parsedType.kind === "scalar" || parsedType.kind === "enum") {
+			const factoryReturn = (() => wrap({
 				parent: typeName,
 				field: fieldName,
 				type: typeSpecifier,
@@ -2317,12 +2301,11 @@ const createFieldFactoriesInner = (schema, typeName) => {
 				directives,
 				object: null,
 				union: null
-			});
-			throw new Error(`Unsupported field type kind: ${parsedType.kind}`);
-		};
-		return [fieldName, factory];
-	});
-	return Object.fromEntries(entries);
+			}));
+			return factoryReturn;
+		}
+		throw new Error(`Unsupported field type kind: ${parsedType.kind}`);
+	};
 };
 
 //#endregion
@@ -2403,220 +2386,6 @@ const createVarAssignments = (definitions, providedValues) => {
 */
 const createVarRefs = (definitions) => mapValues(definitions, (_, name) => createVarRefFromVariable(name));
 
-//#endregion
-//#region packages/core/src/composer/operation-core.ts
-/**
-* Core operation building logic shared by operation and extend composers.
-* @module
-* @internal
-*/
-/**
-* Builds an operation artifact from the provided parameters.
-*
-* This function contains the core logic for:
-* - Creating variable refs and field factories
-* - Evaluating fields with fragment usage tracking
-* - Building the document
-* - Handling metadata (sync and async)
-* - Applying document transformations
-*
-* @param params - Operation building parameters
-* @returns Operation artifact or Promise of artifact (if async metadata)
-*
-* @internal Used by operation.ts, extend.ts, and operation-tagged-template.ts
-*/
-const buildOperationArtifact = (params) => {
-	const { schema, operationType, operationTypeName, operationName, variables, adapter, metadata: metadataBuilder, transformDocument: operationTransformDocument, adapterTransformDocument } = params;
-	const $ = createVarRefs(variables);
-	let document;
-	let variableNames;
-	let fields;
-	let fragmentUsages;
-	if (params.mode === "prebuilt") {
-		document = params.prebuiltDocument;
-		variableNames = params.prebuiltVariableNames ?? Object.keys(variables);
-		fields = {};
-		fragmentUsages = [];
-	} else {
-		const { fieldsFactory } = params;
-		const f = createFieldFactories(schema, operationTypeName);
-		const collected = withFragmentUsageCollection(() => fieldsFactory({
-			f,
-			$
-		}));
-		fields = collected.result;
-		fragmentUsages = collected.usages;
-		document = buildDocument({
-			operationName,
-			operationType,
-			operationTypeName,
-			variables,
-			fields,
-			schema
-		});
-		variableNames = Object.keys(variables);
-	}
-	if (!fragmentUsages.some((u) => u.metadataBuilder) && !metadataBuilder && !adapterTransformDocument && !operationTransformDocument) return {
-		operationType,
-		operationName,
-		schemaLabel: schema.label,
-		variableNames,
-		documentSource: () => fields,
-		document,
-		metadata: void 0
-	};
-	const aggregateFragmentMetadata = (resolvedFragmentMetadata) => {
-		const fragmentMetaInfos = fragmentUsages.map((usage, index) => ({
-			metadata: resolvedFragmentMetadata[index],
-			fieldPath: usage.path
-		}));
-		return adapter.aggregateFragmentMetadata(fragmentMetaInfos);
-	};
-	const fragmentMetadataResults = fragmentUsages.map((usage) => usage.metadataBuilder ? usage.metadataBuilder() : void 0);
-	const hasAsyncFragmentMetadata = fragmentMetadataResults.some((r) => isPromiseLike(r));
-	const buildOperationMetadata = (aggregatedFragmentMetadata) => {
-		const schemaLevel = adapter.schemaLevel;
-		return metadataBuilder?.({
-			$,
-			document,
-			fragmentMetadata: aggregatedFragmentMetadata,
-			schemaLevel
-		});
-	};
-	const makeCreateArtifact = (aggregated$1) => {
-		return ({ metadata }) => {
-			let finalDocument = operationTransformDocument ? operationTransformDocument({
-				document,
-				metadata
-			}) : document;
-			if (adapterTransformDocument) finalDocument = adapterTransformDocument({
-				document: finalDocument,
-				operationName,
-				operationType,
-				variableNames,
-				schemaLevel: adapter.schemaLevel,
-				fragmentMetadata: aggregated$1
-			});
-			return {
-				operationType,
-				operationName,
-				schemaLabel: schema.label,
-				variableNames,
-				documentSource: () => fields,
-				document: finalDocument,
-				metadata
-			};
-		};
-	};
-	if (hasAsyncFragmentMetadata) return Promise.all(fragmentMetadataResults).then(async (resolvedFragmentMetadata) => {
-		const aggregated$1 = aggregateFragmentMetadata(resolvedFragmentMetadata);
-		const operationMetadata = await buildOperationMetadata(aggregated$1);
-		return makeCreateArtifact(aggregated$1)({ metadata: operationMetadata });
-	});
-	const aggregated = aggregateFragmentMetadata(fragmentMetadataResults);
-	const createArtifact = makeCreateArtifact(aggregated);
-	const operationMetadataResult = buildOperationMetadata(aggregated);
-	if (isPromiseLike(operationMetadataResult)) return operationMetadataResult.then((metadata) => createArtifact({ metadata }));
-	return createArtifact({ metadata: operationMetadataResult });
-};
-/**
-* Wraps a buildOperationArtifact call into an Operation.create() invocation,
-* handling both sync and async artifact results.
-*
-* @param artifactFactory - Factory that produces the artifact (may return Promise for async metadata)
-* @param overrideDocumentSource - When true, overrides documentSource to return empty object.
-*   Required for pre-built document mode where fields = {} and the real documentSource is meaningless.
-*   Must be false for fieldsFactory mode to preserve real field selections.
-*
-* @internal Used by extend.ts and operation-tagged-template.ts
-*/
-const wrapArtifactAsOperation = (artifactFactory, overrideDocumentSource) => {
-	return Operation.create((() => {
-		const artifact = artifactFactory();
-		if (overrideDocumentSource) {
-			if (isPromiseLike(artifact)) return artifact.then((a) => ({
-				...a,
-				documentSource: () => ({})
-			}));
-			return {
-				...artifact,
-				documentSource: () => ({})
-			};
-		}
-		if (isPromiseLike(artifact)) return artifact;
-		return artifact;
-	}));
-};
-
-//#endregion
-//#region packages/core/src/composer/extend.ts
-/**
-* Extend composer factory for creating Operations from compat specs.
-* @module
-*/
-/**
-* Creates a factory for extending compat specs into full operations.
-*
-* The extend function takes a compat spec (created by `query.compat()`) and
-* optional metadata/transformDocument options, then creates a full Operation.
-*
-* @param schema - The GraphQL schema definition
-* @param adapter - Optional metadata adapter for custom metadata handling
-* @param transformDocument - Optional document transformer
-* @returns Extend composer function
-*
-* @internal Used by `createGqlElementComposer`
-*/
-const createExtendComposer = (schema, adapter, transformDocument) => {
-	const resolvedAdapter = adapter ?? defaultMetadataAdapter;
-	return (compat, options) => {
-		const spec = compat.value;
-		if (isTemplateCompatSpec(spec)) return buildOperationFromTemplateSpec(schema, spec, resolvedAdapter, options, transformDocument);
-		const { operationType, operationName, variables, fieldsBuilder } = spec;
-		const operationTypeName = schema.operations[operationType];
-		return Operation.create((() => buildOperationArtifact({
-			mode: "fieldsFactory",
-			schema,
-			operationType,
-			operationTypeName,
-			operationName,
-			variables,
-			fieldsFactory: fieldsBuilder,
-			adapter: resolvedAdapter,
-			metadata: options?.metadata,
-			transformDocument: options?.transformDocument,
-			adapterTransformDocument: transformDocument
-		})));
-	};
-};
-/**
-* Builds an Operation from a TemplateCompatSpec by parsing the raw GraphQL source.
-* Delegates to buildOperationArtifact with pre-built document mode.
-*/
-const buildOperationFromTemplateSpec = (schema, spec, adapter, options, adapterTransformDocument) => {
-	const { operationType, operationName, graphqlSource } = spec;
-	const document = (0, graphql.parse)(graphqlSource);
-	const opDef = document.definitions.find((d) => d.kind === graphql.Kind.OPERATION_DEFINITION);
-	if (!opDef) throw new Error("No operation definition found in compat template spec");
-	const schemaIndex = createSchemaIndexFromSchema(spec.schema);
-	const varSpecifiers = buildVarSpecifiers(opDef.variableDefinitions ?? [], schemaIndex);
-	const operationTypeName = schema.operations[operationType];
-	return wrapArtifactAsOperation(() => buildOperationArtifact({
-		mode: "prebuilt",
-		schema,
-		operationType,
-		operationTypeName,
-		operationName,
-		variables: varSpecifiers,
-		prebuiltDocument: document,
-		prebuiltVariableNames: Object.keys(varSpecifiers),
-		adapter,
-		metadata: options?.metadata,
-		transformDocument: options?.transformDocument,
-		adapterTransformDocument
-	}), true);
-};
-
 //#endregion
 //#region packages/core/src/composer/merge-variable-definitions.ts
 /**
@@ -2641,31 +2410,180 @@ function mergeVariableDefinitions(parentVars, interpolationMap) {
 }
 
 //#endregion
-//#region packages/core/src/composer/fragment-tagged-template.ts
+//#region packages/core/src/composer/var-ref-tools.ts
 /**
-* Fragment tagged template function for creating GraphQL fragments from template literals.
-* Supports Fragment Arguments RFC syntax for parameterized fragments.
-* @module
+* Recursively checks if a NestedValue contains any VarRef.
+*
+* Used by getVarRefValue to determine if it's safe to return as ConstValue.
+* @internal
 */
+const hasVarRefInside = (value) => {
+	if (value instanceof VarRef) return true;
+	if (Array.isArray(value)) return value.some(hasVarRefInside);
+	if (typeof value === "object" && value !== null) return Object.values(value).some(hasVarRefInside);
+	return false;
+};
 /**
-* Extract the argument list text from a fragment definition with Fragment Arguments syntax.
-* Returns the text between parens in `fragment Name(...) on Type`, or null if no args.
+* Get the variable name from a VarRef.
+* Throws if the VarRef contains a nested-value instead of a variable reference.
 */
-function extractFragmentArgText(rawSource) {
-	const match = /\bfragment\s+\w+\s*\(/.exec(rawSource);
-	if (!match) return null;
-	const openIndex = match.index + match[0].length - 1;
-	const closeIndex = findMatchingParen(rawSource, openIndex);
-	if (closeIndex === -1) return null;
-	if (rawSource.slice(closeIndex + 1).trimStart().startsWith("on")) return rawSource.slice(openIndex + 1, closeIndex);
-	return null;
-}
+const getVarRefName = (varRef) => {
+	const inner = VarRef.getInner(varRef);
+	if (inner.type !== "variable") throw new Error("Expected variable reference, got nested-value");
+	return inner.name;
+};
 /**
-* Extract variable definitions from Fragment Arguments syntax.
-* Wraps the argument list in a synthetic query to parse with graphql-js.
+* Get the const value from a VarRef.
+* Throws if the VarRef contains a variable reference instead of a nested-value,
+* or if the nested-value contains any VarRef inside.
 */
-function extractFragmentVariables(rawSource, schemaIndex) {
-	const argText = extractFragmentArgText(rawSource);
+const getVarRefValue = (varRef) => {
+	const inner = VarRef.getInner(varRef);
+	if (inner.type !== "nested-value") throw new Error("Expected nested-value, got variable reference");
+	if (hasVarRefInside(inner.value)) throw new Error("Cannot get const value: nested-value contains VarRef");
+	return inner.value;
+};
+const SelectableProxyInnerRegistry = /* @__PURE__ */ new WeakMap();
+const getSelectableProxyInner = (proxy) => {
+	const inner = SelectableProxyInnerRegistry.get(proxy);
+	if (!inner) throw new Error(`Proxy inner not found`);
+	return inner;
+};
+const createSelectableProxy = (current) => {
+	const proxy = new Proxy(Object.create(null), { get(_, property) {
+		if (typeof property === "symbol") throw new Error(`Prohibited property access: ${String(property)}`);
+		const nextSegments = [...current.segments, property];
+		if (current.varInner.type === "virtual") return createSelectableProxy({
+			varInner: current.varInner,
+			segments: nextSegments
+		});
+		if (current.varInner.type === "variable") return createSelectableProxy({
+			varInner: {
+				type: "virtual",
+				varName: current.varInner.name,
+				varSegments: nextSegments
+			},
+			segments: nextSegments
+		});
+		if (typeof current.varInner.value === "object" && current.varInner.value !== null) {
+			const value = current.varInner.value[property];
+			return createSelectableProxy({
+				varInner: value instanceof VarRef ? VarRef.getInner(value) : {
+					type: "nested-value",
+					value
+				},
+				segments: nextSegments
+			});
+		}
+		throw new Error(`Cannot access children of primitive value at path [${current.segments.join(".")}]`);
+	} });
+	SelectableProxyInnerRegistry.set(proxy, current);
+	return proxy;
+};
+/**
+* Get the variable name from a VarRef at a specific path.
+*
+* @param varRef - The VarRef containing a nested-value
+* @param selector - Path builder function, e.g., p => p.user.age
+* @returns The variable name at the specified path
+* @throws If path doesn't lead to a VarRef with type "variable"
+*
+* @example
+* const ref = createVarRefFromNestedValue({
+*   user: { age: someVariableRef }
+* });
+* getNameAt(ref, p => p.user.age); // returns the variable name
+*/
+const getNameAt = (varRef, selector) => {
+	const inner = getSelectableProxyInner(selector(createSelectableProxy({
+		varInner: VarRef.getInner(varRef),
+		segments: []
+	})));
+	if (inner.varInner.type === "virtual") throw new Error(`Value at path [${inner.segments.join(".")}] is inside a variable`);
+	if (inner.varInner.type !== "variable") throw new Error(`Value at path [${inner.segments.join(".")}] is not a variable`);
+	return inner.varInner.name;
+};
+/**
+* Get the const value from a nested-value VarRef at a specific path.
+*
+* @param varRef - The VarRef containing a nested-value
+* @param pathFn - Path builder function, e.g., p => p.user.name
+* @returns The const value at the specified path
+* @throws If path leads to a VarRef or if value contains VarRef inside
+*
+* @example
+* const ref = createVarRefFromNestedValue({
+*   user: { name: "Alice", age: someVariableRef }
+* });
+* getValueAt(ref, p => p.user.name); // returns "Alice"
+*/
+const getValueAt = (varRef, selector) => {
+	const inner = getSelectableProxyInner(selector(createSelectableProxy({
+		varInner: VarRef.getInner(varRef),
+		segments: []
+	})));
+	if (inner.varInner.type === "virtual") throw new Error(`Value at path [${inner.segments.join(".")}] is inside a variable`);
+	if (inner.varInner.type !== "nested-value") throw new Error(`Value at path [${inner.segments.join(".")}] is not a nested-value`);
+	if (hasVarRefInside(inner.varInner.value)) throw new Error(`Value at path [${inner.segments.join(".")}] contains nested VarRef`);
+	return inner.varInner.value;
+};
+/**
+* Gets the full path to a variable within a nested structure.
+*
+* Returns path segments starting with `$variableName` followed by
+* property accesses within that variable's value.
+*
+* @example
+* ```typescript
+* getVariablePath($.filter, p => p.user.id)
+* // Returns: ["$filter", "user", "id"]
+* ```
+*/
+const getVariablePath = (varRef, selector) => {
+	const inner = getSelectableProxyInner(selector(createSelectableProxy({
+		varInner: VarRef.getInner(varRef),
+		segments: []
+	})));
+	if (inner.varInner.type === "virtual") return [`$${inner.varInner.varName}`, ...inner.segments.slice(inner.varInner.varSegments.length)];
+	if (inner.varInner.type === "variable") return [`$${inner.varInner.name}`];
+	throw new Error(`Value at path [${inner.segments.join(".")}] is not a variable or inside a variable`);
+};
+/** Pre-built tools object passed as `$var` in metadata builder callbacks. */
+const varRefTools = Object.freeze({
+	getName: getVarRefName,
+	getValue: getVarRefValue,
+	getNameAt,
+	getValueAt,
+	getPath: getVariablePath,
+	hasVarRefInside
+});
+
+//#endregion
+//#region packages/core/src/composer/fragment-tagged-template.ts
+/**
+* Fragment tagged template function for creating GraphQL fragments from template literals.
+* Supports Fragment Arguments RFC syntax for parameterized fragments.
+* @module
+*/
+/**
+* Extract the argument list text from a fragment definition with Fragment Arguments syntax.
+* Returns the text between parens in `fragment Name(...) on Type`, or null if no args.
+*/
+function extractFragmentArgText(rawSource) {
+	const match = /\bfragment\s+\w+\s*\(/.exec(rawSource);
+	if (!match) return null;
+	const openIndex = match.index + match[0].length - 1;
+	const closeIndex = findMatchingParen(rawSource, openIndex);
+	if (closeIndex === -1) return null;
+	if (rawSource.slice(closeIndex + 1).trimStart().startsWith("on")) return rawSource.slice(openIndex + 1, closeIndex);
+	return null;
+}
+/**
+* Extract variable definitions from Fragment Arguments syntax.
+* Wraps the argument list in a synthetic query to parse with graphql-js.
+*/
+function extractFragmentVariables(rawSource, schemaIndex) {
+	const argText = extractFragmentArgText(rawSource);
 	if (!argText?.trim()) return {};
 	const syntheticQuery = `query _Synthetic(${argText}) { __typename }`;
 	let syntheticDoc;
@@ -2680,6 +2598,30 @@ function extractFragmentVariables(rawSource, schemaIndex) {
 	return buildVarSpecifiers(opDef.variableDefinitions ?? [], schemaIndex);
 }
 /**
+* Filters out named fragment spreads that cannot be resolved without an interpolation map.
+* Used when building fields from compat templates or zero-interpolation tagged templates
+* that may contain standard GraphQL `...FragmentName` spreads.
+*/
+function filterUnresolvedFragmentSpreads(selectionSet, interpolationMap) {
+	return {
+		...selectionSet,
+		selections: selectionSet.selections.filter((sel) => {
+			if (sel.kind !== graphql.Kind.FRAGMENT_SPREAD) return true;
+			return interpolationMap?.has(sel.name.value) ?? false;
+		}).map((sel) => {
+			if (sel.kind === graphql.Kind.FIELD && sel.selectionSet) return {
+				...sel,
+				selectionSet: filterUnresolvedFragmentSpreads(sel.selectionSet, interpolationMap)
+			};
+			if (sel.kind === graphql.Kind.INLINE_FRAGMENT && sel.selectionSet) return {
+				...sel,
+				selectionSet: filterUnresolvedFragmentSpreads(sel.selectionSet, interpolationMap)
+			};
+			return sel;
+		})
+	};
+}
+/**
 * Builds field selections from a GraphQL AST SelectionSet by driving field factories.
 * Converts parsed AST selections into the AnyFieldsExtended format that the document builder expects.
 * Also used by typegen for static field extraction from tagged templates.
@@ -2694,27 +2636,33 @@ function buildFieldsFromSelectionSet(selectionSet, schema, typeName, varAssignme
 			result[alias] = true;
 			continue;
 		}
-		const factory = f[fieldName];
-		if (!factory) throw new Error(`Field "${fieldName}" is not defined on type "${typeName}"`);
 		const args = buildArgsFromASTArguments(selection.arguments ?? [], varAssignments);
-		const extras = alias !== fieldName ? { alias } : void 0;
+		const directives = buildDirectivesFromAST(selection.directives, varAssignments);
+		const hasAlias = alias !== fieldName;
+		const extras = hasAlias || directives.length > 0 ? {
+			...hasAlias ? { alias } : {},
+			...directives.length > 0 ? { directives } : {}
+		} : void 0;
 		if (selection.selectionSet) {
-			const curried = factory(args, extras);
+			const curried = f(fieldName, args, extras);
 			if (typeof curried === "function") {
-				const fieldSpec = schema.object[typeName]?.fields[fieldName];
-				const parsedType = parseOutputField(fieldSpec);
+				const fieldDefRaw = schema.object[typeName]?.fields[fieldName];
+				const parsedType = parseOutputField(typeof fieldDefRaw === "string" ? fieldDefRaw : fieldDefRaw?.spec);
 				if (parsedType.kind === "union") {
 					const unionInput = {};
 					let hasTypename = false;
 					const unsupportedSelections = [];
 					for (const sel of selection.selectionSet.selections) if (sel.kind === graphql.Kind.INLINE_FRAGMENT) {
-						if (sel.directives?.length) throw new Error("Directives on inline fragments are not supported in tagged templates");
 						if (!sel.typeCondition) throw new Error("Inline fragments without type conditions are not supported in tagged templates");
 						const memberName = sel.typeCondition.name.value;
-						if (!schema.union[parsedType.name]?.types[memberName]) throw new Error(`Type "${memberName}" is not a member of union "${parsedType.name}" in tagged template inline fragment`);
+						const unionDef = schema.union[parsedType.name];
+						if (!unionDef) throw new Error(`Union "${parsedType.name}" is not defined in schema`);
+						if (!(memberName in unionDef.types)) throw new Error(`Type "${memberName}" is not a member of union "${parsedType.name}" in tagged template inline fragment`);
 						if (memberName in unionInput) throw new Error(`Duplicate inline fragment for union member "${memberName}" in tagged template. Merge selections into a single "... on ${memberName} { ... }" block.`);
-						const memberFields = buildFieldsFromSelectionSet(sel.selectionSet, schema, memberName, varAssignments, interpolationMap);
-						unionInput[memberName] = ({ f: _f }) => memberFields;
+						unionInput[memberName] = {
+							fields: buildFieldsFromSelectionSet(sel.selectionSet, schema, memberName, varAssignments, interpolationMap),
+							directives: buildDirectivesFromAST(sel.directives, varAssignments, "INLINE_FRAGMENT")
+						};
 					} else if (sel.kind === graphql.Kind.FIELD && sel.name.value === "__typename") {
 						if (sel.alias) throw new Error("Aliases on __typename in union selections are not supported in tagged templates. Use \"__typename\" without an alias.");
 						if (sel.directives?.length) throw new Error(`Directives on __typename in union selections are not supported in tagged templates.`);
@@ -2741,7 +2689,7 @@ function buildFieldsFromSelectionSet(selectionSet, schema, typeName, varAssignme
 				}
 			} else Object.assign(result, curried);
 		} else {
-			const fieldResult = factory(args, extras);
+			const fieldResult = f(fieldName, args, extras);
 			if (typeof fieldResult === "function") {
 				const emptyResult = fieldResult(() => ({}));
 				Object.assign(result, emptyResult);
@@ -2764,6 +2712,18 @@ function buildFieldsFromSelectionSet(selectionSet, schema, typeName, varAssignme
 	return result;
 }
 /**
+* Convert GraphQL AST DirectiveNodes to DirectiveRef instances.
+* Reuses buildArgsFromASTArguments for directive argument conversion.
+*/
+function buildDirectivesFromAST(directives, varAssignments, location = "FIELD") {
+	if (!directives || directives.length === 0) return [];
+	return directives.map((d) => new DirectiveRef({
+		name: d.name.value,
+		arguments: buildArgsFromASTArguments(d.arguments ?? [], varAssignments),
+		locations: [location]
+	}));
+}
+/**
 * Build a simple args object from GraphQL AST argument nodes.
 * Extracts literal values from the AST for passing to field factories.
 */
@@ -2867,7 +2827,10 @@ function createFragmentTaggedTemplate(schema) {
 						let metadataBuilder = null;
 						if (options?.metadata !== void 0) {
 							const metadata = options.metadata;
-							if (typeof metadata === "function") metadataBuilder = () => metadata({ $ });
+							if (typeof metadata === "function") metadataBuilder = () => metadata({
+								$,
+								$var: varRefTools
+							});
 							else metadataBuilder = () => metadata;
 						}
 						recordFragmentUsage({
@@ -2883,54 +2846,179 @@ function createFragmentTaggedTemplate(schema) {
 }
 
 //#endregion
-//#region packages/core/src/composer/operation.ts
+//#region packages/core/src/composer/operation-core.ts
 /**
-* Operation composer factory for creating typed GraphQL operations.
-* @module
+* Builds an operation artifact from the provided parameters.
+*
+* This function contains the core logic for:
+* - Creating variable refs and field factories
+* - Evaluating fields with fragment usage tracking
+* - Building the document
+* - Handling metadata (sync and async)
+* - Applying document transformations
+*
+* @param params - Operation building parameters
+* @returns Operation artifact or Promise of artifact (if async metadata)
+*
+* @internal Used by extend.ts and operation-tagged-template.ts
 */
+const buildOperationArtifact = (params) => {
+	const { schema, operationType, operationTypeName, operationName, variables, variableDefinitionNodes, adapter, metadata: metadataBuilder, transformDocument: operationTransformDocument, adapterTransformDocument } = params;
+	const $ = createVarRefs(variables);
+	const { fieldsFactory } = params;
+	const f = createFieldFactories(schema, operationTypeName);
+	const collected = withFragmentUsageCollection(() => fieldsFactory({
+		f,
+		$
+	}));
+	const fields = collected.result;
+	const fragmentUsages = collected.usages;
+	const document = buildDocument({
+		operationName,
+		operationType,
+		operationTypeName,
+		variableDefinitionNodes,
+		variables,
+		fields,
+		schema
+	});
+	const variableNames = Object.keys(variables);
+	if (!fragmentUsages.some((u) => u.metadataBuilder) && !metadataBuilder && !adapterTransformDocument && !operationTransformDocument) return {
+		operationType,
+		operationName,
+		schemaLabel: schema.label,
+		variableNames,
+		documentSource: () => fields,
+		document,
+		metadata: void 0
+	};
+	const aggregateFragmentMetadata = (resolvedFragmentMetadata) => {
+		const fragmentMetaInfos = fragmentUsages.map((usage, index) => ({
+			metadata: resolvedFragmentMetadata[index],
+			fieldPath: usage.path
+		}));
+		return adapter.aggregateFragmentMetadata(fragmentMetaInfos);
+	};
+	const fragmentMetadataResults = fragmentUsages.map((usage) => usage.metadataBuilder ? usage.metadataBuilder() : void 0);
+	const hasAsyncFragmentMetadata = fragmentMetadataResults.some((r) => isPromiseLike(r));
+	const buildOperationMetadata = (aggregatedFragmentMetadata) => {
+		const schemaLevel = adapter.schemaLevel;
+		return metadataBuilder?.({
+			$,
+			$var: varRefTools,
+			document,
+			fragmentMetadata: aggregatedFragmentMetadata,
+			schemaLevel
+		});
+	};
+	const makeCreateArtifact = (aggregated$1) => {
+		return ({ metadata }) => {
+			let finalDocument = operationTransformDocument ? operationTransformDocument({
+				document,
+				metadata
+			}) : document;
+			if (adapterTransformDocument) finalDocument = adapterTransformDocument({
+				document: finalDocument,
+				operationName,
+				operationType,
+				variableNames,
+				schemaLevel: adapter.schemaLevel,
+				fragmentMetadata: aggregated$1
+			});
+			return {
+				operationType,
+				operationName,
+				schemaLabel: schema.label,
+				variableNames,
+				documentSource: () => fields,
+				document: finalDocument,
+				metadata
+			};
+		};
+	};
+	if (hasAsyncFragmentMetadata) return Promise.all(fragmentMetadataResults).then(async (resolvedFragmentMetadata) => {
+		const aggregated$1 = aggregateFragmentMetadata(resolvedFragmentMetadata);
+		const operationMetadata = await buildOperationMetadata(aggregated$1);
+		return makeCreateArtifact(aggregated$1)({ metadata: operationMetadata });
+	});
+	const aggregated = aggregateFragmentMetadata(fragmentMetadataResults);
+	const createArtifact = makeCreateArtifact(aggregated);
+	const operationMetadataResult = buildOperationMetadata(aggregated);
+	if (isPromiseLike(operationMetadataResult)) return operationMetadataResult.then((metadata) => createArtifact({ metadata }));
+	return createArtifact({ metadata: operationMetadataResult });
+};
 /**
-* Creates a factory for composing GraphQL operations.
+* Wraps a buildOperationArtifact call into an Operation.create() invocation,
+* handling both sync and async artifact results.
 *
-* Returns a curried function: first select operation type (query/mutation/subscription),
-* then define the operation with name, variables, and fields.
+* @param artifactFactory - Factory that produces the artifact (may return Promise for async metadata)
 *
-* Handles metadata aggregation from fragments (sync or async) and builds
-* the TypedDocumentNode automatically.
+* @internal Used by extend.ts and operation-tagged-template.ts
+*/
+const wrapArtifactAsOperation = (artifactFactory) => {
+	return Operation.create(artifactFactory);
+};
+
+//#endregion
+//#region packages/core/src/composer/extend.ts
+/**
+* Extend composer factory for creating Operations from TemplateCompatSpec.
+* @module
+*/
+/**
+* Creates a factory for extending compat specs into full operations.
+*
+* The extend function takes a TemplateCompatSpec (created by `query.compat("Name")\`...\``)
+* and optional metadata/transformDocument options, then creates a full Operation.
 *
 * @param schema - The GraphQL schema definition
 * @param adapter - Optional metadata adapter for custom metadata handling
-* @param transformDocument - Optional document transformer called after building
-* @returns Operation type selector function
+* @param transformDocument - Optional document transformer
+* @returns Extend composer function
 *
 * @internal Used by `createGqlElementComposer`
 */
-const createOperationComposerFactory = (schema, adapter, transformDocument) => {
+const createExtendComposer = (schema, adapter, transformDocument) => {
 	const resolvedAdapter = adapter ?? defaultMetadataAdapter;
-	return (operationType) => {
-		const operationTypeName = schema.operations[operationType];
-		if (operationTypeName === null) throw new Error(`Operation type ${operationType} is not defined in schema roots`);
-		return (options) => {
-			return Operation.create((() => buildOperationArtifact({
-				mode: "fieldsFactory",
-				schema,
-				operationType,
-				operationTypeName,
-				operationName: options.name,
-				variables: options.variables ?? {},
-				fieldsFactory: options.fields,
-				adapter: resolvedAdapter,
-				metadata: options.metadata,
-				transformDocument: options.transformDocument,
-				adapterTransformDocument: transformDocument
-			})));
-		};
+	return (compat, options) => {
+		const spec = compat.value;
+		return buildOperationFromTemplateSpec(schema, spec, resolvedAdapter, options, transformDocument);
 	};
 };
+/**
+* Builds an Operation from a TemplateCompatSpec by parsing the raw GraphQL source.
+* Evaluates fields via buildFieldsFromSelectionSet for correct typegen output.
+*/
+const buildOperationFromTemplateSpec = (schema, spec, adapter, options, adapterTransformDocument) => {
+	const { operationType, operationName, graphqlSource } = spec;
+	const opDef = (0, graphql.parse)(graphqlSource).definitions.find((d) => d.kind === graphql.Kind.OPERATION_DEFINITION);
+	if (!opDef) throw new Error("No operation definition found in compat template spec");
+	const schemaIndex = createSchemaIndexFromSchema(spec.schema);
+	const varSpecifiers = buildVarSpecifiers(opDef.variableDefinitions ?? [], schemaIndex);
+	const operationTypeName = schema.operations[operationType];
+	const filteredSelectionSet = filterUnresolvedFragmentSpreads(opDef.selectionSet);
+	return wrapArtifactAsOperation(() => buildOperationArtifact({
+		schema,
+		operationType,
+		operationTypeName,
+		operationName,
+		variables: varSpecifiers,
+		variableDefinitionNodes: opDef.variableDefinitions ?? [],
+		fieldsFactory: ({ $ }) => {
+			return buildFieldsFromSelectionSet(filteredSelectionSet, schema, operationTypeName, $);
+		},
+		adapter,
+		metadata: options?.metadata,
+		transformDocument: options?.transformDocument,
+		adapterTransformDocument
+	}));
+};
 
 //#endregion
 //#region packages/core/src/composer/operation-tagged-template.ts
 /**
 * Operation tagged template function for creating GraphQL operations from template literals.
+* Also supports options object dispatch for callback builder path.
 * @module
 */
 /**
@@ -2944,9 +3032,9 @@ function buildSyntheticOperationSource(operationType, operationName, body) {
 * Resolves a metadata option from OperationTemplateMetadataOptions into a MetadataBuilder
 * compatible with buildOperationArtifact.
 *
-* - `undefined` → `undefined` (no metadata)
-* - Raw value → `() => value` (static metadata)
-* - Callback → forwarded directly (receives full pipeline context)
+* - `undefined` -> `undefined` (no metadata)
+* - Raw value -> `() => value` (static metadata)
+* - Callback -> forwarded directly (receives full pipeline context)
 */
 const resolveMetadataOption = (metadataOption) => {
 	if (metadataOption === void 0) return void 0;
@@ -2954,8 +3042,11 @@ const resolveMetadataOption = (metadataOption) => {
 	return () => metadataOption;
 };
 /**
-* Creates a curried tagged template function for a specific operation type.
-* New API: `query("name")\`($var: Type!) { fields }\`` returns TemplateResult<Operation>.
+* Creates a curried function for a specific operation type.
+* Supports both tagged template and options object dispatch.
+*
+* Tagged template: `query("name")\`($var: Type!) { fields }\`` returns TemplateResult<Operation>.
+* Options object: `query("name")({ variables, fields })` returns TemplateResult<Operation>.
 *
 * @param schema - The GraphQL schema definition
 * @param operationType - The operation type (query, mutation, subscription)
@@ -2965,264 +3056,99 @@ const resolveMetadataOption = (metadataOption) => {
 const createOperationTaggedTemplate = (schema, operationType, metadataAdapter, adapterTransformDocument) => {
 	const schemaIndex = createSchemaIndexFromSchema(schema);
 	return (operationName) => {
-		return (strings, ...values) => {
-			for (let i = 0; i < values.length; i++) {
-				const value = values[i];
-				if (!(value instanceof Fragment) && typeof value !== "function") throw new Error(`Tagged templates only accept Fragment instances or callback functions as interpolated values. Received ${typeof value} at position ${i}.`);
-			}
-			let body = strings[0] ?? "";
-			const interpolationMap = /* @__PURE__ */ new Map();
-			for (let i = 0; i < values.length; i++) {
-				const placeholderName = `__INTERPOLATION_${i}__`;
-				interpolationMap.set(placeholderName, values[i]);
-				body += placeholderName + (strings[i + 1] ?? "");
-			}
-			const source = buildSyntheticOperationSource(operationType, operationName, body);
-			let document;
-			try {
-				document = (0, graphql.parse)(source);
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				throw new Error(`GraphQL parse error in tagged template: ${message}`);
-			}
-			const opDefs = document.definitions.filter((def) => def.kind === graphql.Kind.OPERATION_DEFINITION);
-			if (opDefs.length !== 1) throw new Error(`Internal error: expected exactly one operation definition in synthesized source`);
-			const opNode = opDefs[0];
-			if (opNode.kind !== graphql.Kind.OPERATION_DEFINITION) throw new Error("Unexpected definition kind");
-			let varSpecifiers = buildVarSpecifiers(opNode.variableDefinitions ?? [], schemaIndex);
-			varSpecifiers = mergeVariableDefinitions(varSpecifiers, interpolationMap);
-			const operationTypeName = schema.operations[operationType];
-			if (operationTypeName === null) throw new Error(`Operation type ${operationType} is not defined in schema roots`);
-			const resolvedAdapter = metadataAdapter ?? defaultMetadataAdapter;
-			return (options) => {
-				const resolvedMetadata = resolveMetadataOption(options?.metadata);
-				if (interpolationMap.size === 0) return wrapArtifactAsOperation(() => buildOperationArtifact({
-					mode: "prebuilt",
-					schema,
-					operationType,
-					operationTypeName,
-					operationName,
-					variables: varSpecifiers,
-					prebuiltDocument: document,
-					prebuiltVariableNames: Object.keys(varSpecifiers),
-					adapter: resolvedAdapter,
-					metadata: resolvedMetadata,
-					adapterTransformDocument
-				}), true);
-				return wrapArtifactAsOperation(() => buildOperationArtifact({
-					mode: "fieldsFactory",
-					schema,
-					operationType,
-					operationTypeName,
-					operationName,
-					variables: varSpecifiers,
-					fieldsFactory: ({ $ }) => {
-						return buildFieldsFromSelectionSet(opNode.selectionSet, schema, operationTypeName, $, interpolationMap);
-					},
-					adapter: resolvedAdapter,
-					metadata: resolvedMetadata,
-					adapterTransformDocument
-				}), false);
-			};
+		const dispatch = (firstArg, ...rest) => {
+			if ("raw" in firstArg) return handleTaggedTemplate(schema, schemaIndex, operationType, operationName, metadataAdapter, adapterTransformDocument, firstArg, rest);
+			return handleOptionsObject(schema, schemaIndex, operationType, operationName, metadataAdapter, adapterTransformDocument, firstArg);
 		};
+		return dispatch;
 	};
 };
-
-//#endregion
-//#region packages/core/src/composer/var-ref-tools.ts
-/**
-* Recursively checks if a NestedValue contains any VarRef.
-*
-* Used by getVarRefValue to determine if it's safe to return as ConstValue.
-* @internal
-*/
-const hasVarRefInside = (value) => {
-	if (value instanceof VarRef) return true;
-	if (Array.isArray(value)) return value.some(hasVarRefInside);
-	if (typeof value === "object" && value !== null) return Object.values(value).some(hasVarRefInside);
-	return false;
-};
 /**
-* Get the variable name from a VarRef.
-* Throws if the VarRef contains a nested-value instead of a variable reference.
-*/
-const getVarRefName = (varRef) => {
-	const inner = VarRef.getInner(varRef);
-	if (inner.type !== "variable") throw new Error("Expected variable reference, got nested-value");
-	return inner.name;
-};
-/**
-* Get the const value from a VarRef.
-* Throws if the VarRef contains a variable reference instead of a nested-value,
-* or if the nested-value contains any VarRef inside.
+* Handles the tagged template path.
 */
-const getVarRefValue = (varRef) => {
-	const inner = VarRef.getInner(varRef);
-	if (inner.type !== "nested-value") throw new Error("Expected nested-value, got variable reference");
-	if (hasVarRefInside(inner.value)) throw new Error("Cannot get const value: nested-value contains VarRef");
-	return inner.value;
-};
-const SelectableProxyInnerRegistry = /* @__PURE__ */ new WeakMap();
-const getSelectableProxyInner = (proxy) => {
-	const inner = SelectableProxyInnerRegistry.get(proxy);
-	if (!inner) throw new Error(`Proxy inner not found`);
-	return inner;
-};
-const createSelectableProxy = (current) => {
-	const proxy = new Proxy(Object.create(null), { get(_, property) {
-		if (typeof property === "symbol") throw new Error(`Prohibited property access: ${String(property)}`);
-		const nextSegments = [...current.segments, property];
-		if (current.varInner.type === "virtual") return createSelectableProxy({
-			varInner: current.varInner,
-			segments: nextSegments
-		});
-		if (current.varInner.type === "variable") return createSelectableProxy({
-			varInner: {
-				type: "virtual",
-				varName: current.varInner.name,
-				varSegments: nextSegments
+function handleTaggedTemplate(schema, schemaIndex, operationType, operationName, metadataAdapter, adapterTransformDocument, strings, values) {
+	for (let i = 0; i < values.length; i++) {
+		const value = values[i];
+		if (!(value instanceof Fragment) && typeof value !== "function") throw new Error(`Tagged templates only accept Fragment instances or callback functions as interpolated values. Received ${typeof value} at position ${i}.`);
+	}
+	let body = strings[0] ?? "";
+	const interpolationMap = /* @__PURE__ */ new Map();
+	for (let i = 0; i < values.length; i++) {
+		const placeholderName = `__INTERPOLATION_${i}__`;
+		interpolationMap.set(placeholderName, values[i]);
+		body += placeholderName + (strings[i + 1] ?? "");
+	}
+	const source = buildSyntheticOperationSource(operationType, operationName, body);
+	let document;
+	try {
+		document = (0, graphql.parse)(source);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`GraphQL parse error in tagged template: ${message}`);
+	}
+	const opDefs = document.definitions.filter((def) => def.kind === graphql.Kind.OPERATION_DEFINITION);
+	if (opDefs.length !== 1) throw new Error(`Internal error: expected exactly one operation definition in synthesized source`);
+	const opNode = opDefs[0];
+	if (opNode.kind !== graphql.Kind.OPERATION_DEFINITION) throw new Error("Unexpected definition kind");
+	const varDefNodes = opNode.variableDefinitions ?? [];
+	let varSpecifiers = buildVarSpecifiers(varDefNodes, schemaIndex);
+	varSpecifiers = mergeVariableDefinitions(varSpecifiers, interpolationMap);
+	const hasInterpolatedFragmentVars = [...interpolationMap.values()].some((v) => v instanceof Fragment && Object.keys(v.variableDefinitions).length > 0);
+	const operationTypeName = schema.operations[operationType];
+	if (operationTypeName === null) throw new Error(`Operation type ${operationType} is not defined in schema roots`);
+	const resolvedAdapter = metadataAdapter ?? defaultMetadataAdapter;
+	return (options) => {
+		const resolvedMetadata = resolveMetadataOption(options?.metadata);
+		return wrapArtifactAsOperation(() => buildOperationArtifact({
+			schema,
+			operationType,
+			operationTypeName,
+			operationName,
+			variables: varSpecifiers,
+			variableDefinitionNodes: hasInterpolatedFragmentVars ? void 0 : varDefNodes,
+			fieldsFactory: ({ $ }) => {
+				return buildFieldsFromSelectionSet(filterUnresolvedFragmentSpreads(opNode.selectionSet, interpolationMap), schema, operationTypeName, $, interpolationMap);
 			},
-			segments: nextSegments
-		});
-		if (typeof current.varInner.value === "object" && current.varInner.value !== null) {
-			const value = current.varInner.value[property];
-			return createSelectableProxy({
-				varInner: value instanceof VarRef ? VarRef.getInner(value) : {
-					type: "nested-value",
-					value
-				},
-				segments: nextSegments
-			});
-		}
-		throw new Error(`Cannot access children of primitive value at path [${current.segments.join(".")}]`);
-	} });
-	SelectableProxyInnerRegistry.set(proxy, current);
-	return proxy;
-};
-/**
-* Get the variable name from a VarRef at a specific path.
-*
-* @param varRef - The VarRef containing a nested-value
-* @param selector - Path builder function, e.g., p => p.user.age
-* @returns The variable name at the specified path
-* @throws If path doesn't lead to a VarRef with type "variable"
-*
-* @example
-* const ref = createVarRefFromNestedValue({
-*   user: { age: someVariableRef }
-* });
-* getNameAt(ref, p => p.user.age); // returns the variable name
-*/
-const getNameAt = (varRef, selector) => {
-	const inner = getSelectableProxyInner(selector(createSelectableProxy({
-		varInner: VarRef.getInner(varRef),
-		segments: []
-	})));
-	if (inner.varInner.type === "virtual") throw new Error(`Value at path [${inner.segments.join(".")}] is inside a variable`);
-	if (inner.varInner.type !== "variable") throw new Error(`Value at path [${inner.segments.join(".")}] is not a variable`);
-	return inner.varInner.name;
-};
-/**
-* Get the const value from a nested-value VarRef at a specific path.
-*
-* @param varRef - The VarRef containing a nested-value
-* @param pathFn - Path builder function, e.g., p => p.user.name
-* @returns The const value at the specified path
-* @throws If path leads to a VarRef or if value contains VarRef inside
-*
-* @example
-* const ref = createVarRefFromNestedValue({
-*   user: { name: "Alice", age: someVariableRef }
-* });
-* getValueAt(ref, p => p.user.name); // returns "Alice"
-*/
-const getValueAt = (varRef, selector) => {
-	const inner = getSelectableProxyInner(selector(createSelectableProxy({
-		varInner: VarRef.getInner(varRef),
-		segments: []
-	})));
-	if (inner.varInner.type === "virtual") throw new Error(`Value at path [${inner.segments.join(".")}] is inside a variable`);
-	if (inner.varInner.type !== "nested-value") throw new Error(`Value at path [${inner.segments.join(".")}] is not a nested-value`);
-	if (hasVarRefInside(inner.varInner.value)) throw new Error(`Value at path [${inner.segments.join(".")}] contains nested VarRef`);
-	return inner.varInner.value;
-};
-/**
-* Gets the full path to a variable within a nested structure.
-*
-* Returns path segments starting with `$variableName` followed by
-* property accesses within that variable's value.
-*
-* @example
-* ```typescript
-* getVariablePath($.filter, p => p.user.id)
-* // Returns: ["$filter", "user", "id"]
-* ```
-*/
-const getVariablePath = (varRef, selector) => {
-	const inner = getSelectableProxyInner(selector(createSelectableProxy({
-		varInner: VarRef.getInner(varRef),
-		segments: []
-	})));
-	if (inner.varInner.type === "virtual") return [`$${inner.varInner.varName}`, ...inner.segments.slice(inner.varInner.varSegments.length)];
-	if (inner.varInner.type === "variable") return [`$${inner.varInner.name}`];
-	throw new Error(`Value at path [${inner.segments.join(".")}] is not a variable or inside a variable`);
-};
-
-//#endregion
-//#region packages/core/src/composer/var-builder.ts
-/**
-* Creates a factory function for generating schema-scoped variable methods.
-* This ensures proper type inference for nested input objects by binding the schema type upfront.
-*
-* @example
-* ```typescript
-* const createMethod = createVarMethodFactory<typeof schema>();
-* const inputTypeMethods = {
-*   Boolean: createMethod("scalar", "Boolean"),
-*   user_bool_exp: createMethod("input", "user_bool_exp"),
-* } satisfies InputTypeMethods<typeof schema>;
-* ```
-*/
-const createVarMethodFactory = () => {
-	return (kind, typeName) => {
-		return ((modifier, extras) => ({
-			kind,
-			name: typeName,
-			modifier,
-			defaultValue: extras?.default ? { default: extras.default() } : null,
-			directives: extras?.directives ?? {}
+			adapter: resolvedAdapter,
+			metadata: resolvedMetadata,
+			transformDocument: options?.transformDocument,
+			adapterTransformDocument
 		}));
 	};
-};
+}
 /**
-* Creates a variable builder using injected input type methods.
-*
-* The returned builder provides type-safe variable definition methods
-* for all input types in the schema. Also includes utilities for
-* extracting variable names and values from VarRefs.
-*
-* @param inputTypeMethods - Methods for each input type (from codegen)
-* @returns Variable builder with methods for all input types
-*
-* @internal Used by `createGqlElementComposer`
+* Handles the options object path.
 */
-const createVarBuilder = (inputTypeMethods) => {
-	const varBuilder = (varName) => {
-		const wrappedMethods = {};
-		for (const [typeName, method] of Object.entries(inputTypeMethods)) Object.defineProperty(wrappedMethods, typeName, {
-			value: ((modifier, extras) => require_schema_builder.wrapByKey(varName, method(modifier, extras))),
-			writable: false,
-			configurable: true
-		});
-		return wrappedMethods;
+function handleOptionsObject(schema, schemaIndex, operationType, operationName, metadataAdapter, adapterTransformDocument, options) {
+	let varSpecifiers = {};
+	let varDefNodes = [];
+	if (options.variables) {
+		const opDef = (0, graphql.parse)(`query __var_parse__ ${String(options.variables).trim()} { __typename }`).definitions[0];
+		if (opDef?.kind === graphql.Kind.OPERATION_DEFINITION) {
+			varDefNodes = opDef.variableDefinitions ?? [];
+			varSpecifiers = buildVarSpecifiers(varDefNodes, schemaIndex);
+		}
+	}
+	const operationTypeName = schema.operations[operationType];
+	if (operationTypeName === null) throw new Error(`Operation type ${operationType} is not defined in schema roots`);
+	const resolvedAdapter = metadataAdapter ?? defaultMetadataAdapter;
+	return (step2Options) => {
+		const resolvedMetadata = resolveMetadataOption(step2Options?.metadata);
+		return wrapArtifactAsOperation(() => buildOperationArtifact({
+			schema,
+			operationType,
+			operationTypeName,
+			operationName,
+			variables: varSpecifiers,
+			variableDefinitionNodes: varDefNodes,
+			fieldsFactory: options.fields,
+			adapter: resolvedAdapter,
+			metadata: resolvedMetadata,
+			transformDocument: step2Options?.transformDocument,
+			adapterTransformDocument
+		}));
 	};
-	varBuilder.getName = getVarRefName;
-	varBuilder.getValue = getVarRefValue;
-	varBuilder.getNameAt = getNameAt;
-	varBuilder.getValueAt = getValueAt;
-	varBuilder.getVariablePath = getVariablePath;
-	return varBuilder;
-};
+}
 
 //#endregion
 //#region packages/core/src/composer/gql-composer.ts
@@ -3232,57 +3158,37 @@ const createVarBuilder = (inputTypeMethods) => {
 * This is the main entry point for defining GraphQL operations and fragments.
 * The returned function provides a context with:
 * - `fragment`: Tagged template function for fragment definitions
-* - `query/mutation/subscription`: Operation builders
-* - `$var`: Variable definition helpers
+* - `query/mutation/subscription`: Operation builders (tagged template + options object + .compat)
 * - `$dir`: Field directive helpers (@skip, @include)
 * - `$colocate`: Fragment colocation utilities
 *
 * @param schema - The GraphQL schema definition
-* @param options - Configuration including input type methods and optional adapter
+* @param options - Configuration including optional adapter
 * @returns Element composer function
 *
 * @example
 * ```typescript
-* const gql = createGqlElementComposer(schema, { inputTypeMethods });
-*
-* const GetUser = gql(({ query, $var, $dir }) =>
-*   query.operation({
-*     name: "GetUser",
-*     variables: { showEmail: $var("showEmail").Boolean("!") },
-*     fields: ({ f, $ }) => ({
-*       ...f.user({ id: "1" })(({ f }) => ({
-*         ...f.name(),
-*         ...f.email({}, { directives: [$dir.skip({ if: $.showEmail })] }),
-*       })),
-*     }),
-*   })
+* const gql = createGqlElementComposer(schema, {});
+*
+* const GetUser = gql(({ query, $dir }) =>
+*   query("GetUser")`($id: ID!) {
+*     user(id: $id) { name email }
+*   }`()
 * );
 * ```
 */
 const createGqlElementComposer = (schema, options) => {
-	const { adapter, inputTypeMethods, directiveMethods } = options;
+	const { adapter, directiveMethods } = options;
 	const helpers = adapter?.helpers;
 	const metadataAdapter = adapter?.metadata;
 	const transformDocument = adapter?.transformDocument;
-	const fragment = createFragmentTaggedTemplate(schema);
-	const createOperationComposer = createOperationComposerFactory(schema, metadataAdapter, transformDocument);
 	const transformedContext = require_context_transformer.applyContextTransformer({
-		fragment,
-		query: Object.assign(createOperationTaggedTemplate(schema, "query", metadataAdapter, transformDocument), {
-			operation: createOperationComposer("query"),
-			compat: createCompatTaggedTemplate(schema, "query")
-		}),
-		mutation: Object.assign(createOperationTaggedTemplate(schema, "mutation", metadataAdapter, transformDocument), {
-			operation: createOperationComposer("mutation"),
-			compat: createCompatTaggedTemplate(schema, "mutation")
-		}),
-		subscription: Object.assign(createOperationTaggedTemplate(schema, "subscription", metadataAdapter, transformDocument), {
-			operation: createOperationComposer("subscription"),
-			compat: createCompatTaggedTemplate(schema, "subscription")
-		}),
+		fragment: createFragmentTaggedTemplate(schema),
+		query: Object.assign(createOperationTaggedTemplate(schema, "query", metadataAdapter, transformDocument), { compat: createCompatTaggedTemplate(schema, "query") }),
+		mutation: Object.assign(createOperationTaggedTemplate(schema, "mutation", metadataAdapter, transformDocument), { compat: createCompatTaggedTemplate(schema, "mutation") }),
+		subscription: Object.assign(createOperationTaggedTemplate(schema, "subscription", metadataAdapter, transformDocument), { compat: createCompatTaggedTemplate(schema, "subscription") }),
 		define: (factory) => GqlDefine.create(factory),
 		extend: createExtendComposer(schema, metadataAdapter, transformDocument),
-		$var: createVarBuilder(inputTypeMethods),
 		$dir: directiveMethods ?? createStandardDirectives(),
 		$colocate: createColocateHelper(),
 		...helpers ?? {}
@@ -3453,15 +3359,15 @@ const calculateUnionType = (schema, union, formatters, unionTypeName) => {
 		if (unionDef) {
 			const allMemberNames = Object.keys(unionDef.types);
 			for (const typeName of allMemberNames) {
-				const fields = selections[typeName];
-				if (fields && typeof fields === "object") {
-					const fieldsType = calculateFieldsType(schema, fields, formatters, typeName);
+				const member = selections[typeName];
+				if (member && typeof member === "object") {
+					const fieldsType = calculateFieldsType(schema, member.fields, formatters, typeName);
 					memberTypes.push(`${fieldsType} & { readonly __typename: "${typeName}" }`);
 				} else memberTypes.push(`{ readonly __typename: "${typeName}" }`);
 			}
 		}
-	} else for (const [typeName, fields] of Object.entries(selections)) if (fields && typeof fields === "object") {
-		const memberType = calculateFieldsType(schema, fields, formatters, typeName);
+	} else for (const [typeName, member] of Object.entries(selections)) if (member && typeof member === "object") {
+		const memberType = calculateFieldsType(schema, member.fields, formatters, typeName);
 		memberTypes.push(memberType);
 	}
 	if (memberTypes.length === 0) return "never";
@@ -3603,7 +3509,7 @@ const generateInputTypeFromSpecifiers = (schema, specifiers, options = {}) => {
 * Generate a TypeScript type string for input variables from VariableDefinitions.
 *
 * Unlike generateInputTypeFromSpecifiers which works with deferred specifier strings,
-* this function works with VarSpecifier objects created by $var().
+* this function works with VarSpecifier objects from variable definitions.
 * Used for generating Fragment input types in prebuilt mode.
 *
 * @param schema - The GraphQL schema
@@ -3642,7 +3548,6 @@ exports.calculateFieldType = calculateFieldType;
 exports.calculateFieldsType = calculateFieldsType;
 exports.collectVariableUsages = collectVariableUsages;
 exports.createColocateHelper = createColocateHelper;
-exports.createCompatComposer = createCompatComposer;
 exports.createCompatTaggedTemplate = createCompatTaggedTemplate;
 exports.createDefaultAdapter = createDefaultAdapter;
 exports.createDirectiveBuilder = createDirectiveBuilder;
@@ -3651,15 +3556,12 @@ exports.createExtendComposer = createExtendComposer;
 exports.createFieldFactories = createFieldFactories;
 exports.createFragmentTaggedTemplate = createFragmentTaggedTemplate;
 exports.createGqlElementComposer = createGqlElementComposer;
-exports.createOperationComposerFactory = createOperationComposerFactory;
 exports.createOperationTaggedTemplate = createOperationTaggedTemplate;
 exports.createSchemaIndex = createSchemaIndex;
 exports.createSchemaIndexFromSchema = createSchemaIndexFromSchema;
 exports.createStandardDirectives = createStandardDirectives;
 exports.createTypedDirectiveMethod = createTypedDirectiveMethod;
 exports.createVarAssignments = createVarAssignments;
-exports.createVarBuilder = createVarBuilder;
-exports.createVarMethodFactory = createVarMethodFactory;
 exports.createVarRefFromVariable = createVarRefFromVariable;
 exports.createVarRefs = createVarRefs;
 exports.defaultMetadataAdapter = defaultMetadataAdapter;
@@ -3668,6 +3570,7 @@ exports.defineOperationRoots = require_schema_builder.defineOperationRoots;
 exports.defineScalar = require_schema_builder.defineScalar;
 exports.err = err;
 exports.extractFragmentVariables = extractFragmentVariables;
+exports.filterUnresolvedFragmentSpreads = filterUnresolvedFragmentSpreads;
 exports.generateInputObjectType = generateInputObjectType;
 exports.generateInputType = generateInputType;
 exports.generateInputTypeFromSpecifiers = generateInputTypeFromSpecifiers;
@@ -3677,14 +3580,19 @@ exports.getCurrentFieldPath = getCurrentFieldPath;
 exports.getEnumType = getEnumType;
 exports.getFieldReturnType = getFieldReturnType;
 exports.getInputFieldType = getInputFieldType;
+exports.getNameAt = getNameAt;
 exports.getScalarInputType = getScalarInputType;
 exports.getScalarOutputType = getScalarOutputType;
+exports.getValueAt = getValueAt;
+exports.getVarRefName = getVarRefName;
+exports.getVarRefValue = getVarRefValue;
+exports.getVariablePath = getVariablePath;
 exports.graphqlTypeToTypeScript = graphqlTypeToTypeScript;
+exports.hasVarRefInside = hasVarRefInside;
 exports.inferVariablesFromUsages = inferVariablesFromUsages;
 exports.isDirectiveRef = isDirectiveRef;
 exports.isListType = isListType;
 exports.isModifierAssignable = isModifierAssignable;
-exports.isTemplateCompatSpec = isTemplateCompatSpec;
 exports.mergeModifiers = mergeModifiers;
 exports.mergeVariableUsages = mergeVariableUsages;
 exports.ok = ok;
@@ -3696,6 +3604,7 @@ exports.preprocessFragmentArgs = preprocessFragmentArgs;
 exports.recordFragmentUsage = recordFragmentUsage;
 exports.sortFragmentsByDependency = sortFragmentsByDependency;
 exports.transformParsedGraphql = transformParsedGraphql;
+exports.varRefTools = varRefTools;
 exports.withFieldPath = withFieldPath;
 exports.withFragmentUsageCollection = withFragmentUsageCollection;
 exports.wrapArtifactAsOperation = wrapArtifactAsOperation;