@formspec/build 0.1.0-alpha.44 → 0.1.0-alpha.46

package/dist/build-alpha.d.ts

@@ -317,7 +317,7 @@ declare interface ControlOptionConstraints {
  *
  * @public
  */
-export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): ExtensionRegistry;
+export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): MutableExtensionRegistry;
 
 /**
  * Creates a supported static build context for a source file.
@@ -436,8 +436,33 @@ declare interface CustomTypeRegistration_2 {
     /**
      * Optional TypeScript surface names that should resolve to this custom type
      * during TSDoc/class analysis. Defaults to `typeName` when omitted.
+     * @deprecated Prefer `brand` for structural detection or type parameters
+     * on `defineCustomType<T>()` for symbol-based detection. String name
+     * matching will be removed in a future major version.
      */
     readonly tsTypeNames?: readonly string[];
+    /**
+     * Optional brand identifier for structural type detection.
+     *
+     * When provided, the type resolver checks `type.getProperties()` for a
+     * computed property whose name matches this identifier. This is more
+     * reliable than `tsTypeNames` for aliased branded types because it does not
+     * depend on the local type name.
+     *
+     * Brand detection is attempted after name-based resolution (`tsTypeNames`)
+     * as a structural fallback. If both match, name-based resolution wins.
+     *
+     * The value should match the identifier text of a `unique symbol` declaration
+     * used as a computed property key on the branded type. For example, if the
+     * type is `string & { readonly [__decimalBrand]: true }`, the brand is
+     * `"__decimalBrand"`.
+     *
+     * Brand identifiers are stored as plain strings in the extension registry, so
+     * they must be unique across the extensions loaded into the same build.
+     *
+     * Note: `"__integerBrand"` is reserved for the builtin Integer type.
+     */
+    readonly brand?: string;
     /**
      * Converts the custom type's payload into a JSON Schema fragment.
      *
@@ -716,10 +741,32 @@ export declare interface ExtensionRegistry {
      * This is used during TSDoc/class analysis to resolve extension-defined
      * custom types from source-level declarations.
      */
-    findTypeByName(typeName: string): {
-        readonly extensionId: string;
-        readonly registration: CustomTypeRegistration;
-    } | undefined;
+    findTypeByName(typeName: string): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type registration by a brand identifier.
+     *
+     * This is used during class analysis to resolve extension-defined custom types
+     * via structural brand detection (`unique symbol` computed property keys).
+     * Brand identifiers are stored as plain strings, so they must be unique
+     * across all extensions loaded into the registry.
+     *
+     * @param brand - The identifier text of the `unique symbol` brand variable.
+     */
+    findTypeByBrand(brand: string): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type by its TypeScript symbol identity.
+     *
+     * Built from `defineCustomType<T>()` type parameter extraction in the config file.
+     * This is the most precise detection path — it uses `ts.Symbol` identity, which is
+     * immune to import aliases and name collisions.
+     *
+     * Returns `undefined` until {@link MutableExtensionRegistry.setSymbolMap} has been
+     * called (i.e., before the TypeScript program is available), or when the symbol is
+     * not registered via a type parameter.
+     *
+     * @param symbol - The canonical TypeScript symbol to look up.
+     */
+    findTypeBySymbol(symbol: ts.Symbol): ExtensionTypeLookupResult | undefined;
     /**
      * Look up a custom constraint registration by its fully-qualified constraint ID.
      *
@@ -757,6 +804,22 @@ export declare interface ExtensionRegistry {
  */
 declare type ExtensionTypeKind = "primitive" | "enum" | "array" | "object" | "record" | "union" | "reference" | "dynamic" | "custom";
 
+/**
+ * The result of a successful extension type lookup.
+ *
+ * Returned by {@link ExtensionRegistry.findTypeByName},
+ * {@link ExtensionRegistry.findTypeByBrand}, and
+ * {@link ExtensionRegistry.findTypeBySymbol}.
+ *
+ * @public
+ */
+export declare interface ExtensionTypeLookupResult {
+    /** The fully-qualified extension ID (e.g., "x-stripe/monetary"). */
+    readonly extensionId: string;
+    /** The custom type registration matched by this lookup. */
+    readonly registration: CustomTypeRegistration;
+}
+
 /**
  * Field configuration option constraints - control which field options are allowed.
  *
@@ -1846,6 +1909,28 @@ export declare interface MixedAuthoringSchemas {
     readonly uiSchema: UISchema;
 }
 
+/**
+ * Mutable extension registry used internally by the build pipeline.
+ *
+ * Extends {@link ExtensionRegistry} with `setSymbolMap`, which must be called
+ * after the TypeScript program is created. Consumer code should accept only
+ * the read-only {@link ExtensionRegistry} interface.
+ *
+ * @public
+ */
+export declare interface MutableExtensionRegistry extends ExtensionRegistry {
+    /**
+     * Sets the symbol map built from config AST analysis.
+     *
+     * Called after the TypeScript program is created and the config file is analyzed.
+     * Prior to this call, {@link ExtensionRegistry.findTypeBySymbol} always returns
+     * `undefined`.
+     *
+     * @param map - A map from canonical `ts.Symbol` to the matching registry entry.
+     */
+    setSymbolMap(map: Map<ts.Symbol, ExtensionTypeLookupResult>): void;
+}
+
 export { NumberField }
 
 export { ObjectField }
@@ -2080,6 +2165,22 @@ export declare interface StaticSchemaGenerationOptions {
     readonly metadata?: MetadataPolicyInput | undefined;
     /** Discriminator-specific schema generation behavior. */
     readonly discriminator?: DiscriminatorResolutionOptions | undefined;
+    /**
+     * Absolute path to the FormSpec config file (e.g., `formspec.config.ts`).
+     *
+     * When provided alongside a `config` that includes extensions, the build
+     * pipeline includes the config file in the TypeScript program and extracts
+     * `defineCustomType<T>()` type parameters. This enables symbol-based custom
+     * type detection — the most precise resolution path, immune to import aliases
+     * and name collisions.
+     *
+     * Obtain this from `loadFormSpecConfig()`:
+     * ```typescript
+     * const { config, configPath } = await loadFormSpecConfig();
+     * await generateSchemas({ filePath, typeName, config, configPath, errorReporting: "throw" });
+     * ```
+     */
+    readonly configPath?: string | undefined;
 }
 
 export { TextField }

package/dist/build-beta.d.ts

@@ -317,7 +317,7 @@ declare interface ControlOptionConstraints {
  *
  * @public
  */
-export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): ExtensionRegistry;
+export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): MutableExtensionRegistry;
 
 /**
  * Creates a supported static build context for a source file.
@@ -436,8 +436,33 @@ declare interface CustomTypeRegistration_2 {
     /**
      * Optional TypeScript surface names that should resolve to this custom type
      * during TSDoc/class analysis. Defaults to `typeName` when omitted.
+     * @deprecated Prefer `brand` for structural detection or type parameters
+     * on `defineCustomType<T>()` for symbol-based detection. String name
+     * matching will be removed in a future major version.
      */
     readonly tsTypeNames?: readonly string[];
+    /**
+     * Optional brand identifier for structural type detection.
+     *
+     * When provided, the type resolver checks `type.getProperties()` for a
+     * computed property whose name matches this identifier. This is more
+     * reliable than `tsTypeNames` for aliased branded types because it does not
+     * depend on the local type name.
+     *
+     * Brand detection is attempted after name-based resolution (`tsTypeNames`)
+     * as a structural fallback. If both match, name-based resolution wins.
+     *
+     * The value should match the identifier text of a `unique symbol` declaration
+     * used as a computed property key on the branded type. For example, if the
+     * type is `string & { readonly [__decimalBrand]: true }`, the brand is
+     * `"__decimalBrand"`.
+     *
+     * Brand identifiers are stored as plain strings in the extension registry, so
+     * they must be unique across the extensions loaded into the same build.
+     *
+     * Note: `"__integerBrand"` is reserved for the builtin Integer type.
+     */
+    readonly brand?: string;
     /**
      * Converts the custom type's payload into a JSON Schema fragment.
      *
@@ -716,10 +741,32 @@ export declare interface ExtensionRegistry {
      * This is used during TSDoc/class analysis to resolve extension-defined
      * custom types from source-level declarations.
      */
-    findTypeByName(typeName: string): {
-        readonly extensionId: string;
-        readonly registration: CustomTypeRegistration;
-    } | undefined;
+    findTypeByName(typeName: string): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type registration by a brand identifier.
+     *
+     * This is used during class analysis to resolve extension-defined custom types
+     * via structural brand detection (`unique symbol` computed property keys).
+     * Brand identifiers are stored as plain strings, so they must be unique
+     * across all extensions loaded into the registry.
+     *
+     * @param brand - The identifier text of the `unique symbol` brand variable.
+     */
+    findTypeByBrand(brand: string): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type by its TypeScript symbol identity.
+     *
+     * Built from `defineCustomType<T>()` type parameter extraction in the config file.
+     * This is the most precise detection path — it uses `ts.Symbol` identity, which is
+     * immune to import aliases and name collisions.
+     *
+     * Returns `undefined` until {@link MutableExtensionRegistry.setSymbolMap} has been
+     * called (i.e., before the TypeScript program is available), or when the symbol is
+     * not registered via a type parameter.
+     *
+     * @param symbol - The canonical TypeScript symbol to look up.
+     */
+    findTypeBySymbol(symbol: ts.Symbol): ExtensionTypeLookupResult | undefined;
     /**
      * Look up a custom constraint registration by its fully-qualified constraint ID.
      *
@@ -757,6 +804,22 @@ export declare interface ExtensionRegistry {
  */
 declare type ExtensionTypeKind = "primitive" | "enum" | "array" | "object" | "record" | "union" | "reference" | "dynamic" | "custom";
 
+/**
+ * The result of a successful extension type lookup.
+ *
+ * Returned by {@link ExtensionRegistry.findTypeByName},
+ * {@link ExtensionRegistry.findTypeByBrand}, and
+ * {@link ExtensionRegistry.findTypeBySymbol}.
+ *
+ * @public
+ */
+export declare interface ExtensionTypeLookupResult {
+    /** The fully-qualified extension ID (e.g., "x-stripe/monetary"). */
+    readonly extensionId: string;
+    /** The custom type registration matched by this lookup. */
+    readonly registration: CustomTypeRegistration;
+}
+
 /**
  * Field configuration option constraints - control which field options are allowed.
  *
@@ -1846,6 +1909,28 @@ export declare interface MixedAuthoringSchemas {
     readonly uiSchema: UISchema;
 }
 
+/**
+ * Mutable extension registry used internally by the build pipeline.
+ *
+ * Extends {@link ExtensionRegistry} with `setSymbolMap`, which must be called
+ * after the TypeScript program is created. Consumer code should accept only
+ * the read-only {@link ExtensionRegistry} interface.
+ *
+ * @public
+ */
+export declare interface MutableExtensionRegistry extends ExtensionRegistry {
+    /**
+     * Sets the symbol map built from config AST analysis.
+     *
+     * Called after the TypeScript program is created and the config file is analyzed.
+     * Prior to this call, {@link ExtensionRegistry.findTypeBySymbol} always returns
+     * `undefined`.
+     *
+     * @param map - A map from canonical `ts.Symbol` to the matching registry entry.
+     */
+    setSymbolMap(map: Map<ts.Symbol, ExtensionTypeLookupResult>): void;
+}
+
 export { NumberField }
 
 export { ObjectField }
@@ -2080,6 +2165,22 @@ export declare interface StaticSchemaGenerationOptions {
     readonly metadata?: MetadataPolicyInput | undefined;
     /** Discriminator-specific schema generation behavior. */
     readonly discriminator?: DiscriminatorResolutionOptions | undefined;
+    /**
+     * Absolute path to the FormSpec config file (e.g., `formspec.config.ts`).
+     *
+     * When provided alongside a `config` that includes extensions, the build
+     * pipeline includes the config file in the TypeScript program and extracts
+     * `defineCustomType<T>()` type parameters. This enables symbol-based custom
+     * type detection — the most precise resolution path, immune to import aliases
+     * and name collisions.
+     *
+     * Obtain this from `loadFormSpecConfig()`:
+     * ```typescript
+     * const { config, configPath } = await loadFormSpecConfig();
+     * await generateSchemas({ filePath, typeName, config, configPath, errorReporting: "throw" });
+     * ```
+     */
+    readonly configPath?: string | undefined;
 }
 
 export { TextField }

package/dist/build-internal.d.ts

@@ -317,7 +317,7 @@ declare interface ControlOptionConstraints {
  *
  * @public
  */
-export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): ExtensionRegistry;
+export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): MutableExtensionRegistry;
 
 /**
  * Creates a supported static build context for a source file.
@@ -436,8 +436,33 @@ declare interface CustomTypeRegistration_2 {
     /**
      * Optional TypeScript surface names that should resolve to this custom type
      * during TSDoc/class analysis. Defaults to `typeName` when omitted.
+     * @deprecated Prefer `brand` for structural detection or type parameters
+     * on `defineCustomType<T>()` for symbol-based detection. String name
+     * matching will be removed in a future major version.
      */
     readonly tsTypeNames?: readonly string[];
+    /**
+     * Optional brand identifier for structural type detection.
+     *
+     * When provided, the type resolver checks `type.getProperties()` for a
+     * computed property whose name matches this identifier. This is more
+     * reliable than `tsTypeNames` for aliased branded types because it does not
+     * depend on the local type name.
+     *
+     * Brand detection is attempted after name-based resolution (`tsTypeNames`)
+     * as a structural fallback. If both match, name-based resolution wins.
+     *
+     * The value should match the identifier text of a `unique symbol` declaration
+     * used as a computed property key on the branded type. For example, if the
+     * type is `string & { readonly [__decimalBrand]: true }`, the brand is
+     * `"__decimalBrand"`.
+     *
+     * Brand identifiers are stored as plain strings in the extension registry, so
+     * they must be unique across the extensions loaded into the same build.
+     *
+     * Note: `"__integerBrand"` is reserved for the builtin Integer type.
+     */
+    readonly brand?: string;
     /**
      * Converts the custom type's payload into a JSON Schema fragment.
      *
@@ -716,10 +741,32 @@ export declare interface ExtensionRegistry {
      * This is used during TSDoc/class analysis to resolve extension-defined
      * custom types from source-level declarations.
      */
-    findTypeByName(typeName: string): {
-        readonly extensionId: string;
-        readonly registration: CustomTypeRegistration;
-    } | undefined;
+    findTypeByName(typeName: string): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type registration by a brand identifier.
+     *
+     * This is used during class analysis to resolve extension-defined custom types
+     * via structural brand detection (`unique symbol` computed property keys).
+     * Brand identifiers are stored as plain strings, so they must be unique
+     * across all extensions loaded into the registry.
+     *
+     * @param brand - The identifier text of the `unique symbol` brand variable.
+     */
+    findTypeByBrand(brand: string): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type by its TypeScript symbol identity.
+     *
+     * Built from `defineCustomType<T>()` type parameter extraction in the config file.
+     * This is the most precise detection path — it uses `ts.Symbol` identity, which is
+     * immune to import aliases and name collisions.
+     *
+     * Returns `undefined` until {@link MutableExtensionRegistry.setSymbolMap} has been
+     * called (i.e., before the TypeScript program is available), or when the symbol is
+     * not registered via a type parameter.
+     *
+     * @param symbol - The canonical TypeScript symbol to look up.
+     */
+    findTypeBySymbol(symbol: ts.Symbol): ExtensionTypeLookupResult | undefined;
     /**
      * Look up a custom constraint registration by its fully-qualified constraint ID.
      *
@@ -757,6 +804,22 @@ export declare interface ExtensionRegistry {
  */
 declare type ExtensionTypeKind = "primitive" | "enum" | "array" | "object" | "record" | "union" | "reference" | "dynamic" | "custom";
 
+/**
+ * The result of a successful extension type lookup.
+ *
+ * Returned by {@link ExtensionRegistry.findTypeByName},
+ * {@link ExtensionRegistry.findTypeByBrand}, and
+ * {@link ExtensionRegistry.findTypeBySymbol}.
+ *
+ * @public
+ */
+export declare interface ExtensionTypeLookupResult {
+    /** The fully-qualified extension ID (e.g., "x-stripe/monetary"). */
+    readonly extensionId: string;
+    /** The custom type registration matched by this lookup. */
+    readonly registration: CustomTypeRegistration;
+}
+
 /**
  * Field configuration option constraints - control which field options are allowed.
  *
@@ -1846,6 +1909,28 @@ export declare interface MixedAuthoringSchemas {
     readonly uiSchema: UISchema;
 }
 
+/**
+ * Mutable extension registry used internally by the build pipeline.
+ *
+ * Extends {@link ExtensionRegistry} with `setSymbolMap`, which must be called
+ * after the TypeScript program is created. Consumer code should accept only
+ * the read-only {@link ExtensionRegistry} interface.
+ *
+ * @public
+ */
+export declare interface MutableExtensionRegistry extends ExtensionRegistry {
+    /**
+     * Sets the symbol map built from config AST analysis.
+     *
+     * Called after the TypeScript program is created and the config file is analyzed.
+     * Prior to this call, {@link ExtensionRegistry.findTypeBySymbol} always returns
+     * `undefined`.
+     *
+     * @param map - A map from canonical `ts.Symbol` to the matching registry entry.
+     */
+    setSymbolMap(map: Map<ts.Symbol, ExtensionTypeLookupResult>): void;
+}
+
 export { NumberField }
 
 export { ObjectField }
@@ -2080,6 +2165,22 @@ export declare interface StaticSchemaGenerationOptions {
     readonly metadata?: MetadataPolicyInput | undefined;
     /** Discriminator-specific schema generation behavior. */
     readonly discriminator?: DiscriminatorResolutionOptions | undefined;
+    /**
+     * Absolute path to the FormSpec config file (e.g., `formspec.config.ts`).
+     *
+     * When provided alongside a `config` that includes extensions, the build
+     * pipeline includes the config file in the TypeScript program and extracts
+     * `defineCustomType<T>()` type parameters. This enables symbol-based custom
+     * type detection — the most precise resolution path, immune to import aliases
+     * and name collisions.
+     *
+     * Obtain this from `loadFormSpecConfig()`:
+     * ```typescript
+     * const { config, configPath } = await loadFormSpecConfig();
+     * await generateSchemas({ filePath, typeName, config, configPath, errorReporting: "throw" });
+     * ```
+     */
+    readonly configPath?: string | undefined;
 }
 
 export { TextField }

package/dist/build.d.ts

@@ -317,7 +317,7 @@ declare interface ControlOptionConstraints {
  *
  * @public
  */
-export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): ExtensionRegistry;
+export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): MutableExtensionRegistry;
 
 /**
  * Creates a supported static build context for a source file.
@@ -436,8 +436,33 @@ declare interface CustomTypeRegistration_2 {
     /**
      * Optional TypeScript surface names that should resolve to this custom type
      * during TSDoc/class analysis. Defaults to `typeName` when omitted.
+     * @deprecated Prefer `brand` for structural detection or type parameters
+     * on `defineCustomType<T>()` for symbol-based detection. String name
+     * matching will be removed in a future major version.
      */
     readonly tsTypeNames?: readonly string[];
+    /**
+     * Optional brand identifier for structural type detection.
+     *
+     * When provided, the type resolver checks `type.getProperties()` for a
+     * computed property whose name matches this identifier. This is more
+     * reliable than `tsTypeNames` for aliased branded types because it does not
+     * depend on the local type name.
+     *
+     * Brand detection is attempted after name-based resolution (`tsTypeNames`)
+     * as a structural fallback. If both match, name-based resolution wins.
+     *
+     * The value should match the identifier text of a `unique symbol` declaration
+     * used as a computed property key on the branded type. For example, if the
+     * type is `string & { readonly [__decimalBrand]: true }`, the brand is
+     * `"__decimalBrand"`.
+     *
+     * Brand identifiers are stored as plain strings in the extension registry, so
+     * they must be unique across the extensions loaded into the same build.
+     *
+     * Note: `"__integerBrand"` is reserved for the builtin Integer type.
+     */
+    readonly brand?: string;
     /**
      * Converts the custom type's payload into a JSON Schema fragment.
      *
@@ -716,10 +741,32 @@ export declare interface ExtensionRegistry {
      * This is used during TSDoc/class analysis to resolve extension-defined
      * custom types from source-level declarations.
      */
-    findTypeByName(typeName: string): {
-        readonly extensionId: string;
-        readonly registration: CustomTypeRegistration;
-    } | undefined;
+    findTypeByName(typeName: string): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type registration by a brand identifier.
+     *
+     * This is used during class analysis to resolve extension-defined custom types
+     * via structural brand detection (`unique symbol` computed property keys).
+     * Brand identifiers are stored as plain strings, so they must be unique
+     * across all extensions loaded into the registry.
+     *
+     * @param brand - The identifier text of the `unique symbol` brand variable.
+     */
+    findTypeByBrand(brand: string): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type by its TypeScript symbol identity.
+     *
+     * Built from `defineCustomType<T>()` type parameter extraction in the config file.
+     * This is the most precise detection path — it uses `ts.Symbol` identity, which is
+     * immune to import aliases and name collisions.
+     *
+     * Returns `undefined` until {@link MutableExtensionRegistry.setSymbolMap} has been
+     * called (i.e., before the TypeScript program is available), or when the symbol is
+     * not registered via a type parameter.
+     *
+     * @param symbol - The canonical TypeScript symbol to look up.
+     */
+    findTypeBySymbol(symbol: ts.Symbol): ExtensionTypeLookupResult | undefined;
     /**
      * Look up a custom constraint registration by its fully-qualified constraint ID.
      *
@@ -757,6 +804,22 @@ export declare interface ExtensionRegistry {
  */
 declare type ExtensionTypeKind = "primitive" | "enum" | "array" | "object" | "record" | "union" | "reference" | "dynamic" | "custom";
 
+/**
+ * The result of a successful extension type lookup.
+ *
+ * Returned by {@link ExtensionRegistry.findTypeByName},
+ * {@link ExtensionRegistry.findTypeByBrand}, and
+ * {@link ExtensionRegistry.findTypeBySymbol}.
+ *
+ * @public
+ */
+export declare interface ExtensionTypeLookupResult {
+    /** The fully-qualified extension ID (e.g., "x-stripe/monetary"). */
+    readonly extensionId: string;
+    /** The custom type registration matched by this lookup. */
+    readonly registration: CustomTypeRegistration;
+}
+
 /**
  * Field configuration option constraints - control which field options are allowed.
  *
@@ -1846,6 +1909,28 @@ export declare interface MixedAuthoringSchemas {
     readonly uiSchema: UISchema;
 }
 
+/**
+ * Mutable extension registry used internally by the build pipeline.
+ *
+ * Extends {@link ExtensionRegistry} with `setSymbolMap`, which must be called
+ * after the TypeScript program is created. Consumer code should accept only
+ * the read-only {@link ExtensionRegistry} interface.
+ *
+ * @public
+ */
+export declare interface MutableExtensionRegistry extends ExtensionRegistry {
+    /**
+     * Sets the symbol map built from config AST analysis.
+     *
+     * Called after the TypeScript program is created and the config file is analyzed.
+     * Prior to this call, {@link ExtensionRegistry.findTypeBySymbol} always returns
+     * `undefined`.
+     *
+     * @param map - A map from canonical `ts.Symbol` to the matching registry entry.
+     */
+    setSymbolMap(map: Map<ts.Symbol, ExtensionTypeLookupResult>): void;
+}
+
 export { NumberField }
 
 export { ObjectField }
@@ -2080,6 +2165,22 @@ export declare interface StaticSchemaGenerationOptions {
     readonly metadata?: MetadataPolicyInput | undefined;
     /** Discriminator-specific schema generation behavior. */
     readonly discriminator?: DiscriminatorResolutionOptions | undefined;
+    /**
+     * Absolute path to the FormSpec config file (e.g., `formspec.config.ts`).
+     *
+     * When provided alongside a `config` that includes extensions, the build
+     * pipeline includes the config file in the TypeScript program and extracts
+     * `defineCustomType<T>()` type parameters. This enables symbol-based custom
+     * type detection — the most precise resolution path, immune to import aliases
+     * and name collisions.
+     *
+     * Obtain this from `loadFormSpecConfig()`:
+     * ```typescript
+     * const { config, configPath } = await loadFormSpecConfig();
+     * await generateSchemas({ filePath, typeName, config, configPath, errorReporting: "throw" });
+     * ```
+     */
+    readonly configPath?: string | undefined;
 }
 
 export { TextField }