@atscript/typescript 0.1.1 → 0.1.2

package/dist/cli.cjs

@@ -325,7 +325,7 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			this.writeln("static __is_atscript_annotated_type: true");
 			this.writeln(`static type: TAtscriptTypeObject<keyof ${asClass}>`);
 			this.writeln(`static metadata: TMetadataMap<AtscriptMetadata>`);
-			this.writeln(`static validator: <TT extends TAtscriptAnnotatedTypeConstructor = ${asClass}>(opts?: Partial<TValidatorOptions>) => Validator<TT>`);
+			this.writeln(`static validator: <TT extends TAtscriptAnnotatedTypeConstructor = typeof ${asClass}>(opts?: Partial<TValidatorOptions>) => Validator<TT>`);
 			this.writeln("static toJsonSchema: () => any");
 		}
 		this.pop();
@@ -354,33 +354,33 @@ else this.writeln("{}");
 	renderAnnotate(node) {
 		if (node.isMutating) return;
 		const targetName = node.targetName;
-		const unwound = this.doc.unwindType(targetName);
-		if (!unwound?.def) return;
-		const def = this.doc.mergeIntersection(unwound.def);
 		this.writeln();
 		const exported = node.token("export")?.text === "export";
 		this.renderJsDoc(node);
-		if ((0, __atscript_core.isStructure)(def) || (0, __atscript_core.isInterface)(def)) {
-			this.write(exported ? "export declare " : "declare ");
-			this.write(`class ${node.id} `);
-			this.renderStructure(def, node.id);
-		} else {
+		if (this.isTypeTarget(targetName)) {
 			this.write(exported ? "export " : "declare ");
-			this.write(`type ${node.id} = `);
-			this.renderTypeDef(def);
+			this.write(`type ${node.id} = ${targetName}`);
+			this.writeln();
+			const unwound = this.doc.unwindType(targetName);
+			this.renderTypeNamespaceFor(node.id, unwound?.def);
+		} else {
+			this.write(exported ? "export declare " : "declare ");
+			this.writeln(`class ${node.id} extends ${targetName} {}`);
+			this.writeln();
 		}
-		this.writeln();
 	}
 	renderTypeNamespace(node) {
-		this.write(`declare namespace ${node.id} `);
+		this.renderTypeNamespaceFor(node.id, node.getDefinition());
+	}
+	renderTypeNamespaceFor(name, inputDef) {
+		this.write(`declare namespace ${name} `);
 		this.blockln("{}");
-		const def = node.getDefinition();
 		let typeDef = "TAtscriptTypeDef";
-		if (def) {
-			let realDef = def;
-			if ((0, __atscript_core.isRef)(def)) realDef = this.doc.unwindType(def.id, def.chain)?.def || realDef;
+		if (inputDef) {
+			let realDef = inputDef;
+			if ((0, __atscript_core.isRef)(inputDef)) realDef = this.doc.unwindType(inputDef.id, inputDef.chain)?.def || realDef;
 			realDef = this.doc.mergeIntersection(realDef);
-			if ((0, __atscript_core.isStructure)(realDef) || (0, __atscript_core.isInterface)(realDef)) typeDef = `TAtscriptTypeObject<keyof ${node.id}>`;
+			if ((0, __atscript_core.isStructure)(realDef) || (0, __atscript_core.isInterface)(realDef)) typeDef = `TAtscriptTypeObject<keyof ${name}>`;
 else if ((0, __atscript_core.isGroup)(realDef)) typeDef = "TAtscriptTypeComplex";
 else if ((0, __atscript_core.isArray)(realDef)) typeDef = "TAtscriptTypeArray";
 else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = "TAtscriptTypeFinal";
@@ -388,10 +388,19 @@ else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = "TAtscriptTypeFina
 		this.writeln(`const __is_atscript_annotated_type: true`);
 		this.writeln(`const type: ${typeDef}`);
 		this.writeln(`const metadata: TMetadataMap<AtscriptMetadata>`);
-		this.writeln(`const validator: <TT extends TAtscriptAnnotatedTypeConstructor = ${node.id}>(opts?: Partial<TValidatorOptions>) => Validator<TT>`);
+		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<TAtscriptAnnotatedTypeConstructor, ${name}>`);
 		this.writeln("const toJsonSchema: () => any");
 		this.popln();
 	}
+	isTypeTarget(name, doc) {
+		const d = doc || this.doc;
+		const decl = d.getDeclarationOwnerNode(name);
+		if (!decl?.node) return false;
+		if (decl.node.entity === "type") return true;
+		if (decl.node.entity === "interface") return false;
+		if (decl.node.entity === "annotate") return this.isTypeTarget(decl.node.targetName, decl.doc);
+		return false;
+	}
 	renderJsDoc(node) {
 		const range = node.token("identifier")?.range;
 		const rangeStr = range ? `:${range.start.line + 1}:${range.start.character + 1}` : "";
@@ -760,6 +769,15 @@ var ValidatorError = class extends Error {
 function isAnnotatedType(type) {
 	return type && type.__is_atscript_annotated_type;
 }
+function annotate(metadata, key, value, asArray) {
+	if (!metadata) return;
+	if (asArray) if (metadata.has(key)) {
+		const a = metadata.get(key);
+		if (Array.isArray(a)) a.push(value);
+else metadata.set(key, [a, value]);
+	} else metadata.set(key, [value]);
+else metadata.set(key, value);
+}
 function defineAnnotatedType(_kind, base) {
 	const kind = _kind || "";
 	const type = base?.type || {};
@@ -859,12 +877,7 @@ else if (!newBase) throw new Error(`"${typeName}" is not annotated type`);
 			return this;
 		},
 		annotate(key, value, asArray) {
-			if (asArray) if (this.$metadata.has(key)) {
-				const a = this.$metadata.get(key);
-				if (Array.isArray(a)) a.push(value);
-else this.$metadata.set(key, [a, value]);
-			} else this.$metadata.set(key, [value]);
-else this.$metadata.set(key, value);
+			annotate(this.$metadata, key, value, asArray);
 			return this;
 		}
 	};
@@ -968,7 +981,7 @@ var JsRenderer = class extends BaseRenderer {
 	pre() {
 		this.writeln("// prettier-ignore-start");
 		this.writeln("/* eslint-disable */");
-		const imports = ["defineAnnotatedType as $"];
+		const imports = ["defineAnnotatedType as $", "annotate as $a"];
 		if (!this.opts?.preRenderJsonSchema) imports.push("buildJsonSchema as $$");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 	}
@@ -987,27 +1000,26 @@ var JsRenderer = class extends BaseRenderer {
 	post() {
 		for (const node of this.postAnnotate) if (node.entity === "annotate") {
 			const annotateNode = node;
-			const unwound = this.doc.unwindType(annotateNode.targetName);
-			if (unwound?.def) {
-				let def = this.doc.mergeIntersection(unwound.def);
-				if ((0, __atscript_core.isInterface)(def)) def = def.getDefinition() || def;
-				this._adHocAnnotations = this.buildAdHocMap([annotateNode]);
-				this.annotateType(def, node.id);
-				this._adHocAnnotations = null;
-				this.indent();
-				this.defineMetadataForAnnotateAlias(annotateNode);
-				this.unindent();
-				this.writeln();
+			if (annotateNode.isMutating) this.renderMutatingAnnotateNode(annotateNode);
+else {
+				const unwound = this.doc.unwindType(annotateNode.targetName);
+				if (unwound?.def) {
+					let def = this.doc.mergeIntersection(unwound.def);
+					if ((0, __atscript_core.isInterface)(def)) def = def.getDefinition() || def;
+					this._adHocAnnotations = this.buildAdHocMap([annotateNode]);
+					this.annotateType(def, node.id);
+					this._adHocAnnotations = null;
+					this.indent();
+					this.defineMetadataForAnnotateAlias(annotateNode);
+					this.unindent();
+					this.writeln();
+				}
 			}
 		} else {
-			const mutatingNodes = this.doc.getAnnotateNodesFor(node.id).filter((n) => n.isMutating);
-			this._adHocAnnotations = this.buildAdHocMap(mutatingNodes);
 			this.annotateType(node.getDefinition(), node.id);
-			this._adHocAnnotations = null;
 			this.indent().defineMetadata(node).unindent();
 			this.writeln();
 		}
-		this.renderMutatingAnnotates();
 		this.writeln("// prettier-ignore-end");
 		super.post();
 	}
@@ -1041,7 +1053,7 @@ var JsRenderer = class extends BaseRenderer {
 	}
 	renderAnnotate(node) {
 		if (node.isMutating) {
-			this.mutatingAnnotates.push(node);
+			this.postAnnotate.push(node);
 			return;
 		}
 		const targetName = node.targetName;
@@ -1329,18 +1341,13 @@ else handle.prop(prop.id, propHandle.$type);
 		return this;
 	}
 	defineMetadata(node) {
-		const annotations = this.doc.evalAnnotationsForNode(node);
-		let adHocNames;
-		let adHoc;
+		let annotations = this.doc.evalAnnotationsForNode(node);
 		if (this._adHocAnnotations && this._propPath.length > 0) {
 			const path$3 = this._propPath.join(".");
-			adHoc = this._adHocAnnotations.get(path$3);
-			if (adHoc) adHocNames = new Set(adHoc.map((a) => a.name));
+			const adHoc = this._adHocAnnotations.get(path$3);
+			if (adHoc) annotations = this.doc.mergeNodesAnnotations(annotations, adHoc);
 		}
 		annotations?.forEach((an) => {
-			if (!adHocNames || !adHocNames.has(an.name)) this.resolveAnnotationValue(node, an);
-		});
-		adHoc?.forEach((an) => {
 			this.resolveAnnotationValue(node, an);
 		});
 		return this;
@@ -1352,11 +1359,8 @@ else handle.prop(prop.id, propHandle.$type);
 		const annotateAnnotations = this.doc.evalAnnotationsForNode(annotateNode);
 		const targetDecl = this.doc.getDeclarationOwnerNode(annotateNode.targetName);
 		const targetAnnotations = targetDecl?.node ? targetDecl.doc.evalAnnotationsForNode(targetDecl.node) : undefined;
-		const overriddenNames = new Set(annotateAnnotations?.map((a) => a.name));
-		targetAnnotations?.forEach((an) => {
-			if (!overriddenNames.has(an.name)) this.resolveAnnotationValue(annotateNode, an);
-		});
-		annotateAnnotations?.forEach((an) => {
+		const merged = this.doc.mergeNodesAnnotations(targetAnnotations, annotateAnnotations);
+		merged.forEach((an) => {
 			this.resolveAnnotationValue(annotateNode, an);
 		});
 		return this;
@@ -1395,47 +1399,123 @@ else targetValue = "true";
 			multiple: !!multiple
 		};
 	}
-	renderMutatingAnnotates() {
-		for (const node of this.mutatingAnnotates) {
-			const targetName = node.targetName;
-			for (const entry of node.entries) {
-				const anns = entry.annotations;
-				if (!anns || anns.length === 0) continue;
-				const parts = entry.hasChain ? [entry.id, ...entry.chain.map((c) => c.text)] : [entry.id];
-				let accessor = targetName;
-				for (const part of parts) accessor += `.type.props.get("${escapeQuotes(part)}")?`;
+	renderMutatingAnnotateNode(node) {
+		const targetName = node.targetName;
+		const targetDef = this.resolveTargetDef(targetName);
+		this.writeln("// Ad-hoc annotations for ", targetName);
+		for (const entry of node.entries) {
+			const anns = entry.annotations;
+			if (!anns || anns.length === 0) continue;
+			const parts = entry.hasChain ? [entry.id, ...entry.chain.map((c) => c.text)] : [entry.id];
+			const accessors = this.buildMutatingAccessors(targetName, targetDef, parts);
+			for (const accessor of accessors) {
+				const cleared = new Set();
 				for (const an of anns) {
 					const { value, multiple } = this.computeAnnotationValue(entry, an);
 					if (multiple) {
-						this.writeln(`{`);
-						this.indent();
-						this.writeln(`const __t = ${accessor}.metadata`);
-						this.writeln(`const __k = "${escapeQuotes(an.name)}"`);
-						this.writeln(`const __v = ${value}`);
-						this.writeln(`if (__t) { const __e = __t.get(__k); __t.set(__k, Array.isArray(__e) ? [...__e, __v] : __e !== undefined ? [__e, __v] : [__v]) }`);
-						this.unindent();
-						this.writeln(`}`);
-					} else this.writeln(`${accessor}.metadata.set("${escapeQuotes(an.name)}", ${value})`);
+						if (!cleared.has(an.name)) {
+							const spec = this.doc.resolveAnnotation(an.name);
+							if (!spec || spec.config.mergeStrategy !== "append") this.writeln(`${accessor}.metadata.delete("${escapeQuotes(an.name)}")`);
+							cleared.add(an.name);
+						}
+						this.writeln(`$a(${accessor}.metadata, "${escapeQuotes(an.name)}", ${value}, true)`);
+					} else this.writeln(`$a(${accessor}.metadata, "${escapeQuotes(an.name)}", ${value})`);
 				}
 			}
-			const topAnnotations = node.annotations;
-			if (topAnnotations && topAnnotations.length > 0) for (const an of topAnnotations) {
+		}
+		const topAnnotations = node.annotations;
+		if (topAnnotations && topAnnotations.length > 0) {
+			const cleared = new Set();
+			for (const an of topAnnotations) {
 				const { value, multiple } = this.computeAnnotationValue(node, an);
 				if (multiple) {
-					this.writeln(`{`);
-					this.indent();
-					this.writeln(`const __t = ${targetName}.metadata`);
-					this.writeln(`const __k = "${escapeQuotes(an.name)}"`);
-					this.writeln(`const __v = ${value}`);
-					this.writeln(`if (__t) { const __e = __t.get(__k); __t.set(__k, Array.isArray(__e) ? [...__e, __v] : __e !== undefined ? [__e, __v] : [__v]) }`);
-					this.unindent();
-					this.writeln(`}`);
-				} else this.writeln(`${targetName}.metadata.set("${escapeQuotes(an.name)}", ${value})`);
+					if (!cleared.has(an.name)) {
+						const spec = this.doc.resolveAnnotation(an.name);
+						if (!spec || spec.config.mergeStrategy !== "append") this.writeln(`${targetName}.metadata.delete("${escapeQuotes(an.name)}")`);
+						cleared.add(an.name);
+					}
+					this.writeln(`$a(${targetName}.metadata, "${escapeQuotes(an.name)}", ${value}, true)`);
+				} else this.writeln(`$a(${targetName}.metadata, "${escapeQuotes(an.name)}", ${value})`);
+			}
+		}
+		this.writeln();
+	}
+	resolveTargetDef(targetName) {
+		const unwound = this.doc.unwindType(targetName);
+		if (!unwound?.def) return undefined;
+		let def = unwound.def;
+		if ((0, __atscript_core.isInterface)(def)) def = def.getDefinition() || def;
+		return def;
+	}
+	/**
+	* Builds the runtime accessor paths for mutating annotate entries.
+	* Computes exact paths at compile time by walking the AST,
+	* so the generated JS accesses props directly without runtime search.
+	* Returns multiple paths when a property appears in multiple union branches.
+	*/ buildMutatingAccessors(targetName, targetDef, parts) {
+		let accessors = [{
+			prefix: targetName + ".type",
+			def: targetDef
+		}];
+		for (let i = 0; i < parts.length; i++) {
+			const nextAccessors = [];
+			for (const { prefix, def } of accessors) {
+				const results = this.buildPropPaths(def, parts[i]);
+				if (results.length > 0) for (const result of results) if (i < parts.length - 1) nextAccessors.push({
+					prefix: prefix + result.path + "?.type",
+					def: result.propDef
+				});
+else nextAccessors.push({
+					prefix: prefix + result.path + "?",
+					def: result.propDef
+				});
+else {
+					const suffix = `.props.get("${escapeQuotes(parts[i])}")` + (i < parts.length - 1 ? "?.type" : "?");
+					nextAccessors.push({
+						prefix: prefix + suffix,
+						def: undefined
+					});
+				}
 			}
+			accessors = nextAccessors;
+		}
+		return accessors.map((a) => a.prefix);
+	}
+	/**
+	* Finds a property in a type tree at compile time, returning all
+	* matching runtime path strings and prop definitions for further chaining.
+	* Returns multiple results when the same property appears in different union branches.
+	*/ buildPropPaths(def, propName) {
+		if (!def) return [];
+		def = this.doc.mergeIntersection(def);
+		if ((0, __atscript_core.isRef)(def)) {
+			const ref = def;
+			const unwound = this.doc.unwindType(ref.id, ref.chain)?.def;
+			return this.buildPropPaths(unwound, propName);
+		}
+		if ((0, __atscript_core.isInterface)(def)) return this.buildPropPaths(def.getDefinition(), propName);
+		if ((0, __atscript_core.isStructure)(def)) {
+			const prop = def.props.get(propName);
+			if (prop) return [{
+				path: `.props.get("${escapeQuotes(propName)}")`,
+				propDef: prop.getDefinition()
+			}];
+			return [];
+		}
+		if ((0, __atscript_core.isGroup)(def)) {
+			const group = def;
+			const items = group.unwrap();
+			const results = [];
+			for (let i = 0; i < items.length; i++) for (const result of this.buildPropPaths(items[i], propName)) results.push({
+				path: `.items[${i}].type${result.path}`,
+				propDef: result.propDef
+			});
+			return results;
 		}
+		return [];
 	}
 	constructor(doc, opts) {
-		super(doc), _define_property$1(this, "opts", void 0), _define_property$1(this, "postAnnotate", void 0), _define_property$1(this, "mutatingAnnotates", void 0), _define_property$1(this, "_adHocAnnotations", void 0), _define_property$1(this, "_propPath", void 0), this.opts = opts, this.postAnnotate = [], this.mutatingAnnotates = [], this._adHocAnnotations = null, this._propPath = [];
+		super(doc), _define_property$1(this, "opts", void 0), _define_property$1(this, "postAnnotate", void 0), _define_property$1(this, "_adHocAnnotations", void 0), _define_property$1(this, "_propPath", void 0), this.opts = opts, this.postAnnotate = [], this._adHocAnnotations = null, this._propPath = [];
 	}
 };
 

package/dist/index.cjs

@@ -322,7 +322,7 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			this.writeln("static __is_atscript_annotated_type: true");
 			this.writeln(`static type: TAtscriptTypeObject<keyof ${asClass}>`);
 			this.writeln(`static metadata: TMetadataMap<AtscriptMetadata>`);
-			this.writeln(`static validator: <TT extends TAtscriptAnnotatedTypeConstructor = ${asClass}>(opts?: Partial<TValidatorOptions>) => Validator<TT>`);
+			this.writeln(`static validator: <TT extends TAtscriptAnnotatedTypeConstructor = typeof ${asClass}>(opts?: Partial<TValidatorOptions>) => Validator<TT>`);
 			this.writeln("static toJsonSchema: () => any");
 		}
 		this.pop();
@@ -351,33 +351,33 @@ else this.writeln("{}");
 	renderAnnotate(node) {
 		if (node.isMutating) return;
 		const targetName = node.targetName;
-		const unwound = this.doc.unwindType(targetName);
-		if (!unwound?.def) return;
-		const def = this.doc.mergeIntersection(unwound.def);
 		this.writeln();
 		const exported = node.token("export")?.text === "export";
 		this.renderJsDoc(node);
-		if ((0, __atscript_core.isStructure)(def) || (0, __atscript_core.isInterface)(def)) {
-			this.write(exported ? "export declare " : "declare ");
-			this.write(`class ${node.id} `);
-			this.renderStructure(def, node.id);
-		} else {
+		if (this.isTypeTarget(targetName)) {
 			this.write(exported ? "export " : "declare ");
-			this.write(`type ${node.id} = `);
-			this.renderTypeDef(def);
+			this.write(`type ${node.id} = ${targetName}`);
+			this.writeln();
+			const unwound = this.doc.unwindType(targetName);
+			this.renderTypeNamespaceFor(node.id, unwound?.def);
+		} else {
+			this.write(exported ? "export declare " : "declare ");
+			this.writeln(`class ${node.id} extends ${targetName} {}`);
+			this.writeln();
 		}
-		this.writeln();
 	}
 	renderTypeNamespace(node) {
-		this.write(`declare namespace ${node.id} `);
+		this.renderTypeNamespaceFor(node.id, node.getDefinition());
+	}
+	renderTypeNamespaceFor(name, inputDef) {
+		this.write(`declare namespace ${name} `);
 		this.blockln("{}");
-		const def = node.getDefinition();
 		let typeDef = "TAtscriptTypeDef";
-		if (def) {
-			let realDef = def;
-			if ((0, __atscript_core.isRef)(def)) realDef = this.doc.unwindType(def.id, def.chain)?.def || realDef;
+		if (inputDef) {
+			let realDef = inputDef;
+			if ((0, __atscript_core.isRef)(inputDef)) realDef = this.doc.unwindType(inputDef.id, inputDef.chain)?.def || realDef;
 			realDef = this.doc.mergeIntersection(realDef);
-			if ((0, __atscript_core.isStructure)(realDef) || (0, __atscript_core.isInterface)(realDef)) typeDef = `TAtscriptTypeObject<keyof ${node.id}>`;
+			if ((0, __atscript_core.isStructure)(realDef) || (0, __atscript_core.isInterface)(realDef)) typeDef = `TAtscriptTypeObject<keyof ${name}>`;
 else if ((0, __atscript_core.isGroup)(realDef)) typeDef = "TAtscriptTypeComplex";
 else if ((0, __atscript_core.isArray)(realDef)) typeDef = "TAtscriptTypeArray";
 else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = "TAtscriptTypeFinal";
@@ -385,10 +385,19 @@ else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = "TAtscriptTypeFina
 		this.writeln(`const __is_atscript_annotated_type: true`);
 		this.writeln(`const type: ${typeDef}`);
 		this.writeln(`const metadata: TMetadataMap<AtscriptMetadata>`);
-		this.writeln(`const validator: <TT extends TAtscriptAnnotatedTypeConstructor = ${node.id}>(opts?: Partial<TValidatorOptions>) => Validator<TT>`);
+		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<TAtscriptAnnotatedTypeConstructor, ${name}>`);
 		this.writeln("const toJsonSchema: () => any");
 		this.popln();
 	}
+	isTypeTarget(name, doc) {
+		const d = doc || this.doc;
+		const decl = d.getDeclarationOwnerNode(name);
+		if (!decl?.node) return false;
+		if (decl.node.entity === "type") return true;
+		if (decl.node.entity === "interface") return false;
+		if (decl.node.entity === "annotate") return this.isTypeTarget(decl.node.targetName, decl.doc);
+		return false;
+	}
 	renderJsDoc(node) {
 		const range = node.token("identifier")?.range;
 		const rangeStr = range ? `:${range.start.line + 1}:${range.start.character + 1}` : "";
@@ -757,6 +766,15 @@ var ValidatorError = class extends Error {
 function isAnnotatedType(type) {
 	return type && type.__is_atscript_annotated_type;
 }
+function annotate(metadata, key, value, asArray) {
+	if (!metadata) return;
+	if (asArray) if (metadata.has(key)) {
+		const a = metadata.get(key);
+		if (Array.isArray(a)) a.push(value);
+else metadata.set(key, [a, value]);
+	} else metadata.set(key, [value]);
+else metadata.set(key, value);
+}
 function defineAnnotatedType(_kind, base) {
 	const kind = _kind || "";
 	const type = base?.type || {};
@@ -856,12 +874,7 @@ else if (!newBase) throw new Error(`"${typeName}" is not annotated type`);
 			return this;
 		},
 		annotate(key, value, asArray) {
-			if (asArray) if (this.$metadata.has(key)) {
-				const a = this.$metadata.get(key);
-				if (Array.isArray(a)) a.push(value);
-else this.$metadata.set(key, [a, value]);
-			} else this.$metadata.set(key, [value]);
-else this.$metadata.set(key, value);
+			annotate(this.$metadata, key, value, asArray);
 			return this;
 		}
 	};
@@ -965,7 +978,7 @@ var JsRenderer = class extends BaseRenderer {
 	pre() {
 		this.writeln("// prettier-ignore-start");
 		this.writeln("/* eslint-disable */");
-		const imports = ["defineAnnotatedType as $"];
+		const imports = ["defineAnnotatedType as $", "annotate as $a"];
 		if (!this.opts?.preRenderJsonSchema) imports.push("buildJsonSchema as $$");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 	}
@@ -984,27 +997,26 @@ var JsRenderer = class extends BaseRenderer {
 	post() {
 		for (const node of this.postAnnotate) if (node.entity === "annotate") {
 			const annotateNode = node;
-			const unwound = this.doc.unwindType(annotateNode.targetName);
-			if (unwound?.def) {
-				let def = this.doc.mergeIntersection(unwound.def);
-				if ((0, __atscript_core.isInterface)(def)) def = def.getDefinition() || def;
-				this._adHocAnnotations = this.buildAdHocMap([annotateNode]);
-				this.annotateType(def, node.id);
-				this._adHocAnnotations = null;
-				this.indent();
-				this.defineMetadataForAnnotateAlias(annotateNode);
-				this.unindent();
-				this.writeln();
+			if (annotateNode.isMutating) this.renderMutatingAnnotateNode(annotateNode);
+else {
+				const unwound = this.doc.unwindType(annotateNode.targetName);
+				if (unwound?.def) {
+					let def = this.doc.mergeIntersection(unwound.def);
+					if ((0, __atscript_core.isInterface)(def)) def = def.getDefinition() || def;
+					this._adHocAnnotations = this.buildAdHocMap([annotateNode]);
+					this.annotateType(def, node.id);
+					this._adHocAnnotations = null;
+					this.indent();
+					this.defineMetadataForAnnotateAlias(annotateNode);
+					this.unindent();
+					this.writeln();
+				}
 			}
 		} else {
-			const mutatingNodes = this.doc.getAnnotateNodesFor(node.id).filter((n) => n.isMutating);
-			this._adHocAnnotations = this.buildAdHocMap(mutatingNodes);
 			this.annotateType(node.getDefinition(), node.id);
-			this._adHocAnnotations = null;
 			this.indent().defineMetadata(node).unindent();
 			this.writeln();
 		}
-		this.renderMutatingAnnotates();
 		this.writeln("// prettier-ignore-end");
 		super.post();
 	}
@@ -1038,7 +1050,7 @@ var JsRenderer = class extends BaseRenderer {
 	}
 	renderAnnotate(node) {
 		if (node.isMutating) {
-			this.mutatingAnnotates.push(node);
+			this.postAnnotate.push(node);
 			return;
 		}
 		const targetName = node.targetName;
@@ -1326,18 +1338,13 @@ else handle.prop(prop.id, propHandle.$type);
 		return this;
 	}
 	defineMetadata(node) {
-		const annotations = this.doc.evalAnnotationsForNode(node);
-		let adHocNames;
-		let adHoc;
+		let annotations = this.doc.evalAnnotationsForNode(node);
 		if (this._adHocAnnotations && this._propPath.length > 0) {
 			const path$2 = this._propPath.join(".");
-			adHoc = this._adHocAnnotations.get(path$2);
-			if (adHoc) adHocNames = new Set(adHoc.map((a) => a.name));
+			const adHoc = this._adHocAnnotations.get(path$2);
+			if (adHoc) annotations = this.doc.mergeNodesAnnotations(annotations, adHoc);
 		}
 		annotations?.forEach((an) => {
-			if (!adHocNames || !adHocNames.has(an.name)) this.resolveAnnotationValue(node, an);
-		});
-		adHoc?.forEach((an) => {
 			this.resolveAnnotationValue(node, an);
 		});
 		return this;
@@ -1349,11 +1356,8 @@ else handle.prop(prop.id, propHandle.$type);
 		const annotateAnnotations = this.doc.evalAnnotationsForNode(annotateNode);
 		const targetDecl = this.doc.getDeclarationOwnerNode(annotateNode.targetName);
 		const targetAnnotations = targetDecl?.node ? targetDecl.doc.evalAnnotationsForNode(targetDecl.node) : undefined;
-		const overriddenNames = new Set(annotateAnnotations?.map((a) => a.name));
-		targetAnnotations?.forEach((an) => {
-			if (!overriddenNames.has(an.name)) this.resolveAnnotationValue(annotateNode, an);
-		});
-		annotateAnnotations?.forEach((an) => {
+		const merged = this.doc.mergeNodesAnnotations(targetAnnotations, annotateAnnotations);
+		merged.forEach((an) => {
 			this.resolveAnnotationValue(annotateNode, an);
 		});
 		return this;
@@ -1392,47 +1396,123 @@ else targetValue = "true";
 			multiple: !!multiple
 		};
 	}
-	renderMutatingAnnotates() {
-		for (const node of this.mutatingAnnotates) {
-			const targetName = node.targetName;
-			for (const entry of node.entries) {
-				const anns = entry.annotations;
-				if (!anns || anns.length === 0) continue;
-				const parts = entry.hasChain ? [entry.id, ...entry.chain.map((c) => c.text)] : [entry.id];
-				let accessor = targetName;
-				for (const part of parts) accessor += `.type.props.get("${escapeQuotes(part)}")?`;
+	renderMutatingAnnotateNode(node) {
+		const targetName = node.targetName;
+		const targetDef = this.resolveTargetDef(targetName);
+		this.writeln("// Ad-hoc annotations for ", targetName);
+		for (const entry of node.entries) {
+			const anns = entry.annotations;
+			if (!anns || anns.length === 0) continue;
+			const parts = entry.hasChain ? [entry.id, ...entry.chain.map((c) => c.text)] : [entry.id];
+			const accessors = this.buildMutatingAccessors(targetName, targetDef, parts);
+			for (const accessor of accessors) {
+				const cleared = new Set();
 				for (const an of anns) {
 					const { value, multiple } = this.computeAnnotationValue(entry, an);
 					if (multiple) {
-						this.writeln(`{`);
-						this.indent();
-						this.writeln(`const __t = ${accessor}.metadata`);
-						this.writeln(`const __k = "${escapeQuotes(an.name)}"`);
-						this.writeln(`const __v = ${value}`);
-						this.writeln(`if (__t) { const __e = __t.get(__k); __t.set(__k, Array.isArray(__e) ? [...__e, __v] : __e !== undefined ? [__e, __v] : [__v]) }`);
-						this.unindent();
-						this.writeln(`}`);
-					} else this.writeln(`${accessor}.metadata.set("${escapeQuotes(an.name)}", ${value})`);
+						if (!cleared.has(an.name)) {
+							const spec = this.doc.resolveAnnotation(an.name);
+							if (!spec || spec.config.mergeStrategy !== "append") this.writeln(`${accessor}.metadata.delete("${escapeQuotes(an.name)}")`);
+							cleared.add(an.name);
+						}
+						this.writeln(`$a(${accessor}.metadata, "${escapeQuotes(an.name)}", ${value}, true)`);
+					} else this.writeln(`$a(${accessor}.metadata, "${escapeQuotes(an.name)}", ${value})`);
 				}
 			}
-			const topAnnotations = node.annotations;
-			if (topAnnotations && topAnnotations.length > 0) for (const an of topAnnotations) {
+		}
+		const topAnnotations = node.annotations;
+		if (topAnnotations && topAnnotations.length > 0) {
+			const cleared = new Set();
+			for (const an of topAnnotations) {
 				const { value, multiple } = this.computeAnnotationValue(node, an);
 				if (multiple) {
-					this.writeln(`{`);
-					this.indent();
-					this.writeln(`const __t = ${targetName}.metadata`);
-					this.writeln(`const __k = "${escapeQuotes(an.name)}"`);
-					this.writeln(`const __v = ${value}`);
-					this.writeln(`if (__t) { const __e = __t.get(__k); __t.set(__k, Array.isArray(__e) ? [...__e, __v] : __e !== undefined ? [__e, __v] : [__v]) }`);
-					this.unindent();
-					this.writeln(`}`);
-				} else this.writeln(`${targetName}.metadata.set("${escapeQuotes(an.name)}", ${value})`);
+					if (!cleared.has(an.name)) {
+						const spec = this.doc.resolveAnnotation(an.name);
+						if (!spec || spec.config.mergeStrategy !== "append") this.writeln(`${targetName}.metadata.delete("${escapeQuotes(an.name)}")`);
+						cleared.add(an.name);
+					}
+					this.writeln(`$a(${targetName}.metadata, "${escapeQuotes(an.name)}", ${value}, true)`);
+				} else this.writeln(`$a(${targetName}.metadata, "${escapeQuotes(an.name)}", ${value})`);
+			}
+		}
+		this.writeln();
+	}
+	resolveTargetDef(targetName) {
+		const unwound = this.doc.unwindType(targetName);
+		if (!unwound?.def) return undefined;
+		let def = unwound.def;
+		if ((0, __atscript_core.isInterface)(def)) def = def.getDefinition() || def;
+		return def;
+	}
+	/**
+	* Builds the runtime accessor paths for mutating annotate entries.
+	* Computes exact paths at compile time by walking the AST,
+	* so the generated JS accesses props directly without runtime search.
+	* Returns multiple paths when a property appears in multiple union branches.
+	*/ buildMutatingAccessors(targetName, targetDef, parts) {
+		let accessors = [{
+			prefix: targetName + ".type",
+			def: targetDef
+		}];
+		for (let i = 0; i < parts.length; i++) {
+			const nextAccessors = [];
+			for (const { prefix, def } of accessors) {
+				const results = this.buildPropPaths(def, parts[i]);
+				if (results.length > 0) for (const result of results) if (i < parts.length - 1) nextAccessors.push({
+					prefix: prefix + result.path + "?.type",
+					def: result.propDef
+				});
+else nextAccessors.push({
+					prefix: prefix + result.path + "?",
+					def: result.propDef
+				});
+else {
+					const suffix = `.props.get("${escapeQuotes(parts[i])}")` + (i < parts.length - 1 ? "?.type" : "?");
+					nextAccessors.push({
+						prefix: prefix + suffix,
+						def: undefined
+					});
+				}
 			}
+			accessors = nextAccessors;
+		}
+		return accessors.map((a) => a.prefix);
+	}
+	/**
+	* Finds a property in a type tree at compile time, returning all
+	* matching runtime path strings and prop definitions for further chaining.
+	* Returns multiple results when the same property appears in different union branches.
+	*/ buildPropPaths(def, propName) {
+		if (!def) return [];
+		def = this.doc.mergeIntersection(def);
+		if ((0, __atscript_core.isRef)(def)) {
+			const ref = def;
+			const unwound = this.doc.unwindType(ref.id, ref.chain)?.def;
+			return this.buildPropPaths(unwound, propName);
+		}
+		if ((0, __atscript_core.isInterface)(def)) return this.buildPropPaths(def.getDefinition(), propName);
+		if ((0, __atscript_core.isStructure)(def)) {
+			const prop = def.props.get(propName);
+			if (prop) return [{
+				path: `.props.get("${escapeQuotes(propName)}")`,
+				propDef: prop.getDefinition()
+			}];
+			return [];
+		}
+		if ((0, __atscript_core.isGroup)(def)) {
+			const group = def;
+			const items = group.unwrap();
+			const results = [];
+			for (let i = 0; i < items.length; i++) for (const result of this.buildPropPaths(items[i], propName)) results.push({
+				path: `.items[${i}].type${result.path}`,
+				propDef: result.propDef
+			});
+			return results;
 		}
+		return [];
 	}
 	constructor(doc, opts) {
-		super(doc), _define_property(this, "opts", void 0), _define_property(this, "postAnnotate", void 0), _define_property(this, "mutatingAnnotates", void 0), _define_property(this, "_adHocAnnotations", void 0), _define_property(this, "_propPath", void 0), this.opts = opts, this.postAnnotate = [], this.mutatingAnnotates = [], this._adHocAnnotations = null, this._propPath = [];
+		super(doc), _define_property(this, "opts", void 0), _define_property(this, "postAnnotate", void 0), _define_property(this, "_adHocAnnotations", void 0), _define_property(this, "_propPath", void 0), this.opts = opts, this.postAnnotate = [], this._adHocAnnotations = null, this._propPath = [];
 	}
 };
 

package/dist/index.mjs

@@ -298,7 +298,7 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			this.writeln("static __is_atscript_annotated_type: true");
 			this.writeln(`static type: TAtscriptTypeObject<keyof ${asClass}>`);
 			this.writeln(`static metadata: TMetadataMap<AtscriptMetadata>`);
-			this.writeln(`static validator: <TT extends TAtscriptAnnotatedTypeConstructor = ${asClass}>(opts?: Partial<TValidatorOptions>) => Validator<TT>`);
+			this.writeln(`static validator: <TT extends TAtscriptAnnotatedTypeConstructor = typeof ${asClass}>(opts?: Partial<TValidatorOptions>) => Validator<TT>`);
 			this.writeln("static toJsonSchema: () => any");
 		}
 		this.pop();
@@ -327,33 +327,33 @@ else this.writeln("{}");
 	renderAnnotate(node) {
 		if (node.isMutating) return;
 		const targetName = node.targetName;
-		const unwound = this.doc.unwindType(targetName);
-		if (!unwound?.def) return;
-		const def = this.doc.mergeIntersection(unwound.def);
 		this.writeln();
 		const exported = node.token("export")?.text === "export";
 		this.renderJsDoc(node);
-		if (isStructure(def) || isInterface(def)) {
-			this.write(exported ? "export declare " : "declare ");
-			this.write(`class ${node.id} `);
-			this.renderStructure(def, node.id);
-		} else {
+		if (this.isTypeTarget(targetName)) {
 			this.write(exported ? "export " : "declare ");
-			this.write(`type ${node.id} = `);
-			this.renderTypeDef(def);
+			this.write(`type ${node.id} = ${targetName}`);
+			this.writeln();
+			const unwound = this.doc.unwindType(targetName);
+			this.renderTypeNamespaceFor(node.id, unwound?.def);
+		} else {
+			this.write(exported ? "export declare " : "declare ");
+			this.writeln(`class ${node.id} extends ${targetName} {}`);
+			this.writeln();
 		}
-		this.writeln();
 	}
 	renderTypeNamespace(node) {
-		this.write(`declare namespace ${node.id} `);
+		this.renderTypeNamespaceFor(node.id, node.getDefinition());
+	}
+	renderTypeNamespaceFor(name, inputDef) {
+		this.write(`declare namespace ${name} `);
 		this.blockln("{}");
-		const def = node.getDefinition();
 		let typeDef = "TAtscriptTypeDef";
-		if (def) {
-			let realDef = def;
-			if (isRef(def)) realDef = this.doc.unwindType(def.id, def.chain)?.def || realDef;
+		if (inputDef) {
+			let realDef = inputDef;
+			if (isRef(inputDef)) realDef = this.doc.unwindType(inputDef.id, inputDef.chain)?.def || realDef;
 			realDef = this.doc.mergeIntersection(realDef);
-			if (isStructure(realDef) || isInterface(realDef)) typeDef = `TAtscriptTypeObject<keyof ${node.id}>`;
+			if (isStructure(realDef) || isInterface(realDef)) typeDef = `TAtscriptTypeObject<keyof ${name}>`;
 else if (isGroup(realDef)) typeDef = "TAtscriptTypeComplex";
 else if (isArray(realDef)) typeDef = "TAtscriptTypeArray";
 else if (isPrimitive(realDef)) typeDef = "TAtscriptTypeFinal";
@@ -361,10 +361,19 @@ else if (isPrimitive(realDef)) typeDef = "TAtscriptTypeFinal";
 		this.writeln(`const __is_atscript_annotated_type: true`);
 		this.writeln(`const type: ${typeDef}`);
 		this.writeln(`const metadata: TMetadataMap<AtscriptMetadata>`);
-		this.writeln(`const validator: <TT extends TAtscriptAnnotatedTypeConstructor = ${node.id}>(opts?: Partial<TValidatorOptions>) => Validator<TT>`);
+		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<TAtscriptAnnotatedTypeConstructor, ${name}>`);
 		this.writeln("const toJsonSchema: () => any");
 		this.popln();
 	}
+	isTypeTarget(name, doc) {
+		const d = doc || this.doc;
+		const decl = d.getDeclarationOwnerNode(name);
+		if (!decl?.node) return false;
+		if (decl.node.entity === "type") return true;
+		if (decl.node.entity === "interface") return false;
+		if (decl.node.entity === "annotate") return this.isTypeTarget(decl.node.targetName, decl.doc);
+		return false;
+	}
 	renderJsDoc(node) {
 		const range = node.token("identifier")?.range;
 		const rangeStr = range ? `:${range.start.line + 1}:${range.start.character + 1}` : "";
@@ -733,6 +742,15 @@ var ValidatorError = class extends Error {
 function isAnnotatedType(type) {
 	return type && type.__is_atscript_annotated_type;
 }
+function annotate(metadata, key, value, asArray) {
+	if (!metadata) return;
+	if (asArray) if (metadata.has(key)) {
+		const a = metadata.get(key);
+		if (Array.isArray(a)) a.push(value);
+else metadata.set(key, [a, value]);
+	} else metadata.set(key, [value]);
+else metadata.set(key, value);
+}
 function defineAnnotatedType(_kind, base) {
 	const kind = _kind || "";
 	const type = base?.type || {};
@@ -832,12 +850,7 @@ else if (!newBase) throw new Error(`"${typeName}" is not annotated type`);
 			return this;
 		},
 		annotate(key, value, asArray) {
-			if (asArray) if (this.$metadata.has(key)) {
-				const a = this.$metadata.get(key);
-				if (Array.isArray(a)) a.push(value);
-else this.$metadata.set(key, [a, value]);
-			} else this.$metadata.set(key, [value]);
-else this.$metadata.set(key, value);
+			annotate(this.$metadata, key, value, asArray);
 			return this;
 		}
 	};
@@ -941,7 +954,7 @@ var JsRenderer = class extends BaseRenderer {
 	pre() {
 		this.writeln("// prettier-ignore-start");
 		this.writeln("/* eslint-disable */");
-		const imports = ["defineAnnotatedType as $"];
+		const imports = ["defineAnnotatedType as $", "annotate as $a"];
 		if (!this.opts?.preRenderJsonSchema) imports.push("buildJsonSchema as $$");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 	}
@@ -960,27 +973,26 @@ var JsRenderer = class extends BaseRenderer {
 	post() {
 		for (const node of this.postAnnotate) if (node.entity === "annotate") {
 			const annotateNode = node;
-			const unwound = this.doc.unwindType(annotateNode.targetName);
-			if (unwound?.def) {
-				let def = this.doc.mergeIntersection(unwound.def);
-				if (isInterface(def)) def = def.getDefinition() || def;
-				this._adHocAnnotations = this.buildAdHocMap([annotateNode]);
-				this.annotateType(def, node.id);
-				this._adHocAnnotations = null;
-				this.indent();
-				this.defineMetadataForAnnotateAlias(annotateNode);
-				this.unindent();
-				this.writeln();
+			if (annotateNode.isMutating) this.renderMutatingAnnotateNode(annotateNode);
+else {
+				const unwound = this.doc.unwindType(annotateNode.targetName);
+				if (unwound?.def) {
+					let def = this.doc.mergeIntersection(unwound.def);
+					if (isInterface(def)) def = def.getDefinition() || def;
+					this._adHocAnnotations = this.buildAdHocMap([annotateNode]);
+					this.annotateType(def, node.id);
+					this._adHocAnnotations = null;
+					this.indent();
+					this.defineMetadataForAnnotateAlias(annotateNode);
+					this.unindent();
+					this.writeln();
+				}
 			}
 		} else {
-			const mutatingNodes = this.doc.getAnnotateNodesFor(node.id).filter((n) => n.isMutating);
-			this._adHocAnnotations = this.buildAdHocMap(mutatingNodes);
 			this.annotateType(node.getDefinition(), node.id);
-			this._adHocAnnotations = null;
 			this.indent().defineMetadata(node).unindent();
 			this.writeln();
 		}
-		this.renderMutatingAnnotates();
 		this.writeln("// prettier-ignore-end");
 		super.post();
 	}
@@ -1014,7 +1026,7 @@ var JsRenderer = class extends BaseRenderer {
 	}
 	renderAnnotate(node) {
 		if (node.isMutating) {
-			this.mutatingAnnotates.push(node);
+			this.postAnnotate.push(node);
 			return;
 		}
 		const targetName = node.targetName;
@@ -1302,18 +1314,13 @@ else handle.prop(prop.id, propHandle.$type);
 		return this;
 	}
 	defineMetadata(node) {
-		const annotations = this.doc.evalAnnotationsForNode(node);
-		let adHocNames;
-		let adHoc;
+		let annotations = this.doc.evalAnnotationsForNode(node);
 		if (this._adHocAnnotations && this._propPath.length > 0) {
 			const path$1 = this._propPath.join(".");
-			adHoc = this._adHocAnnotations.get(path$1);
-			if (adHoc) adHocNames = new Set(adHoc.map((a) => a.name));
+			const adHoc = this._adHocAnnotations.get(path$1);
+			if (adHoc) annotations = this.doc.mergeNodesAnnotations(annotations, adHoc);
 		}
 		annotations?.forEach((an) => {
-			if (!adHocNames || !adHocNames.has(an.name)) this.resolveAnnotationValue(node, an);
-		});
-		adHoc?.forEach((an) => {
 			this.resolveAnnotationValue(node, an);
 		});
 		return this;
@@ -1325,11 +1332,8 @@ else handle.prop(prop.id, propHandle.$type);
 		const annotateAnnotations = this.doc.evalAnnotationsForNode(annotateNode);
 		const targetDecl = this.doc.getDeclarationOwnerNode(annotateNode.targetName);
 		const targetAnnotations = targetDecl?.node ? targetDecl.doc.evalAnnotationsForNode(targetDecl.node) : undefined;
-		const overriddenNames = new Set(annotateAnnotations?.map((a) => a.name));
-		targetAnnotations?.forEach((an) => {
-			if (!overriddenNames.has(an.name)) this.resolveAnnotationValue(annotateNode, an);
-		});
-		annotateAnnotations?.forEach((an) => {
+		const merged = this.doc.mergeNodesAnnotations(targetAnnotations, annotateAnnotations);
+		merged.forEach((an) => {
 			this.resolveAnnotationValue(annotateNode, an);
 		});
 		return this;
@@ -1368,47 +1372,123 @@ else targetValue = "true";
 			multiple: !!multiple
 		};
 	}
-	renderMutatingAnnotates() {
-		for (const node of this.mutatingAnnotates) {
-			const targetName = node.targetName;
-			for (const entry of node.entries) {
-				const anns = entry.annotations;
-				if (!anns || anns.length === 0) continue;
-				const parts = entry.hasChain ? [entry.id, ...entry.chain.map((c) => c.text)] : [entry.id];
-				let accessor = targetName;
-				for (const part of parts) accessor += `.type.props.get("${escapeQuotes(part)}")?`;
+	renderMutatingAnnotateNode(node) {
+		const targetName = node.targetName;
+		const targetDef = this.resolveTargetDef(targetName);
+		this.writeln("// Ad-hoc annotations for ", targetName);
+		for (const entry of node.entries) {
+			const anns = entry.annotations;
+			if (!anns || anns.length === 0) continue;
+			const parts = entry.hasChain ? [entry.id, ...entry.chain.map((c) => c.text)] : [entry.id];
+			const accessors = this.buildMutatingAccessors(targetName, targetDef, parts);
+			for (const accessor of accessors) {
+				const cleared = new Set();
 				for (const an of anns) {
 					const { value, multiple } = this.computeAnnotationValue(entry, an);
 					if (multiple) {
-						this.writeln(`{`);
-						this.indent();
-						this.writeln(`const __t = ${accessor}.metadata`);
-						this.writeln(`const __k = "${escapeQuotes(an.name)}"`);
-						this.writeln(`const __v = ${value}`);
-						this.writeln(`if (__t) { const __e = __t.get(__k); __t.set(__k, Array.isArray(__e) ? [...__e, __v] : __e !== undefined ? [__e, __v] : [__v]) }`);
-						this.unindent();
-						this.writeln(`}`);
-					} else this.writeln(`${accessor}.metadata.set("${escapeQuotes(an.name)}", ${value})`);
+						if (!cleared.has(an.name)) {
+							const spec = this.doc.resolveAnnotation(an.name);
+							if (!spec || spec.config.mergeStrategy !== "append") this.writeln(`${accessor}.metadata.delete("${escapeQuotes(an.name)}")`);
+							cleared.add(an.name);
+						}
+						this.writeln(`$a(${accessor}.metadata, "${escapeQuotes(an.name)}", ${value}, true)`);
+					} else this.writeln(`$a(${accessor}.metadata, "${escapeQuotes(an.name)}", ${value})`);
 				}
 			}
-			const topAnnotations = node.annotations;
-			if (topAnnotations && topAnnotations.length > 0) for (const an of topAnnotations) {
+		}
+		const topAnnotations = node.annotations;
+		if (topAnnotations && topAnnotations.length > 0) {
+			const cleared = new Set();
+			for (const an of topAnnotations) {
 				const { value, multiple } = this.computeAnnotationValue(node, an);
 				if (multiple) {
-					this.writeln(`{`);
-					this.indent();
-					this.writeln(`const __t = ${targetName}.metadata`);
-					this.writeln(`const __k = "${escapeQuotes(an.name)}"`);
-					this.writeln(`const __v = ${value}`);
-					this.writeln(`if (__t) { const __e = __t.get(__k); __t.set(__k, Array.isArray(__e) ? [...__e, __v] : __e !== undefined ? [__e, __v] : [__v]) }`);
-					this.unindent();
-					this.writeln(`}`);
-				} else this.writeln(`${targetName}.metadata.set("${escapeQuotes(an.name)}", ${value})`);
+					if (!cleared.has(an.name)) {
+						const spec = this.doc.resolveAnnotation(an.name);
+						if (!spec || spec.config.mergeStrategy !== "append") this.writeln(`${targetName}.metadata.delete("${escapeQuotes(an.name)}")`);
+						cleared.add(an.name);
+					}
+					this.writeln(`$a(${targetName}.metadata, "${escapeQuotes(an.name)}", ${value}, true)`);
+				} else this.writeln(`$a(${targetName}.metadata, "${escapeQuotes(an.name)}", ${value})`);
+			}
+		}
+		this.writeln();
+	}
+	resolveTargetDef(targetName) {
+		const unwound = this.doc.unwindType(targetName);
+		if (!unwound?.def) return undefined;
+		let def = unwound.def;
+		if (isInterface(def)) def = def.getDefinition() || def;
+		return def;
+	}
+	/**
+	* Builds the runtime accessor paths for mutating annotate entries.
+	* Computes exact paths at compile time by walking the AST,
+	* so the generated JS accesses props directly without runtime search.
+	* Returns multiple paths when a property appears in multiple union branches.
+	*/ buildMutatingAccessors(targetName, targetDef, parts) {
+		let accessors = [{
+			prefix: targetName + ".type",
+			def: targetDef
+		}];
+		for (let i = 0; i < parts.length; i++) {
+			const nextAccessors = [];
+			for (const { prefix, def } of accessors) {
+				const results = this.buildPropPaths(def, parts[i]);
+				if (results.length > 0) for (const result of results) if (i < parts.length - 1) nextAccessors.push({
+					prefix: prefix + result.path + "?.type",
+					def: result.propDef
+				});
+else nextAccessors.push({
+					prefix: prefix + result.path + "?",
+					def: result.propDef
+				});
+else {
+					const suffix = `.props.get("${escapeQuotes(parts[i])}")` + (i < parts.length - 1 ? "?.type" : "?");
+					nextAccessors.push({
+						prefix: prefix + suffix,
+						def: undefined
+					});
+				}
 			}
+			accessors = nextAccessors;
+		}
+		return accessors.map((a) => a.prefix);
+	}
+	/**
+	* Finds a property in a type tree at compile time, returning all
+	* matching runtime path strings and prop definitions for further chaining.
+	* Returns multiple results when the same property appears in different union branches.
+	*/ buildPropPaths(def, propName) {
+		if (!def) return [];
+		def = this.doc.mergeIntersection(def);
+		if (isRef(def)) {
+			const ref = def;
+			const unwound = this.doc.unwindType(ref.id, ref.chain)?.def;
+			return this.buildPropPaths(unwound, propName);
+		}
+		if (isInterface(def)) return this.buildPropPaths(def.getDefinition(), propName);
+		if (isStructure(def)) {
+			const prop = def.props.get(propName);
+			if (prop) return [{
+				path: `.props.get("${escapeQuotes(propName)}")`,
+				propDef: prop.getDefinition()
+			}];
+			return [];
+		}
+		if (isGroup(def)) {
+			const group = def;
+			const items = group.unwrap();
+			const results = [];
+			for (let i = 0; i < items.length; i++) for (const result of this.buildPropPaths(items[i], propName)) results.push({
+				path: `.items[${i}].type${result.path}`,
+				propDef: result.propDef
+			});
+			return results;
 		}
+		return [];
 	}
 	constructor(doc, opts) {
-		super(doc), _define_property(this, "opts", void 0), _define_property(this, "postAnnotate", void 0), _define_property(this, "mutatingAnnotates", void 0), _define_property(this, "_adHocAnnotations", void 0), _define_property(this, "_propPath", void 0), this.opts = opts, this.postAnnotate = [], this.mutatingAnnotates = [], this._adHocAnnotations = null, this._propPath = [];
+		super(doc), _define_property(this, "opts", void 0), _define_property(this, "postAnnotate", void 0), _define_property(this, "_adHocAnnotations", void 0), _define_property(this, "_propPath", void 0), this.opts = opts, this.postAnnotate = [], this._adHocAnnotations = null, this._propPath = [];
 	}
 };
 

package/dist/utils.cjs

@@ -338,6 +338,15 @@ var ValidatorError = class extends Error {
 function isAnnotatedType(type) {
 	return type && type.__is_atscript_annotated_type;
 }
+function annotate(metadata, key, value, asArray) {
+	if (!metadata) return;
+	if (asArray) if (metadata.has(key)) {
+		const a = metadata.get(key);
+		if (Array.isArray(a)) a.push(value);
+else metadata.set(key, [a, value]);
+	} else metadata.set(key, [value]);
+else metadata.set(key, value);
+}
 function defineAnnotatedType(_kind, base) {
 	const kind = _kind || "";
 	const type = base?.type || {};
@@ -437,12 +446,7 @@ else if (!newBase) throw new Error(`"${typeName}" is not annotated type`);
 			return this;
 		},
 		annotate(key, value, asArray) {
-			if (asArray) if (this.$metadata.has(key)) {
-				const a = this.$metadata.get(key);
-				if (Array.isArray(a)) a.push(value);
-else this.$metadata.set(key, [a, value]);
-			} else this.$metadata.set(key, [value]);
-else this.$metadata.set(key, value);
+			annotate(this.$metadata, key, value, asArray);
 			return this;
 		}
 	};
@@ -546,6 +550,7 @@ else schema.allOf = (schema.allOf || []).concat(patterns.map((p) => ({ pattern:
 //#endregion
 exports.Validator = Validator
 exports.ValidatorError = ValidatorError
+exports.annotate = annotate
 exports.buildJsonSchema = buildJsonSchema
 exports.defineAnnotatedType = defineAnnotatedType
 exports.isAnnotatedType = isAnnotatedType

package/dist/utils.d.ts

@@ -18,10 +18,10 @@ interface TValidatorPluginContext {
     error: Validator<any>['error'];
     path: Validator<any>['path'];
 }
-declare class Validator<T extends TAtscriptAnnotatedTypeConstructor> {
-    protected readonly def: T | TAtscriptAnnotatedType<any>;
+declare class Validator<T extends TAtscriptAnnotatedTypeConstructor, IT = InstanceType<T>> {
+    protected readonly def: T;
     protected opts: TValidatorOptions;
-    constructor(def: T | TAtscriptAnnotatedType<any>, opts?: Partial<TValidatorOptions>);
+    constructor(def: T, opts?: Partial<TValidatorOptions>);
     errors: TError[];
     protected stackErrors: TError[][];
     protected stackPath: string[];
@@ -31,7 +31,7 @@ declare class Validator<T extends TAtscriptAnnotatedTypeConstructor> {
     protected clear(): void;
     protected error(message: string, path?: string, details?: TError[]): void;
     protected throw(): void;
-    validate<TT = T>(value: any, safe?: boolean): value is TT;
+    validate<TT = IT>(value: any, safe?: boolean): value is TT;
     protected validateSafe(def: TAtscriptAnnotatedType, value: any): boolean;
     protected get path(): string;
     protected validateAnnotatedType(def: TAtscriptAnnotatedType, value: any): boolean;
@@ -94,6 +94,11 @@ type TAtscriptAnnotatedTypeConstructor = TAtscriptAnnotatedType & (new (...args:
  * Type Guard to check if a type is atscript-annotated
  */
 declare function isAnnotatedType(type: any): type is TAtscriptAnnotatedType;
+/**
+ * Standalone annotate function that handles both replace and append (array) strategies.
+ * Used by the handle's .annotate() method and by generated mutation statements.
+ */
+declare function annotate<K extends keyof AtscriptMetadata>(metadata: TMetadataMap<AtscriptMetadata> | undefined, key: K, value: AtscriptMetadata[K] extends (infer E)[] ? E : AtscriptMetadata[K], asArray?: boolean): void;
 type TKind = '' | 'array' | 'object' | 'union' | 'intersection' | 'tuple';
 declare function defineAnnotatedType(_kind?: TKind, base?: any): TAnnotatedTypeHandle;
 /**
@@ -129,4 +134,5 @@ declare function isAnnotatedTypeOfPrimitive(t: TAtscriptAnnotatedType): boolean;
 type TJsonSchema = Record<string, any>;
 declare function buildJsonSchema(type: TAtscriptAnnotatedType): TJsonSchema;
 
-export { type TAnnotatedTypeHandle, type TAtscriptAnnotatedType, type TAtscriptAnnotatedTypeConstructor, type TAtscriptTypeArray, type TAtscriptTypeComplex, type TAtscriptTypeDef, type TAtscriptTypeFinal, type TAtscriptTypeObject, type TMetadataMap, type TValidatorOptions, type TValidatorPlugin, type TValidatorPluginContext, Validator, ValidatorError, buildJsonSchema, defineAnnotatedType, isAnnotatedType, isAnnotatedTypeOfPrimitive };
+export { Validator, ValidatorError, annotate, buildJsonSchema, defineAnnotatedType, isAnnotatedType, isAnnotatedTypeOfPrimitive };
+export type { TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TMetadataMap, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext };

package/dist/utils.mjs

@@ -337,6 +337,15 @@ var ValidatorError = class extends Error {
 function isAnnotatedType(type) {
 	return type && type.__is_atscript_annotated_type;
 }
+function annotate(metadata, key, value, asArray) {
+	if (!metadata) return;
+	if (asArray) if (metadata.has(key)) {
+		const a = metadata.get(key);
+		if (Array.isArray(a)) a.push(value);
+else metadata.set(key, [a, value]);
+	} else metadata.set(key, [value]);
+else metadata.set(key, value);
+}
 function defineAnnotatedType(_kind, base) {
 	const kind = _kind || "";
 	const type = base?.type || {};
@@ -436,12 +445,7 @@ else if (!newBase) throw new Error(`"${typeName}" is not annotated type`);
 			return this;
 		},
 		annotate(key, value, asArray) {
-			if (asArray) if (this.$metadata.has(key)) {
-				const a = this.$metadata.get(key);
-				if (Array.isArray(a)) a.push(value);
-else this.$metadata.set(key, [a, value]);
-			} else this.$metadata.set(key, [value]);
-else this.$metadata.set(key, value);
+			annotate(this.$metadata, key, value, asArray);
 			return this;
 		}
 	};
@@ -543,4 +547,4 @@ else schema.allOf = (schema.allOf || []).concat(patterns.map((p) => ({ pattern:
 }
 
 //#endregion
-export { Validator, ValidatorError, buildJsonSchema, defineAnnotatedType, isAnnotatedType, isAnnotatedTypeOfPrimitive };
+export { Validator, ValidatorError, annotate, buildJsonSchema, defineAnnotatedType, isAnnotatedType, isAnnotatedTypeOfPrimitive };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/typescript",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Atscript: typescript-gen support.",
   "type": "module",
   "main": "dist/index.mjs",
@@ -70,7 +70,7 @@
   "homepage": "https://github.com/moostjs/atscript/tree/main/packages/typescript#readme",
   "license": "ISC",
   "peerDependencies": {
-    "@atscript/core": "^0.1.1"
+    "@atscript/core": "^0.1.2"
   },
   "dependencies": {
     "@moostjs/event-cli": "^0.5.32",