@atscript/typescript 0.1.19 → 0.1.21

package/dist/cli.cjs

@@ -334,6 +334,8 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			this.writeln(`static validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${asClass}>`);
 			if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
 			this.writeln("static toJsonSchema: () => any");
+			if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+			this.writeln("static toExampleData?: () => any");
 		}
 		this.pop();
 	}
@@ -397,6 +399,8 @@ else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = `TAtscriptTypeFina
 		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${name}>`);
 		if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
 		this.writeln("const toJsonSchema: () => any");
+		if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+		this.writeln("const toExampleData: (() => any) | undefined");
 		this.popln();
 	}
 	phantomPropType(def) {
@@ -1081,7 +1085,10 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln("/* eslint-disable */");
 		this.writeln("/* oxlint-disable */");
 		const imports = ["defineAnnotatedType as $", "annotate as $a"];
-		if (resolveJsonSchemaMode(this.opts) === "lazy") imports.push("buildJsonSchema as $$");
+		const jsonSchemaMode = resolveJsonSchemaMode(this.opts);
+		if (jsonSchemaMode === "lazy") imports.push("buildJsonSchema as $$");
+		if (this.opts?.exampleData) imports.push("createDataFromAnnotatedType as $e");
+		if (jsonSchemaMode === false) imports.push("throwFeatureDisabled as $d");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 	}
 	buildAdHocMap(annotateNodes) {
@@ -1127,6 +1134,7 @@ else {
 		this.writeln("static type = {}");
 		this.writeln("static metadata = new Map()");
 		this.renderJsonSchemaMethod(node);
+		this.renderExampleDataMethod(node);
 	}
 	renderInterface(node) {
 		this.writeln();
@@ -1182,7 +1190,14 @@ else {
 			this.writeln("}");
 		} else {
 			this.writeln("static toJsonSchema() {");
-			this.indent().writeln("throw new Error(\"JSON Schema support is disabled. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add @emit.jsonSchema annotation to individual interfaces.\")").unindent();
+			this.indent().writeln("$d(\"JSON Schema\", \"jsonSchema\", \"emit.jsonSchema\")").unindent();
+			this.writeln("}");
+		}
+	}
+	renderExampleDataMethod(_node) {
+		if (this.opts?.exampleData) {
+			this.writeln("static toExampleData() {");
+			this.indent().writeln("return $e(this, { mode: \"example\" })").unindent();
 			this.writeln("}");
 		}
 	}

package/dist/index.cjs

@@ -331,6 +331,8 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			this.writeln(`static validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${asClass}>`);
 			if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
 			this.writeln("static toJsonSchema: () => any");
+			if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+			this.writeln("static toExampleData?: () => any");
 		}
 		this.pop();
 	}
@@ -394,6 +396,8 @@ else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = `TAtscriptTypeFina
 		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${name}>`);
 		if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
 		this.writeln("const toJsonSchema: () => any");
+		if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+		this.writeln("const toExampleData: (() => any) | undefined");
 		this.popln();
 	}
 	phantomPropType(def) {
@@ -1078,7 +1082,10 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln("/* eslint-disable */");
 		this.writeln("/* oxlint-disable */");
 		const imports = ["defineAnnotatedType as $", "annotate as $a"];
-		if (resolveJsonSchemaMode(this.opts) === "lazy") imports.push("buildJsonSchema as $$");
+		const jsonSchemaMode = resolveJsonSchemaMode(this.opts);
+		if (jsonSchemaMode === "lazy") imports.push("buildJsonSchema as $$");
+		if (this.opts?.exampleData) imports.push("createDataFromAnnotatedType as $e");
+		if (jsonSchemaMode === false) imports.push("throwFeatureDisabled as $d");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 	}
 	buildAdHocMap(annotateNodes) {
@@ -1124,6 +1131,7 @@ else {
 		this.writeln("static type = {}");
 		this.writeln("static metadata = new Map()");
 		this.renderJsonSchemaMethod(node);
+		this.renderExampleDataMethod(node);
 	}
 	renderInterface(node) {
 		this.writeln();
@@ -1179,7 +1187,14 @@ else {
 			this.writeln("}");
 		} else {
 			this.writeln("static toJsonSchema() {");
-			this.indent().writeln("throw new Error(\"JSON Schema support is disabled. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add @emit.jsonSchema annotation to individual interfaces.\")").unindent();
+			this.indent().writeln("$d(\"JSON Schema\", \"jsonSchema\", \"emit.jsonSchema\")").unindent();
+			this.writeln("}");
+		}
+	}
+	renderExampleDataMethod(_node) {
+		if (this.opts?.exampleData) {
+			this.writeln("static toExampleData() {");
+			this.indent().writeln("return $e(this, { mode: \"example\" })").unindent();
 			this.writeln("}");
 		}
 	}

package/dist/index.d.ts

@@ -11,6 +11,12 @@ interface TTsPluginOptions {
      * to force build-time embedding regardless of this setting.
      */
     jsonSchema?: false | 'lazy' | 'bundle';
+    /**
+     * Example data support:
+     * - `false` — No support. `toExampleData` is not rendered. *(default)*
+     * - `true` — Import `createDataFromAnnotatedType`, create example data on each call.
+     */
+    exampleData?: boolean;
 }
 declare const tsPlugin: (opts?: TTsPluginOptions) => TAtscriptPlugin;
 

package/dist/index.mjs

@@ -307,6 +307,8 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			this.writeln(`static validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${asClass}>`);
 			if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
 			this.writeln("static toJsonSchema: () => any");
+			if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+			this.writeln("static toExampleData?: () => any");
 		}
 		this.pop();
 	}
@@ -370,6 +372,8 @@ else if (isPrimitive(realDef)) typeDef = `TAtscriptTypeFinal<${name}>`;
 		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${name}>`);
 		if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
 		this.writeln("const toJsonSchema: () => any");
+		if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+		this.writeln("const toExampleData: (() => any) | undefined");
 		this.popln();
 	}
 	phantomPropType(def) {
@@ -1054,7 +1058,10 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln("/* eslint-disable */");
 		this.writeln("/* oxlint-disable */");
 		const imports = ["defineAnnotatedType as $", "annotate as $a"];
-		if (resolveJsonSchemaMode(this.opts) === "lazy") imports.push("buildJsonSchema as $$");
+		const jsonSchemaMode = resolveJsonSchemaMode(this.opts);
+		if (jsonSchemaMode === "lazy") imports.push("buildJsonSchema as $$");
+		if (this.opts?.exampleData) imports.push("createDataFromAnnotatedType as $e");
+		if (jsonSchemaMode === false) imports.push("throwFeatureDisabled as $d");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 	}
 	buildAdHocMap(annotateNodes) {
@@ -1100,6 +1107,7 @@ else {
 		this.writeln("static type = {}");
 		this.writeln("static metadata = new Map()");
 		this.renderJsonSchemaMethod(node);
+		this.renderExampleDataMethod(node);
 	}
 	renderInterface(node) {
 		this.writeln();
@@ -1155,7 +1163,14 @@ else {
 			this.writeln("}");
 		} else {
 			this.writeln("static toJsonSchema() {");
-			this.indent().writeln("throw new Error(\"JSON Schema support is disabled. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add @emit.jsonSchema annotation to individual interfaces.\")").unindent();
+			this.indent().writeln("$d(\"JSON Schema\", \"jsonSchema\", \"emit.jsonSchema\")").unindent();
+			this.writeln("}");
+		}
+	}
+	renderExampleDataMethod(_node) {
+		if (this.opts?.exampleData) {
+			this.writeln("static toExampleData() {");
+			this.indent().writeln("return $e(this, { mode: \"example\" })").unindent();
 			this.writeln("}");
 		}
 	}

package/dist/utils.cjs

@@ -553,7 +553,7 @@ function isAnnotatedTypeOfPrimitive(t) {
 //#endregion
 //#region packages/typescript/src/json-schema.ts
 function buildJsonSchema(type) {
-	const build = (def) => {
+	const build$1 = (def) => {
 		const meta = def.metadata;
 		return forAnnotatedType(def, {
 			phantom() {
@@ -564,7 +564,7 @@ function buildJsonSchema(type) {
 				const required = [];
 				for (const [key, val] of d.type.props.entries()) {
 					if (isPhantomType(val)) continue;
-					properties[key] = build(val);
+					properties[key] = build$1(val);
 					if (!val.optional) required.push(key);
 				}
 				const schema = {
@@ -577,7 +577,7 @@ function buildJsonSchema(type) {
 			array(d) {
 				const schema = {
 					type: "array",
-					items: build(d.type.of)
+					items: build$1(d.type.of)
 				};
 				const minLength = meta.get("expect.minLength");
 				if (minLength) schema.minItems = typeof minLength === "number" ? minLength : minLength.length;
@@ -586,15 +586,15 @@ function buildJsonSchema(type) {
 				return schema;
 			},
 			union(d) {
-				return { anyOf: d.type.items.map(build) };
+				return { anyOf: d.type.items.map(build$1) };
 			},
 			intersection(d) {
-				return { allOf: d.type.items.map(build) };
+				return { allOf: d.type.items.map(build$1) };
 			},
 			tuple(d) {
 				return {
 					type: "array",
-					items: d.type.items.map(build),
+					items: d.type.items.map(build$1),
 					additionalItems: false
 				};
 			},
@@ -625,7 +625,7 @@ else schema.allOf = (schema.allOf || []).concat(patterns.map((p) => ({ pattern:
 			}
 		});
 	};
-	return build(type);
+	return build$1(type);
 }
 function fromJsonSchema(schema) {
 	const convert = (s) => {
@@ -719,6 +719,92 @@ function fromJsonSchema(schema) {
 	return convert(schema);
 }
 
+//#endregion
+//#region packages/typescript/src/default-value.ts
+/**
+* Attempts to resolve a value from the mode for the given annotated type.
+* Returns `undefined` when no value is available (or parse/validation fails).
+*/ function resolveValue(prop, path, mode) {
+	if (!mode || mode === "empty") return undefined;
+	let raw;
+	if (typeof mode === "function") {
+		raw = mode(prop, path);
+		if (raw === undefined) return undefined;
+		if (prop.validator({ unknownProps: "ignore" }).validate(raw, true)) return { value: raw };
+		return undefined;
+	}
+	const metaKey = mode === "default" ? "meta.default" : "meta.example";
+	const rawStr = prop.metadata.get(metaKey);
+	if (rawStr === undefined) return undefined;
+	const parsed = parseRawValue(rawStr, prop);
+	if (parsed === undefined) return undefined;
+	if (prop.validator({ unknownProps: "ignore" }).validate(parsed, true)) return { value: parsed };
+	return undefined;
+}
+/**
+* Parses a raw annotation string into a JS value.
+* Strings are returned as-is for string types; everything else goes through JSON.parse.
+*/ function parseRawValue(raw, prop) {
+	if (prop.type.kind === "" && prop.type.designType === "string") return raw;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+}
+/** Returns the structural default for a final (primitive/literal) type. */ function finalDefault(def) {
+	if (def.type.value !== undefined) return def.type.value;
+	switch (def.type.designType) {
+		case "string": return "";
+		case "number": return 0;
+		case "boolean": return false;
+		case "undefined": return undefined;
+		case "null": return null;
+		default: return undefined;
+	}
+}
+function createDataFromAnnotatedType(type, opts) {
+	return build(type, "", opts?.mode);
+}
+function build(def, path, mode) {
+	const resolved = resolveValue(def, path, mode);
+	if (resolved !== undefined) return resolved.value;
+	return forAnnotatedType(def, {
+		phantom: () => undefined,
+		final: (d) => finalDefault(d),
+		object: (d) => {
+			const data = {};
+			for (const [key, prop] of d.type.props.entries()) {
+				if (isPhantomType(prop)) continue;
+				const childPath = path ? `${path}.${key}` : key;
+				if (prop.optional) {
+					const childResolved = resolveValue(prop, childPath, mode);
+					if (childResolved !== undefined) data[key] = childResolved.value;
+					continue;
+				}
+				data[key] = build(prop, childPath, mode);
+			}
+			return data;
+		},
+		array: () => [],
+		tuple: (d) => d.type.items.map((item, i) => build(item, `${path}.${i}`, mode)),
+		union: (d) => {
+			const first = d.type.items[0];
+			return first ? build(first, path, mode) : undefined;
+		},
+		intersection: (d) => {
+			const first = d.type.items[0];
+			return first ? build(first, path, mode) : undefined;
+		}
+	});
+}
+
+//#endregion
+//#region packages/typescript/src/throw-disabled.ts
+function throwFeatureDisabled(feature, option, annotation) {
+	throw new Error(`${feature} support is disabled. To enable, set \`${option}: 'lazy'\` or \`${option}: 'bundle'\` in tsPlugin options, or add @${annotation} annotation to individual interfaces.`);
+}
+
 //#endregion
 //#region packages/typescript/src/flatten.ts
 function flattenAnnotatedType(type, options) {
@@ -969,6 +1055,7 @@ exports.Validator = Validator
 exports.ValidatorError = ValidatorError
 exports.annotate = annotate
 exports.buildJsonSchema = buildJsonSchema
+exports.createDataFromAnnotatedType = createDataFromAnnotatedType
 exports.defineAnnotatedType = defineAnnotatedType
 exports.deserializeAnnotatedType = deserializeAnnotatedType
 exports.flattenAnnotatedType = flattenAnnotatedType
@@ -977,4 +1064,5 @@ exports.fromJsonSchema = fromJsonSchema
 exports.isAnnotatedType = isAnnotatedType
 exports.isAnnotatedTypeOfPrimitive = isAnnotatedTypeOfPrimitive
 exports.isPhantomType = isPhantomType
-exports.serializeAnnotatedType = serializeAnnotatedType
+exports.serializeAnnotatedType = serializeAnnotatedType
+exports.throwFeatureDisabled = throwFeatureDisabled

package/dist/utils.d.ts

@@ -305,6 +305,49 @@ declare function forAnnotatedType<R>(def: TAtscriptAnnotatedType, handlers: {
     phantom?: (def: TAtscriptAnnotatedType<TAtscriptTypeFinal>) => R;
 }): R;
 
+/**
+ * Custom resolver function for computing field values.
+ * Return `undefined` to fall through to structural defaults.
+ */
+type TValueResolver = (prop: TAtscriptAnnotatedType, path: string) => unknown | undefined;
+/** Options for {@link createDataFromAnnotatedType}. */
+interface TCreateDataOptions {
+    /**
+     * How to resolve values:
+     * - `'empty'` — structural defaults only (`''`, `0`, `false`, `[]`, `{}`); optional props skipped
+     * - `'default'` — use `@meta.default` annotations; optional props skipped unless annotated
+     * - `'example'` — use `@meta.example` annotations; optional props skipped unless annotated
+     * - `function` — custom resolver per field; optional props skipped unless resolver returns a value
+     *
+     * @default 'empty'
+     */
+    mode?: 'empty' | 'default' | 'example' | TValueResolver;
+}
+/**
+ * Creates a data object from an ATScript annotated type definition.
+ *
+ * Supports four modes:
+ * - `'empty'` — structural defaults only; optional props omitted
+ * - `'default'` — uses `@meta.default` annotations; optional props omitted unless annotated
+ * - `'example'` — uses `@meta.example` annotations; optional props omitted unless annotated
+ * - `function` — custom resolver; optional props omitted unless resolver returns a value
+ *
+ * When a `@meta.default` / `@meta.example` value is set on a complex type (object, array)
+ * and passes full validation, the entire subtree is replaced — no recursion into inner props.
+ * If validation fails, the annotation is ignored and structural defaults are built from inner props.
+ *
+ * @param type - The ATScript annotated type to create data from.
+ * @param opts - Options controlling value resolution mode.
+ * @returns A value conforming to the type's shape.
+ */
+declare function createDataFromAnnotatedType(type: TAtscriptAnnotatedType, opts?: TCreateDataOptions): unknown;
+
+/**
+ * Throws a runtime error indicating that a feature is disabled.
+ * Used by generated JS files to avoid duplicating the error message string.
+ */
+declare function throwFeatureDisabled(feature: string, option: string, annotation: string): never;
+
 /**
  * Options for controlling the flattening process.
  */
@@ -452,5 +495,5 @@ declare function serializeAnnotatedType(type: TAtscriptAnnotatedType, options?:
  */
 declare function deserializeAnnotatedType(data: TSerializedAnnotatedType): TAtscriptAnnotatedType;
 
-export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType };
-export type { InferDataType, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TFlattenOptions, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext };
+export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType, throwFeatureDisabled };
+export type { InferDataType, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TCreateDataOptions, TFlattenOptions, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext, TValueResolver };

package/dist/utils.mjs

@@ -552,7 +552,7 @@ function isAnnotatedTypeOfPrimitive(t) {
 //#endregion
 //#region packages/typescript/src/json-schema.ts
 function buildJsonSchema(type) {
-	const build = (def) => {
+	const build$1 = (def) => {
 		const meta = def.metadata;
 		return forAnnotatedType(def, {
 			phantom() {
@@ -563,7 +563,7 @@ function buildJsonSchema(type) {
 				const required = [];
 				for (const [key, val] of d.type.props.entries()) {
 					if (isPhantomType(val)) continue;
-					properties[key] = build(val);
+					properties[key] = build$1(val);
 					if (!val.optional) required.push(key);
 				}
 				const schema = {
@@ -576,7 +576,7 @@ function buildJsonSchema(type) {
 			array(d) {
 				const schema = {
 					type: "array",
-					items: build(d.type.of)
+					items: build$1(d.type.of)
 				};
 				const minLength = meta.get("expect.minLength");
 				if (minLength) schema.minItems = typeof minLength === "number" ? minLength : minLength.length;
@@ -585,15 +585,15 @@ function buildJsonSchema(type) {
 				return schema;
 			},
 			union(d) {
-				return { anyOf: d.type.items.map(build) };
+				return { anyOf: d.type.items.map(build$1) };
 			},
 			intersection(d) {
-				return { allOf: d.type.items.map(build) };
+				return { allOf: d.type.items.map(build$1) };
 			},
 			tuple(d) {
 				return {
 					type: "array",
-					items: d.type.items.map(build),
+					items: d.type.items.map(build$1),
 					additionalItems: false
 				};
 			},
@@ -624,7 +624,7 @@ else schema.allOf = (schema.allOf || []).concat(patterns.map((p) => ({ pattern:
 			}
 		});
 	};
-	return build(type);
+	return build$1(type);
 }
 function fromJsonSchema(schema) {
 	const convert = (s) => {
@@ -718,6 +718,92 @@ function fromJsonSchema(schema) {
 	return convert(schema);
 }
 
+//#endregion
+//#region packages/typescript/src/default-value.ts
+/**
+* Attempts to resolve a value from the mode for the given annotated type.
+* Returns `undefined` when no value is available (or parse/validation fails).
+*/ function resolveValue(prop, path, mode) {
+	if (!mode || mode === "empty") return undefined;
+	let raw;
+	if (typeof mode === "function") {
+		raw = mode(prop, path);
+		if (raw === undefined) return undefined;
+		if (prop.validator({ unknownProps: "ignore" }).validate(raw, true)) return { value: raw };
+		return undefined;
+	}
+	const metaKey = mode === "default" ? "meta.default" : "meta.example";
+	const rawStr = prop.metadata.get(metaKey);
+	if (rawStr === undefined) return undefined;
+	const parsed = parseRawValue(rawStr, prop);
+	if (parsed === undefined) return undefined;
+	if (prop.validator({ unknownProps: "ignore" }).validate(parsed, true)) return { value: parsed };
+	return undefined;
+}
+/**
+* Parses a raw annotation string into a JS value.
+* Strings are returned as-is for string types; everything else goes through JSON.parse.
+*/ function parseRawValue(raw, prop) {
+	if (prop.type.kind === "" && prop.type.designType === "string") return raw;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+}
+/** Returns the structural default for a final (primitive/literal) type. */ function finalDefault(def) {
+	if (def.type.value !== undefined) return def.type.value;
+	switch (def.type.designType) {
+		case "string": return "";
+		case "number": return 0;
+		case "boolean": return false;
+		case "undefined": return undefined;
+		case "null": return null;
+		default: return undefined;
+	}
+}
+function createDataFromAnnotatedType(type, opts) {
+	return build(type, "", opts?.mode);
+}
+function build(def, path, mode) {
+	const resolved = resolveValue(def, path, mode);
+	if (resolved !== undefined) return resolved.value;
+	return forAnnotatedType(def, {
+		phantom: () => undefined,
+		final: (d) => finalDefault(d),
+		object: (d) => {
+			const data = {};
+			for (const [key, prop] of d.type.props.entries()) {
+				if (isPhantomType(prop)) continue;
+				const childPath = path ? `${path}.${key}` : key;
+				if (prop.optional) {
+					const childResolved = resolveValue(prop, childPath, mode);
+					if (childResolved !== undefined) data[key] = childResolved.value;
+					continue;
+				}
+				data[key] = build(prop, childPath, mode);
+			}
+			return data;
+		},
+		array: () => [],
+		tuple: (d) => d.type.items.map((item, i) => build(item, `${path}.${i}`, mode)),
+		union: (d) => {
+			const first = d.type.items[0];
+			return first ? build(first, path, mode) : undefined;
+		},
+		intersection: (d) => {
+			const first = d.type.items[0];
+			return first ? build(first, path, mode) : undefined;
+		}
+	});
+}
+
+//#endregion
+//#region packages/typescript/src/throw-disabled.ts
+function throwFeatureDisabled(feature, option, annotation) {
+	throw new Error(`${feature} support is disabled. To enable, set \`${option}: 'lazy'\` or \`${option}: 'bundle'\` in tsPlugin options, or add @${annotation} annotation to individual interfaces.`);
+}
+
 //#endregion
 //#region packages/typescript/src/flatten.ts
 function flattenAnnotatedType(type, options) {
@@ -963,4 +1049,4 @@ function deserializeTypeDef(t) {
 }
 
 //#endregion
-export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType };
+export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType, throwFeatureDisabled };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/typescript",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Atscript: typescript-gen support.",
   "keywords": [
     "annotations",
@@ -19,11 +19,14 @@
     "directory": "packages/typescript"
   },
   "bin": {
-    "asc": "./cli.cjs"
+    "asc": "./cli.cjs",
+    "setup-skills": "./scripts/setup-skills.js"
   },
   "files": [
     "dist",
-    "cli.cjs"
+    "cli.cjs",
+    "skills",
+    "scripts/setup-skills.js"
   ],
   "type": "module",
   "main": "dist/index.mjs",
@@ -61,7 +64,7 @@
     "vitest": "3.2.4"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.19"
+    "@atscript/core": "^0.1.21"
   },
   "build": [
     {},
@@ -81,6 +84,7 @@
   ],
   "scripts": {
     "pub": "pnpm publish --access public",
-    "test": "vitest"
+    "test": "vitest",
+    "setup-skills": "node ./scripts/setup-skills.js"
   }
 }

package/scripts/setup-skills.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/* prettier-ignore */
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const SKILL_NAME = 'atscript-typescript'
+const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
+
+if (!fs.existsSync(SKILL_SRC)) {
+  console.error(`No skills found at ${SKILL_SRC}`)
+  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
+  process.exit(1)
+}
+
+const AGENTS = {
+  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
+  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
+  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
+  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
+  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
+}
+
+const args = process.argv.slice(2)
+const isGlobal = args.includes('--global') || args.includes('-g')
+const isPostinstall = args.includes('--postinstall')
+let installed = 0, skipped = 0
+const installedDirs = []
+
+for (const [agentName, cfg] of Object.entries(AGENTS)) {
+  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
+  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
+
+  // In postinstall mode: silently skip agents that aren't set up globally
+  if (isPostinstall || isGlobal) {
+    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
+  }
+
+  const dest = path.join(targetBase, SKILL_NAME)
+  try {
+    fs.mkdirSync(dest, { recursive: true })
+    fs.cpSync(SKILL_SRC, dest, { recursive: true })
+    console.log(`✅  ${agentName}: installed to ${dest}`)
+    installed++
+    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
+  } catch (err) {
+    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
+  }
+}
+
+// Add locally-installed skill dirs to .gitignore
+if (!isGlobal && installedDirs.length > 0) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore')
+  let gitignoreContent = ''
+  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
+  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
+  if (linesToAdd.length > 0) {
+    const hasHeader = gitignoreContent.includes('# AI agent skills')
+    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
+      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
+      + linesToAdd.join('\n') + '\n'
+    fs.appendFileSync(gitignorePath, block)
+    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
+  }
+}
+
+if (installed === 0 && isPostinstall) {
+  // Silence is fine — no agents present, nothing to do
+} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
+  console.log('No agent directories detected. Try --global or run without it for project-local install.')
+} else if (installed === 0) {
+  console.log('Nothing installed. Run without --global to install project-locally.')
+} else {
+  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
+}