@soda-gql/core 0.11.25 → 0.12.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { t as applyContextTransformer } from "./context-transformer-sAzKGoyJ.js";
 import { i as wrapByKey, n as defineOperationRoots, r as defineScalar, t as defineEnum } from "./schema-builder-oVVErGOB.js";
-import { Kind, OperationTypeNode } from "graphql";
+import { Kind, OperationTypeNode, parse } from "graphql";
 
 //#region packages/core/src/types/type-foundation/var-ref.ts
 var VarRef = class {
@@ -68,13 +68,15 @@ var DirectiveRef = class {
 const INPUT_KIND_MAP = {
 	s: "scalar",
 	e: "enum",
-	i: "input"
+	i: "input",
+	x: "excluded"
 };
 const OUTPUT_KIND_MAP = {
 	s: "scalar",
 	e: "enum",
 	o: "object",
-	u: "union"
+	u: "union",
+	x: "excluded"
 };
 /**
 * Parse a deferred input specifier string into a structured object.
@@ -91,7 +93,8 @@ function parseInputSpecifier(spec) {
 	const parts = spec.split("|");
 	const kindChar = parts[0];
 	const name = parts[1];
-	const modifier = hasDefault ? parts[2] : parts.slice(2).join("|");
+	if (!kindChar || !name) throw new Error(`Invalid input specifier format: ${spec}`);
+	const modifier = hasDefault ? parts[2] ?? "" : parts.slice(2).join("|");
 	const kind = INPUT_KIND_MAP[kindChar];
 	if (!kind) throw new Error(`Invalid input specifier kind: ${kindChar}`);
 	return {
@@ -115,6 +118,7 @@ function parseOutputSpecifier(spec) {
 	const kindChar = parts[0];
 	const name = parts[1];
 	const modifier = parts[2];
+	if (!kindChar || !name || modifier === void 0) throw new Error(`Invalid output specifier format: ${spec}`);
 	const kind = OUTPUT_KIND_MAP[kindChar];
 	if (!kind) throw new Error(`Invalid output specifier kind: ${kindChar}`);
 	return {
@@ -368,6 +372,14 @@ const buildUnionSelection = (union, schema) => {
 * @param typeName - Parent type name (required for shorthand expansion)
 */
 const buildField = (fields, schema, typeName) => Object.entries(fields).map(([alias, value]) => {
+	if (alias === "__typename" && isShorthand(value)) return {
+		kind: Kind.FIELD,
+		name: {
+			kind: Kind.NAME,
+			value: "__typename"
+		}
+	};
+	if (isShorthand(value) && !typeName) throw new Error(`typeName is required for shorthand expansion of field "${alias}"`);
 	const { args, field, object, union, directives, type } = isShorthand(value) ? expandShorthand(schema, typeName, alias) : value;
 	const parsedType = parseOutputField(type);
 	const builtDirectives = buildDirectives(directives, "FIELD", schema);
@@ -634,6 +646,16 @@ 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
 /**
@@ -998,6 +1020,46 @@ const createCompatComposer = (schema, operationType) => {
 	};
 };
 
+//#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
+*/
+/**
+* Creates a curried tagged template function for compat mode operations.
+* New API: `query.compat("name")\`($vars) { fields }\`` returns GqlDefine<TemplateCompatSpec>.
+*
+* @param schema - The GraphQL schema definition
+* @param operationType - The operation type (query, mutation, subscription)
+*/
+const createCompatTaggedTemplate = (schema, operationType) => {
+	if (schema.operations[operationType] === null) throw new Error(`Operation type ${operationType} is not defined in schema roots`);
+	return (operationName) => {
+		return (strings, ...values) => {
+			if (values.length > 0) throw new Error("Tagged templates must not contain interpolated expressions");
+			const source = `${operationType} ${operationName} ${(strings[0] ?? "").trim()}`;
+			let document;
+			try {
+				document = 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 === Kind.OPERATION_DEFINITION);
+			if (opDefs.length !== 1) throw new Error(`Internal error: expected exactly one operation definition in synthesized source`);
+			if (opDefs[0].kind !== Kind.OPERATION_DEFINITION) throw new Error("Unexpected definition kind");
+			return GqlDefine.create(() => ({
+				schema,
+				operationType,
+				operationName,
+				graphqlSource: source
+			}));
+		};
+	};
+};
+
 //#endregion
 //#region packages/core/src/composer/directive-builder.ts
 /**
@@ -1104,6 +1166,981 @@ const isDirectiveRef = (value) => {
 	return value instanceof DirectiveRef;
 };
 
+//#endregion
+//#region packages/core/src/graphql/fragment-args-preprocessor.ts
+/**
+* Find the matching closing parenthesis for a balanced group.
+* Handles nested parentheses, string literals, and comments.
+* Returns the index of the closing ')' or -1 if not found.
+*/
+const findMatchingParen = (content, openIndex) => {
+	let depth = 1;
+	let inString = false;
+	for (let i = openIndex + 1; i < content.length; i++) {
+		const ch = content[i];
+		if (inString) {
+			if (ch === inString) {
+				let backslashes = 0;
+				for (let j = i - 1; j >= 0 && content[j] === "\\"; j--) backslashes++;
+				if (backslashes % 2 === 0) inString = false;
+			}
+			continue;
+		}
+		if (ch === "\"" || ch === "'") {
+			inString = ch;
+			continue;
+		}
+		if (ch === "(") depth++;
+		else if (ch === ")") {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+};
+/**
+* Replace a range [start, end] (inclusive) with spaces, preserving newlines.
+*/
+const replaceWithSpaces = (content, start, end) => {
+	let result = content.slice(0, start);
+	for (let i = start; i <= end; i++) result += content[i] === "\n" ? "\n" : " ";
+	result += content.slice(end + 1);
+	return result;
+};
+const FRAGMENT_DEF_PATTERN = /\bfragment\s+(\w+)\s*\(/g;
+const FRAGMENT_SPREAD_PATTERN = /\.\.\.(\w+)\s*\(/g;
+/**
+* Preprocess Fragment Arguments RFC syntax by replacing argument lists with spaces.
+*
+* Transforms:
+* - `fragment UserProfile($showEmail: Boolean = false) on User` -> `fragment UserProfile                               on User`
+* - `...UserProfile(showEmail: true)` -> `...UserProfile                  `
+*/
+const preprocessFragmentArgs = (content) => {
+	let result = content;
+	let modified = false;
+	let match;
+	FRAGMENT_DEF_PATTERN.lastIndex = 0;
+	while ((match = FRAGMENT_DEF_PATTERN.exec(result)) !== null) {
+		const openParenIndex = match.index + match[0].length - 1;
+		const closeParenIndex = findMatchingParen(result, openParenIndex);
+		if (closeParenIndex === -1) continue;
+		if (!result.slice(closeParenIndex + 1).trimStart().startsWith("on")) continue;
+		result = replaceWithSpaces(result, openParenIndex, closeParenIndex);
+		modified = true;
+		FRAGMENT_DEF_PATTERN.lastIndex = 0;
+	}
+	FRAGMENT_SPREAD_PATTERN.lastIndex = 0;
+	while ((match = FRAGMENT_SPREAD_PATTERN.exec(result)) !== null) {
+		const openParenIndex = match.index + match[0].length - 1;
+		const closeParenIndex = findMatchingParen(result, openParenIndex);
+		if (closeParenIndex === -1) continue;
+		result = replaceWithSpaces(result, openParenIndex, closeParenIndex);
+		modified = true;
+		FRAGMENT_SPREAD_PATTERN.lastIndex = 0;
+	}
+	return {
+		preprocessed: result,
+		modified
+	};
+};
+
+//#endregion
+//#region packages/core/src/graphql/result.ts
+/** Create a successful Result */
+const ok = (value) => ({
+	ok: true,
+	value
+});
+/** Create a failed Result */
+const err = (error) => ({
+	ok: false,
+	error
+});
+
+//#endregion
+//#region packages/core/src/graphql/parser.ts
+/**
+* GraphQL parser utilities.
+* Extracts operations and fragments from GraphQL source strings.
+* @module
+*/
+/** Parse GraphQL source string directly. No file I/O. */
+const parseGraphqlSource = (source, sourceFile) => {
+	try {
+		const document = parse(source);
+		return ok({
+			document,
+			...extractFromDocument(document, sourceFile)
+		});
+	} catch (error) {
+		return err({
+			code: "GRAPHQL_PARSE_ERROR",
+			message: `GraphQL parse error: ${error instanceof Error ? error.message : String(error)}`,
+			filePath: sourceFile
+		});
+	}
+};
+/**
+* Parse a GraphQL TypeNode into type name and modifier.
+*
+* Format: inner nullability + list modifiers
+* - Inner: `!` (non-null) or `?` (nullable)
+* - List: `[]!` (non-null list) or `[]?` (nullable list)
+*/
+const parseTypeNode = (node) => {
+	const levels = [];
+	const collect = (n, nonNull) => {
+		if (n.kind === Kind.NON_NULL_TYPE) return collect(n.type, true);
+		if (n.kind === Kind.LIST_TYPE) {
+			levels.push({
+				kind: "list",
+				nonNull
+			});
+			return collect(n.type, false);
+		}
+		levels.push({
+			kind: "named",
+			nonNull
+		});
+		return n.name.value;
+	};
+	const typeName = collect(node, false);
+	let modifier = "?";
+	for (const level of levels.slice().reverse()) {
+		if (level.kind === "named") {
+			modifier = level.nonNull ? "!" : "?";
+			continue;
+		}
+		const listSuffix = level.nonNull ? "[]!" : "[]?";
+		modifier = `${modifier}${listSuffix}`;
+	}
+	return {
+		typeName,
+		modifier
+	};
+};
+/** Extract operations and fragments from a parsed GraphQL document. */
+const extractFromDocument = (document, sourceFile) => {
+	const operations = [];
+	const fragments = [];
+	for (const definition of document.definitions) if (definition.kind === Kind.OPERATION_DEFINITION) {
+		const operation = extractOperation(definition, sourceFile);
+		if (operation) operations.push(operation);
+	} else if (definition.kind === Kind.FRAGMENT_DEFINITION) fragments.push(extractFragment(definition, sourceFile));
+	return {
+		operations,
+		fragments
+	};
+};
+/** Extract a single operation from an OperationDefinitionNode. */
+const extractOperation = (node, sourceFile) => {
+	if (!node.name) return null;
+	const variables = (node.variableDefinitions ?? []).map(extractVariable);
+	const selections = extractSelections(node.selectionSet.selections);
+	return {
+		kind: node.operation,
+		name: node.name.value,
+		variables,
+		selections,
+		sourceFile
+	};
+};
+/** Extract a fragment from a FragmentDefinitionNode. */
+const extractFragment = (node, sourceFile) => {
+	const selections = extractSelections(node.selectionSet.selections);
+	return {
+		name: node.name.value,
+		onType: node.typeCondition.name.value,
+		selections,
+		sourceFile
+	};
+};
+/** Extract a variable definition. */
+const extractVariable = (node) => {
+	const { typeName, modifier } = parseTypeNode(node.type);
+	const defaultValue = node.defaultValue ? extractValue(node.defaultValue) : void 0;
+	return {
+		name: node.variable.name.value,
+		typeName,
+		modifier,
+		typeKind: "scalar",
+		defaultValue
+	};
+};
+/** Extract selections from a SelectionSet. */
+const extractSelections = (selections) => {
+	return selections.map(extractSelection);
+};
+/** Extract a single selection. */
+const extractSelection = (node) => {
+	switch (node.kind) {
+		case Kind.FIELD: return extractFieldSelection(node);
+		case Kind.FRAGMENT_SPREAD: return extractFragmentSpread(node);
+		case Kind.INLINE_FRAGMENT: return extractInlineFragment(node);
+	}
+};
+/** Extract a field selection. */
+const extractFieldSelection = (node) => {
+	const args = node.arguments?.length ? node.arguments.map(extractArgument) : void 0;
+	const selections = node.selectionSet ? extractSelections(node.selectionSet.selections) : void 0;
+	return {
+		kind: "field",
+		name: node.name.value,
+		alias: node.alias?.value,
+		arguments: args,
+		selections
+	};
+};
+/** Extract a fragment spread. */
+const extractFragmentSpread = (node) => {
+	return {
+		kind: "fragmentSpread",
+		name: node.name.value
+	};
+};
+/** Extract an inline fragment. */
+const extractInlineFragment = (node) => {
+	return {
+		kind: "inlineFragment",
+		onType: node.typeCondition?.name.value ?? "",
+		selections: extractSelections(node.selectionSet.selections)
+	};
+};
+/** Extract an argument. */
+const extractArgument = (node) => {
+	return {
+		name: node.name.value,
+		value: extractValue(node.value)
+	};
+};
+/** Assert unreachable code path (for exhaustiveness checks). */
+const assertUnreachable = (value) => {
+	throw new Error(`Unexpected value: ${JSON.stringify(value)}`);
+};
+/** Extract a value (literal or variable reference). */
+const extractValue = (node) => {
+	switch (node.kind) {
+		case Kind.VARIABLE: return {
+			kind: "variable",
+			name: node.name.value
+		};
+		case Kind.INT: return {
+			kind: "int",
+			value: node.value
+		};
+		case Kind.FLOAT: return {
+			kind: "float",
+			value: node.value
+		};
+		case Kind.STRING: return {
+			kind: "string",
+			value: node.value
+		};
+		case Kind.BOOLEAN: return {
+			kind: "boolean",
+			value: node.value
+		};
+		case Kind.NULL: return { kind: "null" };
+		case Kind.ENUM: return {
+			kind: "enum",
+			value: node.value
+		};
+		case Kind.LIST: return {
+			kind: "list",
+			values: node.values.map(extractValue)
+		};
+		case Kind.OBJECT: return {
+			kind: "object",
+			fields: node.fields.map((field) => ({
+				name: field.name.value,
+				value: extractValue(field.value)
+			}))
+		};
+		default: return assertUnreachable(node);
+	}
+};
+
+//#endregion
+//#region packages/core/src/graphql/schema-adapter.ts
+/**
+* Create a minimal SchemaIndex from AnyGraphqlSchema.
+*
+* IMPORTANT: This adapter produces a "name-resolution only" SchemaIndex.
+* Only the name-level Maps are populated (.has() lookups work).
+* Field-level data (FieldDefinitionNode, InputValueDefinitionNode, etc.)
+* is NOT populated -- those Maps are empty.
+*
+* Use this when you need SchemaIndex for type kind resolution only
+* (e.g., buildVarSpecifier). For full SchemaIndex with field-level data,
+* use createSchemaIndex(DocumentNode) from schema-index.ts.
+*/
+const createSchemaIndexFromSchema = (schema) => {
+	const scalars = new Map(Object.keys(schema.scalar).map((n) => [n, {
+		name: n,
+		directives: []
+	}]));
+	const enums = new Map(Object.keys(schema.enum).map((n) => [n, {
+		name: n,
+		values: /* @__PURE__ */ new Map(),
+		directives: []
+	}]));
+	const inputs = new Map(Object.keys(schema.input).map((n) => [n, {
+		name: n,
+		fields: /* @__PURE__ */ new Map(),
+		directives: []
+	}]));
+	return {
+		objects: new Map(Object.keys(schema.object).map((n) => [n, {
+			name: n,
+			fields: /* @__PURE__ */ new Map(),
+			directives: []
+		}])),
+		inputs,
+		enums,
+		unions: new Map(Object.keys(schema.union).map((n) => [n, {
+			name: n,
+			members: /* @__PURE__ */ new Map(),
+			directives: []
+		}])),
+		scalars,
+		directives: /* @__PURE__ */ new Map(),
+		operationTypes: {
+			query: schema.operations.query ?? void 0,
+			mutation: schema.operations.mutation ?? void 0,
+			subscription: schema.operations.subscription ?? void 0
+		}
+	};
+};
+
+//#endregion
+//#region packages/core/src/graphql/schema-index.ts
+const ensureRecord = (collection, key, factory) => {
+	const existing = collection.get(key);
+	if (existing) return existing;
+	const created = factory(key);
+	collection.set(key, created);
+	return created;
+};
+const addObjectFields = (target, fields) => {
+	if (!fields) return;
+	for (const field of fields) target.set(field.name.value, field);
+};
+const addInputFields = (target, fields) => {
+	if (!fields) return;
+	for (const field of fields) target.set(field.name.value, field);
+};
+const addEnumValues = (target, values) => {
+	if (!values) return;
+	for (const value of values) target.set(value.name.value, value);
+};
+const addUnionMembers = (target, members) => {
+	if (!members) return;
+	for (const member of members) target.set(member.name.value, member);
+};
+const mergeDirectives = (existing, incoming, precedence) => {
+	const current = existing ?? [];
+	const next = incoming ? Array.from(incoming) : [];
+	return precedence === "definition" ? [...next, ...current] : [...current, ...next];
+};
+const updateOperationTypes = (operationTypes, definition) => {
+	for (const operation of definition.operationTypes ?? []) {
+		const typeName = operation.type.name.value;
+		switch (operation.operation) {
+			case "query":
+				operationTypes.query = typeName;
+				break;
+			case "mutation":
+				operationTypes.mutation = typeName;
+				break;
+			case "subscription":
+				operationTypes.subscription = typeName;
+				break;
+			default: break;
+		}
+	}
+};
+const addDirectiveArgs = (target, args) => {
+	if (!args) return;
+	for (const arg of args) target.set(arg.name.value, arg);
+};
+/** Build a schema index from a parsed GraphQL schema document. */
+const createSchemaIndex = (document) => {
+	const objects = /* @__PURE__ */ new Map();
+	const inputs = /* @__PURE__ */ new Map();
+	const enums = /* @__PURE__ */ new Map();
+	const unions = /* @__PURE__ */ new Map();
+	const scalars = /* @__PURE__ */ new Map();
+	const directives = /* @__PURE__ */ new Map();
+	const operationTypes = {};
+	for (const definition of document.definitions) switch (definition.kind) {
+		case Kind.OBJECT_TYPE_DEFINITION:
+		case Kind.OBJECT_TYPE_EXTENSION: {
+			const precedence = definition.kind === Kind.OBJECT_TYPE_DEFINITION ? "definition" : "extension";
+			const record = ensureRecord(objects, definition.name.value, (name) => ({
+				name,
+				fields: /* @__PURE__ */ new Map(),
+				directives: []
+			}));
+			addObjectFields(record.fields, definition.fields);
+			record.directives = mergeDirectives(record.directives, definition.directives, precedence);
+			break;
+		}
+		case Kind.INPUT_OBJECT_TYPE_DEFINITION:
+		case Kind.INPUT_OBJECT_TYPE_EXTENSION: {
+			const precedence = definition.kind === Kind.INPUT_OBJECT_TYPE_DEFINITION ? "definition" : "extension";
+			const record = ensureRecord(inputs, definition.name.value, (name) => ({
+				name,
+				fields: /* @__PURE__ */ new Map(),
+				directives: []
+			}));
+			addInputFields(record.fields, definition.fields);
+			record.directives = mergeDirectives(record.directives, definition.directives, precedence);
+			break;
+		}
+		case Kind.ENUM_TYPE_DEFINITION:
+		case Kind.ENUM_TYPE_EXTENSION: {
+			const precedence = definition.kind === Kind.ENUM_TYPE_DEFINITION ? "definition" : "extension";
+			const record = ensureRecord(enums, definition.name.value, (name) => ({
+				name,
+				values: /* @__PURE__ */ new Map(),
+				directives: []
+			}));
+			addEnumValues(record.values, definition.values);
+			record.directives = mergeDirectives(record.directives, definition.directives, precedence);
+			break;
+		}
+		case Kind.UNION_TYPE_DEFINITION:
+		case Kind.UNION_TYPE_EXTENSION: {
+			const precedence = definition.kind === Kind.UNION_TYPE_DEFINITION ? "definition" : "extension";
+			const record = ensureRecord(unions, definition.name.value, (name) => ({
+				name,
+				members: /* @__PURE__ */ new Map(),
+				directives: []
+			}));
+			addUnionMembers(record.members, definition.types);
+			record.directives = mergeDirectives(record.directives, definition.directives, precedence);
+			break;
+		}
+		case Kind.SCALAR_TYPE_DEFINITION:
+		case Kind.SCALAR_TYPE_EXTENSION: {
+			const precedence = definition.kind === Kind.SCALAR_TYPE_DEFINITION ? "definition" : "extension";
+			const record = ensureRecord(scalars, definition.name.value, (name) => ({
+				name,
+				directives: []
+			}));
+			record.directives = mergeDirectives(record.directives, definition.directives, precedence);
+			break;
+		}
+		case Kind.DIRECTIVE_DEFINITION: {
+			const name = definition.name.value;
+			if (name === "skip" || name === "include" || name === "deprecated" || name === "specifiedBy") break;
+			const args = /* @__PURE__ */ new Map();
+			addDirectiveArgs(args, definition.arguments);
+			directives.set(name, {
+				name,
+				locations: definition.locations.map((loc) => loc.value),
+				args,
+				isRepeatable: definition.repeatable
+			});
+			break;
+		}
+		case Kind.SCHEMA_DEFINITION:
+		case Kind.SCHEMA_EXTENSION:
+			updateOperationTypes(operationTypes, definition);
+			break;
+		default: break;
+	}
+	if (!operationTypes.query && objects.has("Query")) operationTypes.query = "Query";
+	if (!operationTypes.mutation && objects.has("Mutation")) operationTypes.mutation = "Mutation";
+	if (!operationTypes.subscription && objects.has("Subscription")) operationTypes.subscription = "Subscription";
+	return {
+		objects,
+		inputs,
+		enums,
+		unions,
+		scalars,
+		directives,
+		operationTypes
+	};
+};
+
+//#endregion
+//#region packages/core/src/graphql/transformer.ts
+const builtinScalarTypes$1 = new Set([
+	"ID",
+	"String",
+	"Int",
+	"Float",
+	"Boolean"
+]);
+const parseModifierStructure = (modifier) => {
+	const inner = modifier[0] === "!" ? "!" : "?";
+	const lists = [];
+	const listPattern = /\[\]([!?])/g;
+	let match;
+	while ((match = listPattern.exec(modifier)) !== null) lists.push(`[]${match[1]}`);
+	return {
+		inner,
+		lists
+	};
+};
+const buildModifier = (structure) => {
+	return structure.inner + structure.lists.join("");
+};
+const isModifierAssignable = (source, target) => {
+	const srcStruct = parseModifierStructure(source);
+	const tgtStruct = parseModifierStructure(target);
+	const depthDiff = tgtStruct.lists.length - srcStruct.lists.length;
+	if (depthDiff < 0 || depthDiff > 1) return false;
+	const tgtListsToCompare = depthDiff === 1 ? tgtStruct.lists.slice(1) : tgtStruct.lists;
+	if (depthDiff === 1 && srcStruct.lists.length === 0 && srcStruct.inner === "?" && tgtStruct.lists[0] === "[]!") return false;
+	if (srcStruct.inner === "?" && tgtStruct.inner === "!") return false;
+	for (let i = 0; i < srcStruct.lists.length; i++) {
+		const srcList = srcStruct.lists[i];
+		const tgtList = tgtListsToCompare[i];
+		if (srcList === "[]?" && tgtList === "[]!") return false;
+	}
+	return true;
+};
+const deriveMinimumModifier = (expectedModifier) => {
+	const struct = parseModifierStructure(expectedModifier);
+	if (struct.lists.length > 0) return buildModifier({
+		inner: struct.inner,
+		lists: struct.lists.slice(1)
+	});
+	return expectedModifier;
+};
+const mergeModifiers = (a, b) => {
+	const structA = parseModifierStructure(a);
+	const structB = parseModifierStructure(b);
+	if (structA.lists.length !== structB.lists.length) return {
+		ok: false,
+		reason: `Incompatible list depths: "${a}" has ${structA.lists.length} list level(s), "${b}" has ${structB.lists.length}`
+	};
+	const mergedInner = structA.inner === "!" || structB.inner === "!" ? "!" : "?";
+	const mergedLists = [];
+	for (let i = 0; i < structA.lists.length; i++) {
+		const listA = structA.lists[i];
+		const listB = structB.lists[i];
+		mergedLists.push(listA === "[]!" || listB === "[]!" ? "[]!" : "[]?");
+	}
+	return {
+		ok: true,
+		value: buildModifier({
+			inner: mergedInner,
+			lists: mergedLists
+		})
+	};
+};
+const getArgumentType = (schema, parentTypeName, fieldName, argumentName) => {
+	const objectRecord = schema.objects.get(parentTypeName);
+	if (!objectRecord) return null;
+	const fieldDef = objectRecord.fields.get(fieldName);
+	if (!fieldDef) return null;
+	const argDef = fieldDef.arguments?.find((arg) => arg.name.value === argumentName);
+	if (!argDef) return null;
+	return parseTypeNode(argDef.type);
+};
+const getInputFieldType = (schema, inputTypeName, fieldName) => {
+	const inputRecord = schema.inputs.get(inputTypeName);
+	if (!inputRecord) return null;
+	const fieldDef = inputRecord.fields.get(fieldName);
+	if (!fieldDef) return null;
+	return parseTypeNode(fieldDef.type);
+};
+const resolveTypeKindFromName = (schema, typeName) => {
+	if (isScalarName(schema, typeName)) return "scalar";
+	if (isEnumName(schema, typeName)) return "enum";
+	if (schema.inputs.has(typeName)) return "input";
+	return null;
+};
+const collectVariablesFromValue = (value, expectedTypeName, expectedModifier, schema, usages) => {
+	if (value.kind === "variable") {
+		const typeKind = resolveTypeKindFromName(schema, expectedTypeName);
+		if (!typeKind) return {
+			code: "GRAPHQL_UNKNOWN_TYPE",
+			message: `Unknown type "${expectedTypeName}" for variable "$${value.name}"`,
+			typeName: expectedTypeName
+		};
+		usages.push({
+			name: value.name,
+			typeName: expectedTypeName,
+			expectedModifier,
+			minimumModifier: deriveMinimumModifier(expectedModifier),
+			typeKind
+		});
+		return null;
+	}
+	if (value.kind === "object") {
+		for (const field of value.fields) {
+			const fieldType = getInputFieldType(schema, expectedTypeName, field.name);
+			if (!fieldType) return {
+				code: "GRAPHQL_UNKNOWN_FIELD",
+				message: `Unknown field "${field.name}" on input type "${expectedTypeName}"`,
+				typeName: expectedTypeName,
+				fieldName: field.name
+			};
+			const error = collectVariablesFromValue(field.value, fieldType.typeName, fieldType.modifier, schema, usages);
+			if (error) return error;
+		}
+		return null;
+	}
+	if (value.kind === "list") {
+		const struct = parseModifierStructure(expectedModifier);
+		if (struct.lists.length > 0) {
+			const innerModifier = buildModifier({
+				inner: struct.inner,
+				lists: struct.lists.slice(1)
+			});
+			for (const item of value.values) {
+				const error = collectVariablesFromValue(item, expectedTypeName, innerModifier, schema, usages);
+				if (error) return error;
+			}
+		}
+	}
+	return null;
+};
+const collectVariablesFromArguments = (args, parentTypeName, fieldName, schema, usages) => {
+	for (const arg of args) {
+		const argType = getArgumentType(schema, parentTypeName, fieldName, arg.name);
+		if (!argType) return {
+			code: "GRAPHQL_UNKNOWN_ARGUMENT",
+			message: `Unknown argument "${arg.name}" on field "${fieldName}"`,
+			fieldName,
+			argumentName: arg.name
+		};
+		const error = collectVariablesFromValue(arg.value, argType.typeName, argType.modifier, schema, usages);
+		if (error) return error;
+	}
+	return null;
+};
+const collectVariableUsages = (selections, parentTypeName, schema) => {
+	const usages = [];
+	const collect = (sels, parentType) => {
+		for (const sel of sels) switch (sel.kind) {
+			case "field":
+				if (sel.arguments && sel.arguments.length > 0) {
+					const error$1 = collectVariablesFromArguments(sel.arguments, parentType, sel.name, schema, usages);
+					if (error$1) return error$1;
+				}
+				if (sel.selections && sel.selections.length > 0) {
+					const fieldReturnType = getFieldReturnType(schema, parentType, sel.name);
+					if (!fieldReturnType) return {
+						code: "GRAPHQL_UNKNOWN_FIELD",
+						message: `Unknown field "${sel.name}" on type "${parentType}"`,
+						typeName: parentType,
+						fieldName: sel.name
+					};
+					const error$1 = collect(sel.selections, fieldReturnType);
+					if (error$1) return error$1;
+				}
+				break;
+			case "inlineFragment": {
+				const error$1 = collect(sel.selections, sel.onType);
+				if (error$1) return error$1;
+				break;
+			}
+			case "fragmentSpread": break;
+		}
+		return null;
+	};
+	const error = collect(selections, parentTypeName);
+	if (error) return err(error);
+	return ok(usages);
+};
+const getFieldReturnType = (schema, parentTypeName, fieldName) => {
+	const objectRecord = schema.objects.get(parentTypeName);
+	if (!objectRecord) return null;
+	const fieldDef = objectRecord.fields.get(fieldName);
+	if (!fieldDef) return null;
+	const { typeName } = parseTypeNode(fieldDef.type);
+	return typeName;
+};
+const mergeVariableUsages = (variableName, usages) => {
+	if (usages.length === 0) return err({
+		code: "GRAPHQL_UNDECLARED_VARIABLE",
+		message: `No usages found for variable "${variableName}"`,
+		variableName
+	});
+	const first = usages[0];
+	for (const usage of usages) if (usage.typeName !== first.typeName) return err({
+		code: "GRAPHQL_VARIABLE_TYPE_MISMATCH",
+		message: `Variable "$${variableName}" has conflicting types: "${first.typeName}" and "${usage.typeName}"`,
+		variableName
+	});
+	let candidateModifier = first.minimumModifier;
+	for (let i = 1; i < usages.length; i++) {
+		const result = mergeModifiers(candidateModifier, usages[i].minimumModifier);
+		if (!result.ok) return err({
+			code: "GRAPHQL_VARIABLE_MODIFIER_INCOMPATIBLE",
+			message: `Variable "$${variableName}" has incompatible modifiers: ${result.reason}`,
+			variableName
+		});
+		candidateModifier = result.value;
+	}
+	for (const usage of usages) if (!isModifierAssignable(candidateModifier, usage.expectedModifier)) return err({
+		code: "GRAPHQL_VARIABLE_MODIFIER_INCOMPATIBLE",
+		message: `Variable "$${variableName}" with modifier "${candidateModifier}" cannot satisfy expected "${usage.expectedModifier}"`,
+		variableName
+	});
+	return ok({
+		name: variableName,
+		typeName: first.typeName,
+		modifier: candidateModifier,
+		typeKind: first.typeKind
+	});
+};
+const inferVariablesFromUsages = (usages) => {
+	const byName = /* @__PURE__ */ new Map();
+	for (const usage of usages) {
+		const existing = byName.get(usage.name);
+		if (existing) existing.push(usage);
+		else byName.set(usage.name, [usage]);
+	}
+	const variables = [];
+	for (const [name, group] of byName) {
+		const result = mergeVariableUsages(name, group);
+		if (!result.ok) return err(result.error);
+		variables.push(result.value);
+	}
+	variables.sort((a, b) => a.name.localeCompare(b.name));
+	return ok(variables);
+};
+const isScalarName = (schema, name) => builtinScalarTypes$1.has(name) || schema.scalars.has(name);
+const sortFragmentsByDependency = (fragments) => {
+	const graph = /* @__PURE__ */ new Map();
+	for (const fragment of fragments) {
+		const deps = collectFragmentDependenciesSet(fragment.selections);
+		graph.set(fragment.name, deps);
+	}
+	const fragmentByName = /* @__PURE__ */ new Map();
+	for (const f of fragments) fragmentByName.set(f.name, f);
+	const sorted = [];
+	const visited = /* @__PURE__ */ new Set();
+	const visiting = /* @__PURE__ */ new Set();
+	const visit = (name, path) => {
+		if (visited.has(name)) return null;
+		if (visiting.has(name)) {
+			const cycleStart = path.indexOf(name);
+			const cycle = path.slice(cycleStart).concat(name);
+			return {
+				code: "GRAPHQL_FRAGMENT_CIRCULAR_DEPENDENCY",
+				message: `Circular dependency detected in fragments: ${cycle.join(" -> ")}`,
+				fragmentNames: cycle
+			};
+		}
+		const fragment = fragmentByName.get(name);
+		if (!fragment) {
+			visited.add(name);
+			return null;
+		}
+		visiting.add(name);
+		const deps = graph.get(name) ?? /* @__PURE__ */ new Set();
+		for (const dep of deps) {
+			const error = visit(dep, [...path, name]);
+			if (error) return error;
+		}
+		visiting.delete(name);
+		visited.add(name);
+		sorted.push(fragment);
+		return null;
+	};
+	for (const fragment of fragments) {
+		const error = visit(fragment.name, []);
+		if (error) return err(error);
+	}
+	return ok(sorted);
+};
+const collectFragmentDependenciesSet = (selections) => {
+	const deps = /* @__PURE__ */ new Set();
+	const collect = (sels) => {
+		for (const sel of sels) switch (sel.kind) {
+			case "fragmentSpread":
+				deps.add(sel.name);
+				break;
+			case "field":
+				if (sel.selections) collect(sel.selections);
+				break;
+			case "inlineFragment":
+				collect(sel.selections);
+				break;
+		}
+	};
+	collect(selections);
+	return deps;
+};
+const isEnumName = (schema, name) => schema.enums.has(name);
+const transformParsedGraphql = (parsed, options) => {
+	const schema = createSchemaIndex(options.schemaDocument);
+	const sortResult = sortFragmentsByDependency(parsed.fragments);
+	if (!sortResult.ok) return err(sortResult.error);
+	const sortedFragments = sortResult.value;
+	const resolvedFragmentVariables = /* @__PURE__ */ new Map();
+	const fragments = [];
+	for (const frag of sortedFragments) {
+		const result = transformFragment(frag, schema, resolvedFragmentVariables);
+		if (!result.ok) return err(result.error);
+		resolvedFragmentVariables.set(frag.name, result.value.variables);
+		fragments.push(result.value);
+	}
+	const operations = [];
+	for (const op of parsed.operations) {
+		const result = transformOperation(op, schema);
+		if (!result.ok) return err(result.error);
+		operations.push(result.value);
+	}
+	return ok({
+		operations,
+		fragments
+	});
+};
+const transformOperation = (op, schema) => {
+	const variables = [];
+	for (const v of op.variables) {
+		const typeKind = resolveTypeKind$1(schema, v.typeName);
+		if (typeKind === null) return err({
+			code: "GRAPHQL_UNKNOWN_TYPE",
+			message: `Unknown type "${v.typeName}" in variable "${v.name}"`,
+			typeName: v.typeName
+		});
+		variables.push({
+			...v,
+			typeKind
+		});
+	}
+	const fragmentDependencies = collectFragmentDependencies(op.selections);
+	return ok({
+		...op,
+		variables,
+		fragmentDependencies
+	});
+};
+const transformFragment = (frag, schema, resolvedFragmentVariables) => {
+	const fragmentDependencies = collectFragmentDependencies(frag.selections);
+	const directUsagesResult = collectVariableUsages(frag.selections, frag.onType, schema);
+	if (!directUsagesResult.ok) return err(directUsagesResult.error);
+	const directUsages = directUsagesResult.value;
+	const spreadVariables = [];
+	for (const depName of fragmentDependencies) {
+		const depVariables = resolvedFragmentVariables.get(depName);
+		if (depVariables) spreadVariables.push(...depVariables);
+	}
+	const variablesResult = inferVariablesFromUsages([...directUsages, ...spreadVariables.map((v) => ({
+		name: v.name,
+		typeName: v.typeName,
+		expectedModifier: v.modifier,
+		minimumModifier: v.modifier,
+		typeKind: v.typeKind
+	}))]);
+	if (!variablesResult.ok) return err(variablesResult.error);
+	return ok({
+		...frag,
+		fragmentDependencies,
+		variables: variablesResult.value
+	});
+};
+const resolveTypeKind$1 = (schema, typeName) => {
+	if (isScalarName(schema, typeName)) return "scalar";
+	if (isEnumName(schema, typeName)) return "enum";
+	if (schema.inputs.has(typeName)) return "input";
+	return null;
+};
+const collectFragmentDependencies = (selections) => {
+	const fragments = /* @__PURE__ */ new Set();
+	const collect = (sels) => {
+		for (const sel of sels) switch (sel.kind) {
+			case "fragmentSpread":
+				fragments.add(sel.name);
+				break;
+			case "field":
+				if (sel.selections) collect(sel.selections);
+				break;
+			case "inlineFragment":
+				collect(sel.selections);
+				break;
+		}
+	};
+	collect(selections);
+	return [...fragments];
+};
+
+//#endregion
+//#region packages/core/src/graphql/var-specifier-builder.ts
+/**
+* Converts VariableDefinitionNode from graphql-js AST into VarSpecifier objects
+* compatible with the composer's GenericVarSpecifier type.
+*
+* Uses throw (not Result) because it will be called from the composer layer.
+* @module
+*/
+const builtinScalarTypes = new Set([
+	"ID",
+	"String",
+	"Int",
+	"Float",
+	"Boolean"
+]);
+const resolveTypeKind = (schema, typeName) => {
+	if (builtinScalarTypes.has(typeName) || schema.scalars.has(typeName)) return "scalar";
+	if (schema.enums.has(typeName)) return "enum";
+	if (schema.inputs.has(typeName)) return "input";
+	throw new Error(`Cannot resolve type kind for "${typeName}": not found in schema as scalar, enum, or input`);
+};
+/**
+* Extract a constant value from a ValueNode (for default values).
+* Similar to graphql-js valueFromAST but without type coercion.
+*/
+const extractConstValue = (node) => {
+	switch (node.kind) {
+		case Kind.INT: return Number.parseInt(node.value, 10);
+		case Kind.FLOAT: return Number.parseFloat(node.value);
+		case Kind.STRING: return node.value;
+		case Kind.BOOLEAN: return node.value;
+		case Kind.NULL: return null;
+		case Kind.ENUM: return node.value;
+		case Kind.LIST: return node.values.map(extractConstValue);
+		case Kind.OBJECT: {
+			const obj = {};
+			for (const field of node.fields) obj[field.name.value] = extractConstValue(field.value);
+			return obj;
+		}
+		case Kind.VARIABLE: throw new Error("Variable references are not allowed in default values");
+		default: throw new Error(`Unexpected value kind: ${node.kind}`);
+	}
+};
+const extractDefaultValue = (node) => {
+	if (!node.defaultValue) return null;
+	return { default: extractConstValue(node.defaultValue) };
+};
+/**
+* Convert a VariableDefinitionNode to a VarSpecifier.
+* Resolves `kind` (scalar/enum/input) from the schema index.
+*
+* @throws Error if type name cannot be resolved in schema
+*/
+const buildVarSpecifier = (node, schema) => {
+	const { typeName, modifier } = parseTypeNode(node.type);
+	return {
+		kind: resolveTypeKind(schema, typeName),
+		name: typeName,
+		modifier,
+		defaultValue: extractDefaultValue(node),
+		directives: {}
+	};
+};
+/**
+* Convert all variable definitions from a list of VariableDefinitionNodes
+* into a record keyed by variable name.
+*
+* @throws Error if any type name cannot be resolved in schema
+*/
+const buildVarSpecifiers = (nodes, schema) => {
+	const result = {};
+	for (const node of nodes) result[node.variable.name.value] = buildVarSpecifier(node, schema);
+	return result;
+};
+
 //#endregion
 //#region packages/core/src/types/metadata/adapter.ts
 /**
@@ -1369,6 +2406,11 @@ const createVarRefs = (definitions) => mapValues(definitions, (_, name) => creat
 //#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:
@@ -1381,25 +2423,39 @@ const createVarRefs = (definitions) => mapValues(definitions, (_, name) => creat
 * @param params - Operation building parameters
 * @returns Operation artifact or Promise of artifact (if async metadata)
 *
-* @internal Used by operation.ts and extend.ts
+* @internal Used by operation.ts, extend.ts, and operation-tagged-template.ts
 */
 const buildOperationArtifact = (params) => {
-	const { schema, operationType, operationTypeName, operationName, variables, fieldsFactory, adapter, metadata: metadataBuilder, transformDocument: operationTransformDocument, adapterTransformDocument } = params;
+	const { schema, operationType, operationTypeName, operationName, variables, adapter, metadata: metadataBuilder, transformDocument: operationTransformDocument, adapterTransformDocument } = params;
 	const $ = createVarRefs(variables);
-	const f = createFieldFactories(schema, operationTypeName);
-	const { result: fields, usages: fragmentUsages } = withFragmentUsageCollection(() => fieldsFactory({
-		f,
-		$
-	}));
-	const document = buildDocument({
-		operationName,
-		operationType,
-		operationTypeName,
-		variables,
-		fields,
-		schema
-	});
-	const variableNames = Object.keys(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,
@@ -1463,6 +2519,34 @@ const buildOperationArtifact = (params) => {
 	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
@@ -1486,9 +2570,12 @@ const buildOperationArtifact = (params) => {
 const createExtendComposer = (schema, adapter, transformDocument) => {
 	const resolvedAdapter = adapter ?? defaultMetadataAdapter;
 	return (compat, options) => {
-		const { operationType, operationName, variables, fieldsBuilder } = compat.value;
+		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,
@@ -1502,52 +2589,298 @@ const createExtendComposer = (schema, adapter, 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 = parse(graphqlSource);
+	const opDef = document.definitions.find((d) => d.kind === 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/fragment.ts
+//#region packages/core/src/composer/merge-variable-definitions.ts
 /**
-* Fragment composer factory for creating reusable field selections.
+* Shared utility for merging variable definitions from interpolated fragments.
+* Used by both fragment and operation tagged template implementations.
 * @module
 */
 /**
-* Creates fragment builder functions for all object types in the schema.
-*
-* Returns an object with a builder for each type (e.g., `fragment.User`, `fragment.Post`).
-* Each builder creates a `Fragment` that can be spread into operations.
-*
-* @param schema - The GraphQL schema definition
-* @param _adapter - Optional metadata adapter (for fragment metadata)
-* @returns Object mapping type names to fragment builder functions
-*
-* @internal Used by `createGqlElementComposer`
+* Merge variable definitions from interpolated fragments into the parent's variable definitions.
+* Deduplicates variables with matching names and types, throws on conflicting types.
 */
-const createGqlFragmentComposers = (schema, _adapter) => {
-	const createFragmentComposer = (typename) => {
-		return (options) => {
-			const varDefinitions = options.variables ?? {};
-			const { key, metadata, fields } = options;
-			return Fragment.create(() => ({
-				typename,
-				key,
-				schemaLabel: schema.label,
-				variableDefinitions: varDefinitions,
-				spread: (variables) => {
-					const f = createFieldFactories(schema, typename);
-					const $ = createVarAssignments(varDefinitions, variables);
-					recordFragmentUsage({
-						metadataBuilder: metadata ? () => metadata({ $ }) : null,
-						path: getCurrentFieldPath()
-					});
-					return fields({
-						f,
-						$
+function mergeVariableDefinitions(parentVars, interpolationMap) {
+	const merged = { ...parentVars };
+	for (const value of interpolationMap.values()) if (value instanceof Fragment) {
+		const childVars = value.variableDefinitions;
+		for (const [varName, varDef] of Object.entries(childVars)) if (varName in merged) {
+			const existing = merged[varName];
+			if (existing?.kind !== varDef.kind || existing?.name !== varDef.name || existing?.modifier !== varDef.modifier) throw new Error(`Variable definition conflict: $${varName} is defined with incompatible types (${existing?.kind}:${existing?.name}:${existing?.modifier} vs ${varDef.kind}:${varDef.name}:${varDef.modifier})`);
+		} else merged[varName] = varDef;
+	}
+	return merged;
+}
+
+//#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;
+	try {
+		syntheticDoc = parse(syntheticQuery);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to parse fragment argument definitions: ${message}`);
+	}
+	const opDef = syntheticDoc.definitions[0];
+	if (!opDef || opDef.kind !== Kind.OPERATION_DEFINITION) return {};
+	return buildVarSpecifiers(opDef.variableDefinitions ?? [], schemaIndex);
+}
+/**
+* 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.
+*/
+function buildFieldsFromSelectionSet(selectionSet, schema, typeName, varAssignments, interpolationMap) {
+	const f = createFieldFactories(schema, typeName);
+	const result = {};
+	for (const selection of selectionSet.selections) if (selection.kind === Kind.FIELD) {
+		const fieldName = selection.name.value;
+		const alias = selection.alias?.value ?? fieldName;
+		if (fieldName === "__typename") {
+			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;
+		if (selection.selectionSet) {
+			const curried = factory(args, extras);
+			if (typeof curried === "function") {
+				const fieldSpec = schema.object[typeName]?.fields[fieldName];
+				const parsedType = parseOutputField(fieldSpec);
+				if (parsedType.kind === "union") {
+					const unionInput = {};
+					let hasTypename = false;
+					const unsupportedSelections = [];
+					for (const sel of selection.selectionSet.selections) if (sel.kind === 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`);
+						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;
+					} else if (sel.kind === 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.`);
+						hasTypename = true;
+					} else {
+						const desc = sel.kind === Kind.FIELD ? `Field "${sel.name.value}"` : "Fragment spread";
+						unsupportedSelections.push(desc);
+					}
+					const hasInlineFragments = Object.keys(unionInput).length > 0;
+					if (unsupportedSelections.length > 0) {
+						if (hasInlineFragments) throw new Error(`${unsupportedSelections[0]} alongside inline fragments in union selection is not supported in tagged templates. Use per-member inline fragments instead.`);
+						throw new Error(`Union field "${fieldName}" requires at least __typename or inline fragment syntax (... on Type { fields }) in tagged templates`);
+					}
+					if (!hasInlineFragments && !hasTypename) throw new Error(`Union field "${fieldName}" requires at least __typename or inline fragment syntax (... on Type { fields }) in tagged templates`);
+					if (hasTypename) unionInput.__typename = true;
+					const fieldResult = curried(unionInput);
+					Object.assign(result, fieldResult);
+				} else {
+					const nestedFields = buildFieldsFromSelectionSet(selection.selectionSet, schema, resolveFieldTypeName(schema, typeName, fieldName), varAssignments, interpolationMap);
+					const fieldResult = curried(({ f: nestedFactories }) => {
+						return nestedFields;
 					});
+					Object.assign(result, fieldResult);
 				}
-			}));
+			} else Object.assign(result, curried);
+		} else {
+			const fieldResult = factory(args, extras);
+			if (typeof fieldResult === "function") {
+				const emptyResult = fieldResult(() => ({}));
+				Object.assign(result, emptyResult);
+			} else Object.assign(result, fieldResult);
+		}
+	} else if (selection.kind === Kind.FRAGMENT_SPREAD) {
+		const fragmentName = selection.name.value;
+		if (interpolationMap?.has(fragmentName)) {
+			const interpolatedValue = interpolationMap.get(fragmentName);
+			if (!interpolatedValue) throw new Error(`Interpolation placeholder "${fragmentName}" has no value`);
+			let spreadFields;
+			if (interpolatedValue instanceof Fragment) spreadFields = interpolatedValue.spread(varAssignments);
+			else {
+				if (!varAssignments) throw new Error(`Callback interpolation requires variable context`);
+				spreadFields = interpolatedValue({ $: varAssignments });
+			}
+			Object.assign(result, spreadFields);
+		} else throw new Error(`Fragment spread "...${fragmentName}" in tagged template must use interpolation syntax. Use \`...@\${fragment}\` instead of \`...FragmentName\`.`);
+	} else if (selection.kind === Kind.INLINE_FRAGMENT) throw new Error("Inline fragments (... on Type) at the top level are not supported in tagged templates. Use inline fragments only inside union field selections.");
+	return result;
+}
+/**
+* Build a simple args object from GraphQL AST argument nodes.
+* Extracts literal values from the AST for passing to field factories.
+*/
+function buildArgsFromASTArguments(args, varAssignments) {
+	if (args.length === 0) return {};
+	const result = {};
+	for (const arg of args) result[arg.name.value] = extractASTValue(arg.value, varAssignments);
+	return result;
+}
+/**
+* Extract a runtime value from a GraphQL AST ValueNode.
+*/
+function extractASTValue(node, varAssignments) {
+	switch (node.kind) {
+		case Kind.INT: return Number.parseInt(node.value, 10);
+		case Kind.FLOAT: return Number.parseFloat(node.value);
+		case Kind.STRING:
+		case Kind.BOOLEAN:
+		case Kind.ENUM: return node.value;
+		case Kind.NULL: return null;
+		case Kind.LIST: return node.values?.map((v) => extractASTValue(v, varAssignments)) ?? [];
+		case Kind.OBJECT: return Object.fromEntries((node.fields ?? []).map((f) => [f.name.value, extractASTValue(f.value, varAssignments)]));
+		case Kind.VARIABLE: {
+			const varName = node.name.value;
+			if (varAssignments && varName in varAssignments) return varAssignments[varName];
+			return createVarRefFromVariable(varName);
+		}
+		default: return;
+	}
+}
+/**
+* Resolve the output type name for a field on a given type.
+* Looks up the field's type specifier in the schema and extracts the type name.
+* Handles both string specifiers ("o|Avatar|?") and object specifiers ({ spec: "o|Avatar|?" }).
+*/
+function resolveFieldTypeName(schema, typeName, fieldName) {
+	const typeDef = schema.object[typeName];
+	if (!typeDef) throw new Error(`Type "${typeName}" is not defined in schema objects`);
+	const fieldDef = typeDef.fields[fieldName];
+	if (!fieldDef) throw new Error(`Field "${fieldName}" is not defined on type "${typeName}"`);
+	return (typeof fieldDef === "string" ? fieldDef : fieldDef.spec).split("|")[1] ?? typeName;
+}
+/**
+* Construct a synthetic GraphQL fragment source from JS arguments and template body.
+* Handles optional variable declarations: `($var: Type!) { fields }` or `{ fields }`.
+*/
+function buildSyntheticFragmentSource(name, typeName, body) {
+	const trimmed = body.trim();
+	if (trimmed.startsWith("(")) {
+		const closeIndex = findMatchingParen(trimmed, 0);
+		if (closeIndex === -1) throw new Error("Unmatched parenthesis in fragment variable declarations");
+		return `fragment ${name}${trimmed.slice(0, closeIndex + 1)} on ${typeName} ${trimmed.slice(closeIndex + 1).trim()}`;
+	}
+	return `fragment ${name} on ${typeName} ${trimmed}`;
+}
+/**
+* Creates a curried tagged template function for fragments.
+* New API: `fragment("name", "type")\`{ fields }\`` returns TemplateResult<AnyFragment>.
+*
+* @param schema - The GraphQL schema definition
+*/
+function createFragmentTaggedTemplate(schema) {
+	const schemaIndex = createSchemaIndexFromSchema(schema);
+	return (fragmentName, onType) => {
+		if (!(onType in schema.object)) throw new Error(`Type "${onType}" is not defined in schema objects`);
+		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 rawSource = buildSyntheticFragmentSource(fragmentName, onType, body);
+			let varSpecifiers = extractFragmentVariables(rawSource, schemaIndex);
+			varSpecifiers = mergeVariableDefinitions(varSpecifiers, interpolationMap);
+			const { preprocessed } = preprocessFragmentArgs(rawSource);
+			let document;
+			try {
+				document = parse(preprocessed);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				throw new Error(`GraphQL parse error in tagged template: ${message}`);
+			}
+			const fragmentDefs = document.definitions.filter((def) => def.kind === Kind.FRAGMENT_DEFINITION);
+			if (fragmentDefs.length !== 1) throw new Error(`Internal error: expected exactly one fragment definition in synthesized source`);
+			const fragNode = fragmentDefs[0];
+			if (fragNode.kind !== Kind.FRAGMENT_DEFINITION) throw new Error("Unexpected definition kind");
+			return (options) => {
+				return Fragment.create(() => ({
+					typename: onType,
+					key: fragmentName,
+					schemaLabel: schema.label,
+					variableDefinitions: varSpecifiers,
+					spread: (variables) => {
+						const $ = createVarAssignments(varSpecifiers, variables);
+						let metadataBuilder = null;
+						if (options?.metadata !== void 0) {
+							const metadata = options.metadata;
+							if (typeof metadata === "function") metadataBuilder = () => metadata({ $ });
+							else metadataBuilder = () => metadata;
+						}
+						recordFragmentUsage({
+							metadataBuilder,
+							path: null
+						});
+						return buildFieldsFromSelectionSet(fragNode.selectionSet, schema, onType, $, interpolationMap);
+					}
+				}));
+			};
 		};
 	};
-	return mapValues(schema.object, (_, typename) => createFragmentComposer(typename));
-};
+}
 
 //#endregion
 //#region packages/core/src/composer/operation.ts
@@ -1578,6 +2911,7 @@ const createOperationComposerFactory = (schema, adapter, transformDocument) => {
 		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,
@@ -1593,6 +2927,106 @@ const createOperationComposerFactory = (schema, adapter, transformDocument) => {
 	};
 };
 
+//#endregion
+//#region packages/core/src/composer/operation-tagged-template.ts
+/**
+* Operation tagged template function for creating GraphQL operations from template literals.
+* @module
+*/
+/**
+* Construct a synthetic GraphQL operation source from JS arguments and template body.
+* Handles optional variable declarations: `($var: Type!) { fields }` or `{ fields }`.
+*/
+function buildSyntheticOperationSource(operationType, operationName, body) {
+	return `${operationType} ${operationName} ${body.trim()}`;
+}
+/**
+* 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)
+*/
+const resolveMetadataOption = (metadataOption) => {
+	if (metadataOption === void 0) return void 0;
+	if (typeof metadataOption === "function") return metadataOption;
+	return () => metadataOption;
+};
+/**
+* Creates a curried tagged template function for a specific operation type.
+* New API: `query("name")\`($var: Type!) { fields }\`` returns TemplateResult<Operation>.
+*
+* @param schema - The GraphQL schema definition
+* @param operationType - The operation type (query, mutation, subscription)
+* @param metadataAdapter - Optional metadata adapter for metadata aggregation
+* @param adapterTransformDocument - Optional document transformer from adapter
+*/
+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 = 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 === 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 !== Kind.OPERATION_DEFINITION) throw new Error("Unexpected definition kind");
+			let varSpecifiers = buildVarSpecifiers(opNode.variableDefinitions ?? [], schemaIndex);
+			varSpecifiers = mergeVariableDefinitions(varSpecifiers, interpolationMap);
+			const operationTypeName = schema.operations[operationType];
+			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);
+			};
+		};
+	};
+};
+
 //#endregion
 //#region packages/core/src/composer/var-ref-tools.ts
 /**
@@ -1811,7 +3245,7 @@ const createVarBuilder = (inputTypeMethods) => {
 *
 * This is the main entry point for defining GraphQL operations and fragments.
 * The returned function provides a context with:
-* - `fragment`: Builders for each object type
+* - `fragment`: Tagged template function for fragment definitions
 * - `query/mutation/subscription`: Operation builders
 * - `$var`: Variable definition helpers
 * - `$dir`: Field directive helpers (@skip, @include)
@@ -1844,22 +3278,22 @@ const createGqlElementComposer = (schema, options) => {
 	const helpers = adapter?.helpers;
 	const metadataAdapter = adapter?.metadata;
 	const transformDocument = adapter?.transformDocument;
-	const fragment = createGqlFragmentComposers(schema, metadataAdapter);
+	const fragment = createFragmentTaggedTemplate(schema);
 	const createOperationComposer = createOperationComposerFactory(schema, metadataAdapter, transformDocument);
 	const transformedContext = applyContextTransformer({
 		fragment,
-		query: {
+		query: Object.assign(createOperationTaggedTemplate(schema, "query", metadataAdapter, transformDocument), {
 			operation: createOperationComposer("query"),
-			compat: createCompatComposer(schema, "query")
-		},
-		mutation: {
+			compat: createCompatTaggedTemplate(schema, "query")
+		}),
+		mutation: Object.assign(createOperationTaggedTemplate(schema, "mutation", metadataAdapter, transformDocument), {
 			operation: createOperationComposer("mutation"),
-			compat: createCompatComposer(schema, "mutation")
-		},
-		subscription: {
+			compat: createCompatTaggedTemplate(schema, "mutation")
+		}),
+		subscription: Object.assign(createOperationTaggedTemplate(schema, "subscription", metadataAdapter, transformDocument), {
 			operation: createOperationComposer("subscription"),
-			compat: createCompatComposer(schema, "subscription")
-		},
+			compat: createCompatTaggedTemplate(schema, "subscription")
+		}),
 		define: (factory) => GqlDefine.create(factory),
 		extend: createExtendComposer(schema, metadataAdapter, transformDocument),
 		$var: createVarBuilder(inputTypeMethods),
@@ -2202,5 +3636,5 @@ const generateInputTypeFromVarDefs = (schema, varDefs, options = {}) => {
 };
 
 //#endregion
-export { Fragment, GqlDefine, GqlElement, Operation, VarRef, appendToPath, applyTypeModifier, buildArgumentValue, buildConstValueNode, buildDocument, buildOperationArtifact, buildOperationTypeNode, buildWithTypeModifier, calculateFieldType, calculateFieldsType, createColocateHelper, createCompatComposer, createDefaultAdapter, createDirectiveBuilder, createDirectiveMethod, createExtendComposer, createFieldFactories, createGqlElementComposer, createGqlFragmentComposers, createOperationComposerFactory, createStandardDirectives, createTypedDirectiveMethod, createVarAssignments, createVarBuilder, createVarMethod, createVarMethodFactory, createVarRefFromVariable, createVarRefs, defaultMetadataAdapter, defineEnum, defineOperationRoots, defineScalar, generateInputObjectType, generateInputType, generateInputTypeFromSpecifiers, generateInputTypeFromVarDefs, getCurrentFieldPath, getEnumType, getScalarInputType, getScalarOutputType, graphqlTypeToTypeScript, isDirectiveRef, isListType, parseInputSpecifier, parseOutputSpecifier, recordFragmentUsage, withFieldPath, withFragmentUsageCollection };
+export { Fragment, GqlDefine, GqlElement, Operation, VarRef, appendToPath, applyTypeModifier, buildArgumentValue, buildConstValueNode, buildDocument, buildFieldsFromSelectionSet, buildOperationArtifact, buildOperationTypeNode, buildVarSpecifier, buildVarSpecifiers, buildWithTypeModifier, calculateFieldType, calculateFieldsType, collectVariableUsages, createColocateHelper, createCompatComposer, createCompatTaggedTemplate, createDefaultAdapter, createDirectiveBuilder, createDirectiveMethod, createExtendComposer, createFieldFactories, createFragmentTaggedTemplate, createGqlElementComposer, createOperationComposerFactory, createOperationTaggedTemplate, createSchemaIndex, createSchemaIndexFromSchema, createStandardDirectives, createTypedDirectiveMethod, createVarAssignments, createVarBuilder, createVarMethod, createVarMethodFactory, createVarRefFromVariable, createVarRefs, defaultMetadataAdapter, defineEnum, defineOperationRoots, defineScalar, err, extractFragmentVariables, generateInputObjectType, generateInputType, generateInputTypeFromSpecifiers, generateInputTypeFromVarDefs, getArgumentType, getCurrentFieldPath, getEnumType, getFieldReturnType, getInputFieldType, getScalarInputType, getScalarOutputType, graphqlTypeToTypeScript, inferVariablesFromUsages, isDirectiveRef, isListType, isModifierAssignable, isTemplateCompatSpec, mergeModifiers, mergeVariableUsages, ok, parseGraphqlSource, parseInputSpecifier, parseOutputSpecifier, parseTypeNode, preprocessFragmentArgs, recordFragmentUsage, sortFragmentsByDependency, transformParsedGraphql, withFieldPath, withFragmentUsageCollection, wrapArtifactAsOperation };
 //# sourceMappingURL=index.js.map