@formspec/build 0.1.0-alpha.16 → 0.1.0-alpha.19

package/dist/index.js

@@ -20,6 +20,7 @@ function canonicalizeChainDSL(form) {
     kind: "form-ir",
     irVersion: IR_VERSION,
     elements: canonicalizeElements(form.elements),
+    rootAnnotations: [],
     typeRegistry: {},
     provenance: CHAIN_DSL_PROVENANCE
   };
@@ -325,6 +326,7 @@ function canonicalizeTSDoc(analysis, source) {
     irVersion: IR_VERSION2,
     elements,
     typeRegistry: analysis.typeRegistry,
+    ...analysis.annotations !== void 0 && analysis.annotations.length > 0 && { rootAnnotations: analysis.annotations },
     ...analysis.annotations !== void 0 && analysis.annotations.length > 0 && { annotations: analysis.annotations },
     provenance
   };
@@ -402,6 +404,9 @@ function generateJsonSchemaFromIR(ir, options) {
   const ctx = makeContext(options);
   for (const [name, typeDef] of Object.entries(ir.typeRegistry)) {
     ctx.defs[name] = generateTypeNode(typeDef.type, ctx);
+    if (typeDef.constraints && typeDef.constraints.length > 0) {
+      applyConstraints(ctx.defs[name], typeDef.constraints, ctx);
+    }
     if (typeDef.annotations && typeDef.annotations.length > 0) {
       applyAnnotations(ctx.defs[name], typeDef.annotations, ctx);
     }
@@ -570,7 +575,9 @@ function generateTypeNode(type, ctx) {
   }
 }
 function generatePrimitiveType(type) {
-  return { type: type.primitiveKind };
+  return {
+    type: type.primitiveKind === "integer" || type.primitiveKind === "bigint" ? "integer" : type.primitiveKind
+  };
 }
 function generateEnumType(type) {
   const hasDisplayNames = type.members.some((m) => m.displayName !== void 0);
@@ -743,7 +750,7 @@ function applyAnnotations(schema, annotations, ctx) {
       case "deprecated":
         schema.deprecated = true;
         if (annotation.message !== void 0 && annotation.message !== "") {
-          schema["x-formspec-deprecation-description"] = annotation.message;
+          schema[`${ctx.vendorPrefix}-deprecation-description`] = annotation.message;
         }
         break;
       case "placeholder":
@@ -776,7 +783,12 @@ function applyCustomConstraint(schema, constraint, ctx) {
       `Cannot generate JSON Schema for custom constraint "${constraint.constraintId}" without a matching extension registration`
     );
   }
-  Object.assign(schema, registration.toJsonSchema(constraint.payload, ctx.vendorPrefix));
+  assignVendorPrefixedExtensionKeywords(
+    schema,
+    registration.toJsonSchema(constraint.payload, ctx.vendorPrefix),
+    ctx.vendorPrefix,
+    `custom constraint "${constraint.constraintId}"`
+  );
 }
 function applyCustomAnnotation(schema, annotation, ctx) {
   const registration = ctx.extensionRegistry?.findAnnotation(annotation.annotationId);
@@ -788,7 +800,22 @@ function applyCustomAnnotation(schema, annotation, ctx) {
   if (registration.toJsonSchema === void 0) {
     return;
   }
-  Object.assign(schema, registration.toJsonSchema(annotation.value, ctx.vendorPrefix));
+  assignVendorPrefixedExtensionKeywords(
+    schema,
+    registration.toJsonSchema(annotation.value, ctx.vendorPrefix),
+    ctx.vendorPrefix,
+    `custom annotation "${annotation.annotationId}"`
+  );
+}
+function assignVendorPrefixedExtensionKeywords(schema, extensionSchema, vendorPrefix, source) {
+  for (const [key, value] of Object.entries(extensionSchema)) {
+    if (!key.startsWith(`${vendorPrefix}-`)) {
+      throw new Error(
+        `Cannot apply ${source}: extension hooks may only emit "${vendorPrefix}-*" JSON Schema keywords`
+      );
+    }
+    schema[key] = value;
+  }
 }
 
 // src/json-schema/generator.ts
@@ -1041,7 +1068,10 @@ function getSchemaExtension(schema, key) {
 // src/extensions/registry.ts
 function createExtensionRegistry(extensions) {
   const typeMap = /* @__PURE__ */ new Map();
+  const typeNameMap = /* @__PURE__ */ new Map();
   const constraintMap = /* @__PURE__ */ new Map();
+  const constraintTagMap = /* @__PURE__ */ new Map();
+  const builtinBroadeningMap = /* @__PURE__ */ new Map();
   const annotationMap = /* @__PURE__ */ new Map();
   for (const ext of extensions) {
     if (ext.types !== void 0) {
@@ -1051,6 +1081,27 @@ function createExtensionRegistry(extensions) {
           throw new Error(`Duplicate custom type ID: "${qualifiedId}"`);
         }
         typeMap.set(qualifiedId, type);
+        for (const sourceTypeName of type.tsTypeNames ?? [type.typeName]) {
+          if (typeNameMap.has(sourceTypeName)) {
+            throw new Error(`Duplicate custom type source name: "${sourceTypeName}"`);
+          }
+          typeNameMap.set(sourceTypeName, {
+            extensionId: ext.extensionId,
+            registration: type
+          });
+        }
+        if (type.builtinConstraintBroadenings !== void 0) {
+          for (const broadening of type.builtinConstraintBroadenings) {
+            const key = `${qualifiedId}:${broadening.tagName}`;
+            if (builtinBroadeningMap.has(key)) {
+              throw new Error(`Duplicate built-in constraint broadening: "${key}"`);
+            }
+            builtinBroadeningMap.set(key, {
+              extensionId: ext.extensionId,
+              registration: broadening
+            });
+          }
+        }
       }
     }
     if (ext.constraints !== void 0) {
@@ -1062,6 +1113,17 @@ function createExtensionRegistry(extensions) {
         constraintMap.set(qualifiedId, constraint);
       }
     }
+    if (ext.constraintTags !== void 0) {
+      for (const tag of ext.constraintTags) {
+        if (constraintTagMap.has(tag.tagName)) {
+          throw new Error(`Duplicate custom constraint tag: "@${tag.tagName}"`);
+        }
+        constraintTagMap.set(tag.tagName, {
+          extensionId: ext.extensionId,
+          registration: tag
+        });
+      }
+    }
     if (ext.annotations !== void 0) {
       for (const annotation of ext.annotations) {
         const qualifiedId = `${ext.extensionId}/${annotation.annotationName}`;
@@ -1075,7 +1137,10 @@ function createExtensionRegistry(extensions) {
   return {
     extensions,
     findType: (typeId) => typeMap.get(typeId),
+    findTypeByName: (typeName) => typeNameMap.get(typeName),
     findConstraint: (constraintId) => constraintMap.get(constraintId),
+    findConstraintTag: (tagName) => constraintTagMap.get(tagName),
+    findBuiltinConstraintBroadening: (typeId, tagName) => builtinBroadeningMap.get(`${typeId}:${tagName}`),
     findAnnotation: (annotationId) => annotationMap.get(annotationId)
   };
 }
@@ -1143,85 +1208,17 @@ var jsonSchema7Schema = z3.lazy(
 );
 
 // src/analyzer/program.ts
-import * as ts from "typescript";
+import * as ts4 from "typescript";
 import * as path from "path";
-function createProgramContext(filePath) {
-  const absolutePath = path.resolve(filePath);
-  const fileDir = path.dirname(absolutePath);
-  const configPath = ts.findConfigFile(fileDir, ts.sys.fileExists.bind(ts.sys), "tsconfig.json");
-  let compilerOptions;
-  let fileNames;
-  if (configPath) {
-    const configFile = ts.readConfigFile(configPath, ts.sys.readFile.bind(ts.sys));
-    if (configFile.error) {
-      throw new Error(
-        `Error reading tsconfig.json: ${ts.flattenDiagnosticMessageText(configFile.error.messageText, "\n")}`
-      );
-    }
-    const parsed = ts.parseJsonConfigFileContent(
-      configFile.config,
-      ts.sys,
-      path.dirname(configPath)
-    );
-    if (parsed.errors.length > 0) {
-      const errorMessages = parsed.errors.map((e) => ts.flattenDiagnosticMessageText(e.messageText, "\n")).join("\n");
-      throw new Error(`Error parsing tsconfig.json: ${errorMessages}`);
-    }
-    compilerOptions = parsed.options;
-    fileNames = parsed.fileNames.includes(absolutePath) ? parsed.fileNames : [...parsed.fileNames, absolutePath];
-  } else {
-    compilerOptions = {
-      target: ts.ScriptTarget.ES2022,
-      module: ts.ModuleKind.NodeNext,
-      moduleResolution: ts.ModuleResolutionKind.NodeNext,
-      strict: true,
-      skipLibCheck: true,
-      declaration: true
-    };
-    fileNames = [absolutePath];
-  }
-  const program = ts.createProgram(fileNames, compilerOptions);
-  const sourceFile = program.getSourceFile(absolutePath);
-  if (!sourceFile) {
-    throw new Error(`Could not find source file: ${absolutePath}`);
-  }
-  return {
-    program,
-    checker: program.getTypeChecker(),
-    sourceFile
-  };
-}
-function findNodeByName(sourceFile, name, predicate, getName) {
-  let result = null;
-  function visit(node) {
-    if (result) return;
-    if (predicate(node) && getName(node) === name) {
-      result = node;
-      return;
-    }
-    ts.forEachChild(node, visit);
-  }
-  visit(sourceFile);
-  return result;
-}
-function findClassByName(sourceFile, className) {
-  return findNodeByName(sourceFile, className, ts.isClassDeclaration, (n) => n.name?.text);
-}
-function findInterfaceByName(sourceFile, interfaceName) {
-  return findNodeByName(sourceFile, interfaceName, ts.isInterfaceDeclaration, (n) => n.name.text);
-}
-function findTypeAliasByName(sourceFile, aliasName) {
-  return findNodeByName(sourceFile, aliasName, ts.isTypeAliasDeclaration, (n) => n.name.text);
-}
 
 // src/analyzer/class-analyzer.ts
-import * as ts4 from "typescript";
+import * as ts3 from "typescript";
 
 // src/analyzer/jsdoc-constraints.ts
-import * as ts3 from "typescript";
+import * as ts2 from "typescript";
 
 // src/analyzer/tsdoc-parser.ts
-import * as ts2 from "typescript";
+import * as ts from "typescript";
 import {
   TSDocParser,
   TSDocConfiguration,
@@ -1261,7 +1258,7 @@ var LENGTH_CONSTRAINT_MAP = {
   maxItems: "maxItems"
 };
 var TAGS_REQUIRING_RAW_TEXT = /* @__PURE__ */ new Set(["pattern", "enumOptions", "defaultValue"]);
-function createFormSpecTSDocConfig() {
+function createFormSpecTSDocConfig(extensionTagNames = []) {
   const config = new TSDocConfiguration();
   for (const tagName of Object.keys(BUILTIN_CONSTRAINT_DEFINITIONS)) {
     config.addTagDefinition(
@@ -1281,14 +1278,34 @@ function createFormSpecTSDocConfig() {
       })
     );
   }
+  for (const tagName of extensionTagNames) {
+    config.addTagDefinition(
+      new TSDocTagDefinition({
+        tagName: "@" + tagName,
+        syntaxKind: TSDocTagSyntaxKind.BlockTag,
+        allowMultiple: true
+      })
+    );
+  }
   return config;
 }
-var sharedParser;
-function getParser() {
-  sharedParser ??= new TSDocParser(createFormSpecTSDocConfig());
-  return sharedParser;
-}
-function parseTSDocTags(node, file = "") {
+var parserCache = /* @__PURE__ */ new Map();
+function getParser(options) {
+  const extensionTagNames = [
+    ...options?.extensionRegistry?.extensions.flatMap(
+      (extension) => (extension.constraintTags ?? []).map((tag) => tag.tagName)
+    ) ?? []
+  ].sort();
+  const cacheKey = extensionTagNames.join("|");
+  const existing = parserCache.get(cacheKey);
+  if (existing) {
+    return existing;
+  }
+  const parser = new TSDocParser(createFormSpecTSDocConfig(extensionTagNames));
+  parserCache.set(cacheKey, parser);
+  return parser;
+}
+function parseTSDocTags(node, file = "", options) {
   const constraints = [];
   const annotations = [];
   let displayName;
@@ -1299,17 +1316,17 @@ function parseTSDocTags(node, file = "") {
   let placeholderProvenance;
   const sourceFile = node.getSourceFile();
   const sourceText = sourceFile.getFullText();
-  const commentRanges = ts2.getLeadingCommentRanges(sourceText, node.getFullStart());
+  const commentRanges = ts.getLeadingCommentRanges(sourceText, node.getFullStart());
   if (commentRanges) {
     for (const range of commentRanges) {
-      if (range.kind !== ts2.SyntaxKind.MultiLineCommentTrivia) {
+      if (range.kind !== ts.SyntaxKind.MultiLineCommentTrivia) {
         continue;
       }
       const commentText = sourceText.substring(range.pos, range.end);
       if (!commentText.startsWith("/**")) {
         continue;
       }
-      const parser = getParser();
+      const parser = getParser(options);
       const parserContext = parser.parseRange(
         TextRange.fromStringRange(sourceText, range.pos, range.end)
       );
@@ -1320,26 +1337,31 @@ function parseTSDocTags(node, file = "") {
           const text2 = extractBlockText(block).trim();
           if (text2 === "") continue;
           const provenance2 = provenanceForComment(range, sourceFile, file, tagName);
-          if (tagName === "displayName") {
-            if (!isMemberTargetDisplayName(text2) && displayName === void 0) {
-              displayName = text2;
-              displayNameProvenance = provenance2;
-            }
-          } else if (tagName === "format") {
-            annotations.push({
-              kind: "annotation",
-              annotationKind: "format",
-              value: text2,
-              provenance: provenance2
-            });
-          } else {
-            if (tagName === "description" && description === void 0) {
+          switch (tagName) {
+            case "displayName":
+              if (!isMemberTargetDisplayName(text2) && displayName === void 0) {
+                displayName = text2;
+                displayNameProvenance = provenance2;
+              }
+              break;
+            case "format":
+              annotations.push({
+                kind: "annotation",
+                annotationKind: "format",
+                value: text2,
+                provenance: provenance2
+              });
+              break;
+            case "description":
               description = text2;
               descriptionProvenance = provenance2;
-            } else if (tagName === "placeholder" && placeholder === void 0) {
-              placeholder = text2;
-              placeholderProvenance = provenance2;
-            }
+              break;
+            case "placeholder":
+              if (placeholder === void 0) {
+                placeholder = text2;
+                placeholderProvenance = provenance2;
+              }
+              break;
           }
           continue;
         }
@@ -1348,7 +1370,7 @@ function parseTSDocTags(node, file = "") {
         const expectedType = isBuiltinConstraintName(tagName) ? BUILTIN_CONSTRAINT_DEFINITIONS[tagName] : void 0;
         if (text === "" && expectedType !== "boolean") continue;
         const provenance = provenanceForComment(range, sourceFile, file, tagName);
-        const constraintNode = parseConstraintValue(tagName, text, provenance);
+        const constraintNode = parseConstraintValue(tagName, text, provenance, options);
         if (constraintNode) {
           constraints.push(constraintNode);
         }
@@ -1369,6 +1391,13 @@ function parseTSDocTags(node, file = "") {
           descriptionProvenance = provenanceForComment(range, sourceFile, file, "remarks");
         }
       }
+      if (description === void 0) {
+        const summary = extractPlainText(docComment.summarySection).trim();
+        if (summary !== "") {
+          description = summary;
+          descriptionProvenance = provenanceForComment(range, sourceFile, file, "summary");
+        }
+      }
     }
   }
   if (displayName !== void 0 && displayNameProvenance !== void 0) {
@@ -1395,7 +1424,7 @@ function parseTSDocTags(node, file = "") {
       provenance: placeholderProvenance
     });
   }
-  const jsDocTagsAll = ts2.getJSDocTags(node);
+  const jsDocTagsAll = ts.getJSDocTags(node);
   for (const tag of jsDocTagsAll) {
     const tagName = normalizeConstraintTagName(tag.tagName.text);
     if (!TAGS_REQUIRING_RAW_TEXT.has(tagName)) continue;
@@ -1408,7 +1437,7 @@ function parseTSDocTags(node, file = "") {
       annotations.push(defaultValueNode);
       continue;
     }
-    const constraintNode = parseConstraintValue(tagName, text, provenance);
+    const constraintNode = parseConstraintValue(tagName, text, provenance, options);
     if (constraintNode) {
       constraints.push(constraintNode);
     }
@@ -1418,7 +1447,7 @@ function parseTSDocTags(node, file = "") {
 function extractDisplayNameMetadata(node) {
   let displayName;
   const memberDisplayNames = /* @__PURE__ */ new Map();
-  for (const tag of ts2.getJSDocTags(node)) {
+  for (const tag of ts.getJSDocTags(node)) {
     const tagName = normalizeConstraintTagName(tag.tagName.text);
     if (tagName !== "displayName") continue;
     const commentText = getTagCommentText(tag);
@@ -1439,11 +1468,11 @@ function extractDisplayNameMetadata(node) {
 }
 function extractPathTarget(text) {
   const trimmed = text.trimStart();
-  const match = /^:([a-zA-Z_]\w*)\s+([\s\S]*)$/.exec(trimmed);
-  if (!match?.[1] || !match[2]) return null;
+  const match = /^:([a-zA-Z_]\w*)(?:\s+([\s\S]*))?$/.exec(trimmed);
+  if (!match?.[1]) return null;
   return {
     path: { segments: [match[1]] },
-    remainingText: match[2]
+    remainingText: match[2] ?? ""
   };
 }
 function extractBlockText(block) {
@@ -1464,7 +1493,11 @@ function extractPlainText(node) {
   }
   return result;
 }
-function parseConstraintValue(tagName, text, provenance) {
+function parseConstraintValue(tagName, text, provenance, options) {
+  const customConstraint = parseExtensionConstraintValue(tagName, text, provenance, options);
+  if (customConstraint) {
+    return customConstraint;
+  }
   if (!isBuiltinConstraintName(tagName)) {
     return null;
   }
@@ -1569,6 +1602,83 @@ function parseConstraintValue(tagName, text, provenance) {
     provenance
   };
 }
+function parseExtensionConstraintValue(tagName, text, provenance, options) {
+  const pathResult = extractPathTarget(text);
+  const effectiveText = pathResult ? pathResult.remainingText : text;
+  const path3 = pathResult?.path;
+  const registry = options?.extensionRegistry;
+  if (registry === void 0) {
+    return null;
+  }
+  const directTag = registry.findConstraintTag(tagName);
+  if (directTag !== void 0) {
+    return makeCustomConstraintNode(
+      directTag.extensionId,
+      directTag.registration.constraintName,
+      directTag.registration.parseValue(effectiveText),
+      provenance,
+      path3,
+      registry
+    );
+  }
+  if (!isBuiltinConstraintName(tagName)) {
+    return null;
+  }
+  const broadenedTypeId = getBroadenedCustomTypeId(options?.fieldType);
+  if (broadenedTypeId === void 0) {
+    return null;
+  }
+  const broadened = registry.findBuiltinConstraintBroadening(broadenedTypeId, tagName);
+  if (broadened === void 0) {
+    return null;
+  }
+  return makeCustomConstraintNode(
+    broadened.extensionId,
+    broadened.registration.constraintName,
+    broadened.registration.parseValue(effectiveText),
+    provenance,
+    path3,
+    registry
+  );
+}
+function getBroadenedCustomTypeId(fieldType) {
+  if (fieldType?.kind === "custom") {
+    return fieldType.typeId;
+  }
+  if (fieldType?.kind !== "union") {
+    return void 0;
+  }
+  const customMembers = fieldType.members.filter(
+    (member) => member.kind === "custom"
+  );
+  if (customMembers.length !== 1) {
+    return void 0;
+  }
+  const nonCustomMembers = fieldType.members.filter((member) => member.kind !== "custom");
+  const allOtherMembersAreNull = nonCustomMembers.every(
+    (member) => member.kind === "primitive" && member.primitiveKind === "null"
+  );
+  const customMember = customMembers[0];
+  return allOtherMembersAreNull && customMember !== void 0 ? customMember.typeId : void 0;
+}
+function makeCustomConstraintNode(extensionId, constraintName, payload, provenance, path3, registry) {
+  const constraintId = `${extensionId}/${constraintName}`;
+  const registration = registry.findConstraint(constraintId);
+  if (registration === void 0) {
+    throw new Error(
+      `Custom TSDoc tag resolved to unregistered constraint "${constraintId}". Register the constraint before using its tag.`
+    );
+  }
+  return {
+    kind: "constraint",
+    constraintKind: "custom",
+    constraintId,
+    payload,
+    compositionRule: registration.compositionRule,
+    ...path3 && { path: path3 },
+    provenance
+  };
+}
 function parseDefaultValueValue(text, provenance) {
   const trimmed = text.trim();
   let value;
@@ -1625,33 +1735,33 @@ function getTagCommentText(tag) {
   if (typeof tag.comment === "string") {
     return tag.comment;
   }
-  return ts2.getTextOfJSDocComment(tag.comment);
+  return ts.getTextOfJSDocComment(tag.comment);
 }
 
 // src/analyzer/jsdoc-constraints.ts
-function extractJSDocConstraintNodes(node, file = "") {
-  const result = parseTSDocTags(node, file);
+function extractJSDocConstraintNodes(node, file = "", options) {
+  const result = parseTSDocTags(node, file, options);
   return [...result.constraints];
 }
-function extractJSDocAnnotationNodes(node, file = "") {
-  const result = parseTSDocTags(node, file);
+function extractJSDocAnnotationNodes(node, file = "", options) {
+  const result = parseTSDocTags(node, file, options);
   return [...result.annotations];
 }
 function extractDefaultValueAnnotation(initializer, file = "") {
   if (!initializer) return null;
   let value;
-  if (ts3.isStringLiteral(initializer)) {
+  if (ts2.isStringLiteral(initializer)) {
     value = initializer.text;
-  } else if (ts3.isNumericLiteral(initializer)) {
+  } else if (ts2.isNumericLiteral(initializer)) {
     value = Number(initializer.text);
-  } else if (initializer.kind === ts3.SyntaxKind.TrueKeyword) {
+  } else if (initializer.kind === ts2.SyntaxKind.TrueKeyword) {
     value = true;
-  } else if (initializer.kind === ts3.SyntaxKind.FalseKeyword) {
+  } else if (initializer.kind === ts2.SyntaxKind.FalseKeyword) {
     value = false;
-  } else if (initializer.kind === ts3.SyntaxKind.NullKeyword) {
+  } else if (initializer.kind === ts2.SyntaxKind.NullKeyword) {
     value = null;
-  } else if (ts3.isPrefixUnaryExpression(initializer)) {
-    if (initializer.operator === ts3.SyntaxKind.MinusToken && ts3.isNumericLiteral(initializer.operand)) {
+  } else if (ts2.isPrefixUnaryExpression(initializer)) {
+    if (initializer.operator === ts2.SyntaxKind.MinusToken && ts2.isNumericLiteral(initializer.operand)) {
       value = -Number(initializer.operand.text);
     }
   }
@@ -1673,36 +1783,56 @@ function extractDefaultValueAnnotation(initializer, file = "") {
 
 // src/analyzer/class-analyzer.ts
 function isObjectType(type) {
-  return !!(type.flags & ts4.TypeFlags.Object);
+  return !!(type.flags & ts3.TypeFlags.Object);
 }
 function isTypeReference(type) {
-  return !!(type.flags & ts4.TypeFlags.Object) && !!(type.objectFlags & ts4.ObjectFlags.Reference);
+  return !!(type.flags & ts3.TypeFlags.Object) && !!(type.objectFlags & ts3.ObjectFlags.Reference);
 }
 var RESOLVING_TYPE_PLACEHOLDER = {
   kind: "object",
   properties: [],
   additionalProperties: true
 };
-function analyzeClassToIR(classDecl, checker, file = "") {
+function makeParseOptions(extensionRegistry, fieldType) {
+  if (extensionRegistry === void 0 && fieldType === void 0) {
+    return void 0;
+  }
+  return {
+    ...extensionRegistry !== void 0 && { extensionRegistry },
+    ...fieldType !== void 0 && { fieldType }
+  };
+}
+function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry) {
   const name = classDecl.name?.text ?? "AnonymousClass";
   const fields = [];
   const fieldLayouts = [];
   const typeRegistry = {};
-  const annotations = extractJSDocAnnotationNodes(classDecl, file);
+  const annotations = extractJSDocAnnotationNodes(
+    classDecl,
+    file,
+    makeParseOptions(extensionRegistry)
+  );
   const visiting = /* @__PURE__ */ new Set();
   const instanceMethods = [];
   const staticMethods = [];
   for (const member of classDecl.members) {
-    if (ts4.isPropertyDeclaration(member)) {
-      const fieldNode = analyzeFieldToIR(member, checker, file, typeRegistry, visiting);
+    if (ts3.isPropertyDeclaration(member)) {
+      const fieldNode = analyzeFieldToIR(
+        member,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        extensionRegistry
+      );
       if (fieldNode) {
         fields.push(fieldNode);
         fieldLayouts.push({});
       }
-    } else if (ts4.isMethodDeclaration(member)) {
+    } else if (ts3.isMethodDeclaration(member)) {
       const methodInfo = analyzeMethod(member, checker);
       if (methodInfo) {
-        const isStatic = member.modifiers?.some((m) => m.kind === ts4.SyntaxKind.StaticKeyword);
+        const isStatic = member.modifiers?.some((m) => m.kind === ts3.SyntaxKind.StaticKeyword);
         if (isStatic) {
           staticMethods.push(methodInfo);
         } else {
@@ -1721,15 +1851,26 @@ function analyzeClassToIR(classDecl, checker, file = "") {
     staticMethods
   };
 }
-function analyzeInterfaceToIR(interfaceDecl, checker, file = "") {
+function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegistry) {
   const name = interfaceDecl.name.text;
   const fields = [];
   const typeRegistry = {};
-  const annotations = extractJSDocAnnotationNodes(interfaceDecl, file);
+  const annotations = extractJSDocAnnotationNodes(
+    interfaceDecl,
+    file,
+    makeParseOptions(extensionRegistry)
+  );
   const visiting = /* @__PURE__ */ new Set();
   for (const member of interfaceDecl.members) {
-    if (ts4.isPropertySignature(member)) {
-      const fieldNode = analyzeInterfacePropertyToIR(member, checker, file, typeRegistry, visiting);
+    if (ts3.isPropertySignature(member)) {
+      const fieldNode = analyzeInterfacePropertyToIR(
+        member,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        extensionRegistry
+      );
       if (fieldNode) {
         fields.push(fieldNode);
       }
@@ -1746,11 +1887,11 @@ function analyzeInterfaceToIR(interfaceDecl, checker, file = "") {
     staticMethods: []
   };
 }
-function analyzeTypeAliasToIR(typeAlias, checker, file = "") {
-  if (!ts4.isTypeLiteralNode(typeAlias.type)) {
+function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry) {
+  if (!ts3.isTypeLiteralNode(typeAlias.type)) {
     const sourceFile = typeAlias.getSourceFile();
     const { line } = sourceFile.getLineAndCharacterOfPosition(typeAlias.getStart());
-    const kindDesc = ts4.SyntaxKind[typeAlias.type.kind] ?? "unknown";
+    const kindDesc = ts3.SyntaxKind[typeAlias.type.kind] ?? "unknown";
     return {
       ok: false,
       error: `Type alias "${typeAlias.name.text}" at line ${String(line + 1)} is not an object type literal (found ${kindDesc})`
@@ -1759,11 +1900,22 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "") {
   const name = typeAlias.name.text;
   const fields = [];
   const typeRegistry = {};
-  const annotations = extractJSDocAnnotationNodes(typeAlias, file);
+  const annotations = extractJSDocAnnotationNodes(
+    typeAlias,
+    file,
+    makeParseOptions(extensionRegistry)
+  );
   const visiting = /* @__PURE__ */ new Set();
   for (const member of typeAlias.type.members) {
-    if (ts4.isPropertySignature(member)) {
-      const fieldNode = analyzeInterfacePropertyToIR(member, checker, file, typeRegistry, visiting);
+    if (ts3.isPropertySignature(member)) {
+      const fieldNode = analyzeInterfacePropertyToIR(
+        member,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        extensionRegistry
+      );
       if (fieldNode) {
         fields.push(fieldNode);
       }
@@ -1782,22 +1934,36 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "") {
     }
   };
 }
-function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting) {
-  if (!ts4.isIdentifier(prop.name)) {
+function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, extensionRegistry) {
+  if (!ts3.isIdentifier(prop.name)) {
     return null;
   }
   const name = prop.name.text;
   const tsType = checker.getTypeAtLocation(prop);
   const optional = prop.questionToken !== void 0;
   const provenance = provenanceForNode(prop, file);
-  let type = resolveTypeNode(tsType, checker, file, typeRegistry, visiting, prop);
+  let type = resolveTypeNode(
+    tsType,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    prop,
+    extensionRegistry
+  );
   const constraints = [];
-  if (prop.type) {
-    constraints.push(...extractTypeAliasConstraintNodes(prop.type, checker, file));
+  if (prop.type && !shouldEmitPrimitiveAliasDefinition(prop.type, checker)) {
+    constraints.push(
+      ...extractTypeAliasConstraintNodes(prop.type, checker, file, extensionRegistry)
+    );
   }
-  constraints.push(...extractJSDocConstraintNodes(prop, file));
+  constraints.push(
+    ...extractJSDocConstraintNodes(prop, file, makeParseOptions(extensionRegistry, type))
+  );
   let annotations = [];
-  annotations.push(...extractJSDocAnnotationNodes(prop, file));
+  annotations.push(
+    ...extractJSDocAnnotationNodes(prop, file, makeParseOptions(extensionRegistry, type))
+  );
   const defaultAnnotation = extractDefaultValueAnnotation(prop.initializer, file);
   if (defaultAnnotation && !annotations.some((a) => a.annotationKind === "defaultValue")) {
     annotations.push(defaultAnnotation);
@@ -1813,22 +1979,36 @@ function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting) {
     provenance
   };
 }
-function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visiting) {
-  if (!ts4.isIdentifier(prop.name)) {
+function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visiting, extensionRegistry) {
+  if (!ts3.isIdentifier(prop.name)) {
     return null;
   }
   const name = prop.name.text;
   const tsType = checker.getTypeAtLocation(prop);
   const optional = prop.questionToken !== void 0;
   const provenance = provenanceForNode(prop, file);
-  let type = resolveTypeNode(tsType, checker, file, typeRegistry, visiting, prop);
+  let type = resolveTypeNode(
+    tsType,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    prop,
+    extensionRegistry
+  );
   const constraints = [];
-  if (prop.type) {
-    constraints.push(...extractTypeAliasConstraintNodes(prop.type, checker, file));
+  if (prop.type && !shouldEmitPrimitiveAliasDefinition(prop.type, checker)) {
+    constraints.push(
+      ...extractTypeAliasConstraintNodes(prop.type, checker, file, extensionRegistry)
+    );
   }
-  constraints.push(...extractJSDocConstraintNodes(prop, file));
+  constraints.push(
+    ...extractJSDocConstraintNodes(prop, file, makeParseOptions(extensionRegistry, type))
+  );
   let annotations = [];
-  annotations.push(...extractJSDocAnnotationNodes(prop, file));
+  annotations.push(
+    ...extractJSDocAnnotationNodes(prop, file, makeParseOptions(extensionRegistry, type))
+  );
   ({ type, annotations } = applyEnumMemberDisplayNames(type, annotations));
   return {
     kind: "field",
@@ -1902,20 +2082,94 @@ function parseEnumMemberDisplayName(value) {
   if (label === "") return null;
   return { value: match[1], label };
 }
-function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode) {
-  if (type.flags & ts4.TypeFlags.String) {
+function resolveRegisteredCustomType(sourceNode, extensionRegistry, checker) {
+  if (sourceNode === void 0 || extensionRegistry === void 0) {
+    return null;
+  }
+  const typeNode = extractTypeNodeFromSource(sourceNode);
+  if (typeNode === void 0) {
+    return null;
+  }
+  return resolveRegisteredCustomTypeFromTypeNode(typeNode, extensionRegistry, checker);
+}
+function resolveRegisteredCustomTypeFromTypeNode(typeNode, extensionRegistry, checker) {
+  if (ts3.isParenthesizedTypeNode(typeNode)) {
+    return resolveRegisteredCustomTypeFromTypeNode(typeNode.type, extensionRegistry, checker);
+  }
+  const typeName = getTypeNodeRegistrationName(typeNode);
+  if (typeName === null) {
+    return null;
+  }
+  const registration = extensionRegistry.findTypeByName(typeName);
+  if (registration !== void 0) {
+    return {
+      kind: "custom",
+      typeId: `${registration.extensionId}/${registration.registration.typeName}`,
+      payload: null
+    };
+  }
+  if (ts3.isTypeReferenceNode(typeNode) && ts3.isIdentifier(typeNode.typeName)) {
+    const aliasDecl = checker.getSymbolAtLocation(typeNode.typeName)?.declarations?.find(ts3.isTypeAliasDeclaration);
+    if (aliasDecl !== void 0) {
+      return resolveRegisteredCustomTypeFromTypeNode(aliasDecl.type, extensionRegistry, checker);
+    }
+  }
+  return null;
+}
+function extractTypeNodeFromSource(sourceNode) {
+  if (ts3.isPropertyDeclaration(sourceNode) || ts3.isPropertySignature(sourceNode) || ts3.isParameter(sourceNode) || ts3.isTypeAliasDeclaration(sourceNode)) {
+    return sourceNode.type;
+  }
+  if (ts3.isTypeNode(sourceNode)) {
+    return sourceNode;
+  }
+  return void 0;
+}
+function getTypeNodeRegistrationName(typeNode) {
+  if (ts3.isTypeReferenceNode(typeNode)) {
+    return ts3.isIdentifier(typeNode.typeName) ? typeNode.typeName.text : typeNode.typeName.right.text;
+  }
+  if (ts3.isParenthesizedTypeNode(typeNode)) {
+    return getTypeNodeRegistrationName(typeNode.type);
+  }
+  if (typeNode.kind === ts3.SyntaxKind.BigIntKeyword || typeNode.kind === ts3.SyntaxKind.StringKeyword || typeNode.kind === ts3.SyntaxKind.NumberKeyword || typeNode.kind === ts3.SyntaxKind.BooleanKeyword) {
+    return typeNode.getText();
+  }
+  return null;
+}
+function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry) {
+  const customType = resolveRegisteredCustomType(sourceNode, extensionRegistry, checker);
+  if (customType) {
+    return customType;
+  }
+  const primitiveAlias = tryResolveNamedPrimitiveAlias(
+    type,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    sourceNode,
+    extensionRegistry
+  );
+  if (primitiveAlias) {
+    return primitiveAlias;
+  }
+  if (type.flags & ts3.TypeFlags.String) {
     return { kind: "primitive", primitiveKind: "string" };
   }
-  if (type.flags & ts4.TypeFlags.Number) {
+  if (type.flags & ts3.TypeFlags.Number) {
     return { kind: "primitive", primitiveKind: "number" };
   }
-  if (type.flags & ts4.TypeFlags.Boolean) {
+  if (type.flags & (ts3.TypeFlags.BigInt | ts3.TypeFlags.BigIntLiteral)) {
+    return { kind: "primitive", primitiveKind: "bigint" };
+  }
+  if (type.flags & ts3.TypeFlags.Boolean) {
     return { kind: "primitive", primitiveKind: "boolean" };
   }
-  if (type.flags & ts4.TypeFlags.Null) {
+  if (type.flags & ts3.TypeFlags.Null) {
     return { kind: "primitive", primitiveKind: "null" };
   }
-  if (type.flags & ts4.TypeFlags.Undefined) {
+  if (type.flags & ts3.TypeFlags.Undefined) {
     return { kind: "primitive", primitiveKind: "null" };
   }
   if (type.isStringLiteral()) {
@@ -1931,27 +2185,120 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
     };
   }
   if (type.isUnion()) {
-    return resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode);
+    return resolveUnionType(
+      type,
+      checker,
+      file,
+      typeRegistry,
+      visiting,
+      sourceNode,
+      extensionRegistry
+    );
   }
   if (checker.isArrayType(type)) {
-    return resolveArrayType(type, checker, file, typeRegistry, visiting);
+    return resolveArrayType(
+      type,
+      checker,
+      file,
+      typeRegistry,
+      visiting,
+      sourceNode,
+      extensionRegistry
+    );
   }
   if (isObjectType(type)) {
-    return resolveObjectType(type, checker, file, typeRegistry, visiting);
+    return resolveObjectType(type, checker, file, typeRegistry, visiting, extensionRegistry);
   }
   return { kind: "primitive", primitiveKind: "string" };
 }
-function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode) {
+function tryResolveNamedPrimitiveAlias(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry) {
+  if (!(type.flags & (ts3.TypeFlags.String | ts3.TypeFlags.Number | ts3.TypeFlags.BigInt | ts3.TypeFlags.BigIntLiteral | ts3.TypeFlags.Boolean | ts3.TypeFlags.Null))) {
+    return null;
+  }
+  const aliasDecl = type.aliasSymbol?.declarations?.find(ts3.isTypeAliasDeclaration) ?? getReferencedTypeAliasDeclaration(sourceNode, checker);
+  if (!aliasDecl) {
+    return null;
+  }
+  const aliasName = aliasDecl.name.text;
+  if (!typeRegistry[aliasName]) {
+    const aliasType = checker.getTypeFromTypeNode(aliasDecl.type);
+    const constraints = [
+      ...extractJSDocConstraintNodes(aliasDecl, file, makeParseOptions(extensionRegistry)),
+      ...extractTypeAliasConstraintNodes(aliasDecl.type, checker, file, extensionRegistry)
+    ];
+    const annotations = extractJSDocAnnotationNodes(
+      aliasDecl,
+      file,
+      makeParseOptions(extensionRegistry)
+    );
+    typeRegistry[aliasName] = {
+      name: aliasName,
+      type: resolveAliasedPrimitiveTarget(
+        aliasType,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        extensionRegistry
+      ),
+      ...constraints.length > 0 && { constraints },
+      ...annotations.length > 0 && { annotations },
+      provenance: provenanceForDeclaration(aliasDecl, file)
+    };
+  }
+  return { kind: "reference", name: aliasName, typeArguments: [] };
+}
+function getReferencedTypeAliasDeclaration(sourceNode, checker) {
+  const typeNode = sourceNode && (ts3.isPropertyDeclaration(sourceNode) || ts3.isPropertySignature(sourceNode) || ts3.isParameter(sourceNode)) ? sourceNode.type : void 0;
+  if (!typeNode || !ts3.isTypeReferenceNode(typeNode)) {
+    return void 0;
+  }
+  return checker.getSymbolAtLocation(typeNode.typeName)?.declarations?.find(ts3.isTypeAliasDeclaration);
+}
+function shouldEmitPrimitiveAliasDefinition(typeNode, checker) {
+  if (!ts3.isTypeReferenceNode(typeNode)) {
+    return false;
+  }
+  const aliasDecl = checker.getSymbolAtLocation(typeNode.typeName)?.declarations?.find(ts3.isTypeAliasDeclaration);
+  if (!aliasDecl) {
+    return false;
+  }
+  const resolved = checker.getTypeFromTypeNode(aliasDecl.type);
+  return !!(resolved.flags & (ts3.TypeFlags.String | ts3.TypeFlags.Number | ts3.TypeFlags.BigInt | ts3.TypeFlags.BigIntLiteral | ts3.TypeFlags.Boolean | ts3.TypeFlags.Null));
+}
+function resolveAliasedPrimitiveTarget(type, checker, file, typeRegistry, visiting, extensionRegistry) {
+  const nestedAliasDecl = type.aliasSymbol?.declarations?.find(ts3.isTypeAliasDeclaration);
+  if (nestedAliasDecl !== void 0) {
+    return resolveAliasedPrimitiveTarget(
+      checker.getTypeFromTypeNode(nestedAliasDecl.type),
+      checker,
+      file,
+      typeRegistry,
+      visiting,
+      extensionRegistry
+    );
+  }
+  return resolveTypeNode(type, checker, file, typeRegistry, visiting, void 0, extensionRegistry);
+}
+function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry) {
   const typeName = getNamedTypeName(type);
   const namedDecl = getNamedTypeDeclaration(type);
   if (typeName && typeName in typeRegistry) {
     return { kind: "reference", name: typeName, typeArguments: [] };
   }
   const allTypes = type.types;
+  const unionMemberTypeNodes = extractUnionMemberTypeNodes(sourceNode, checker);
+  const nonNullSourceNodes = unionMemberTypeNodes.filter(
+    (memberTypeNode) => !isNullishTypeNode(resolveAliasedTypeNode(memberTypeNode, checker))
+  );
   const nonNullTypes = allTypes.filter(
-    (t) => !(t.flags & (ts4.TypeFlags.Null | ts4.TypeFlags.Undefined))
+    (memberType) => !(memberType.flags & (ts3.TypeFlags.Null | ts3.TypeFlags.Undefined))
   );
-  const hasNull = allTypes.some((t) => t.flags & ts4.TypeFlags.Null);
+  const nonNullMembers = nonNullTypes.map((memberType, index) => ({
+    memberType,
+    sourceNode: nonNullSourceNodes.length === nonNullTypes.length ? nonNullSourceNodes[index] : void 0
+  }));
+  const hasNull = allTypes.some((t) => t.flags & ts3.TypeFlags.Null);
   const memberDisplayNames = /* @__PURE__ */ new Map();
   if (namedDecl) {
     for (const [value, label] of extractDisplayNameMetadata(namedDecl).memberDisplayNames) {
@@ -1967,7 +2314,7 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
     if (!typeName) {
       return result;
     }
-    const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file) : void 0;
+    const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
     typeRegistry[typeName] = {
       name: typeName,
       type: result,
@@ -1980,7 +2327,7 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
     const displayName = memberDisplayNames.get(String(value));
     return displayName !== void 0 ? { value, displayName } : { value };
   });
-  const isBooleanUnion2 = nonNullTypes.length === 2 && nonNullTypes.every((t) => t.flags & ts4.TypeFlags.BooleanLiteral);
+  const isBooleanUnion2 = nonNullTypes.length === 2 && nonNullTypes.every((t) => t.flags & ts3.TypeFlags.BooleanLiteral);
   if (isBooleanUnion2) {
     const boolNode = { kind: "primitive", primitiveKind: "boolean" };
     const result = hasNull ? {
@@ -2015,14 +2362,15 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
     } : enumNode;
     return registerNamed(result);
   }
-  if (nonNullTypes.length === 1 && nonNullTypes[0]) {
+  if (nonNullMembers.length === 1 && nonNullMembers[0]) {
     const inner = resolveTypeNode(
-      nonNullTypes[0],
+      nonNullMembers[0].memberType,
       checker,
       file,
       typeRegistry,
       visiting,
-      sourceNode
+      nonNullMembers[0].sourceNode ?? sourceNode,
+      extensionRegistry
     );
     const result = hasNull ? {
       kind: "union",
@@ -2030,29 +2378,54 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
     } : inner;
     return registerNamed(result);
   }
-  const members = nonNullTypes.map(
-    (t) => resolveTypeNode(t, checker, file, typeRegistry, visiting, sourceNode)
+  const members = nonNullMembers.map(
+    ({ memberType, sourceNode: memberSourceNode }) => resolveTypeNode(
+      memberType,
+      checker,
+      file,
+      typeRegistry,
+      visiting,
+      memberSourceNode ?? sourceNode,
+      extensionRegistry
+    )
   );
   if (hasNull) {
     members.push({ kind: "primitive", primitiveKind: "null" });
   }
   return registerNamed({ kind: "union", members });
 }
-function resolveArrayType(type, checker, file, typeRegistry, visiting) {
+function resolveArrayType(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry) {
   const typeArgs = isTypeReference(type) ? type.typeArguments : void 0;
   const elementType = typeArgs?.[0];
-  const items = elementType ? resolveTypeNode(elementType, checker, file, typeRegistry, visiting) : { kind: "primitive", primitiveKind: "string" };
+  const elementSourceNode = extractArrayElementTypeNode(sourceNode, checker);
+  const items = elementType ? resolveTypeNode(
+    elementType,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    elementSourceNode,
+    extensionRegistry
+  ) : { kind: "primitive", primitiveKind: "string" };
   return { kind: "array", items };
 }
-function tryResolveRecordType(type, checker, file, typeRegistry, visiting) {
+function tryResolveRecordType(type, checker, file, typeRegistry, visiting, extensionRegistry) {
   if (type.getProperties().length > 0) {
     return null;
   }
-  const indexInfo = checker.getIndexInfoOfType(type, ts4.IndexKind.String);
+  const indexInfo = checker.getIndexInfoOfType(type, ts3.IndexKind.String);
   if (!indexInfo) {
     return null;
   }
-  const valueType = resolveTypeNode(indexInfo.type, checker, file, typeRegistry, visiting);
+  const valueType = resolveTypeNode(
+    indexInfo.type,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    void 0,
+    extensionRegistry
+  );
   return { kind: "record", valueType };
 }
 function typeNodeContainsReference(type, targetName) {
@@ -2080,7 +2453,7 @@ function typeNodeContainsReference(type, targetName) {
     }
   }
 }
-function resolveObjectType(type, checker, file, typeRegistry, visiting) {
+function resolveObjectType(type, checker, file, typeRegistry, visiting, extensionRegistry) {
   const typeName = getNamedTypeName(type);
   const namedTypeName = typeName ?? void 0;
   const namedDecl = getNamedTypeDeclaration(type);
@@ -2111,7 +2484,14 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
       return { kind: "reference", name: namedTypeName, typeArguments: [] };
     }
   }
-  const recordNode = tryResolveRecordType(type, checker, file, typeRegistry, visiting);
+  const recordNode = tryResolveRecordType(
+    type,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    extensionRegistry
+  );
   if (recordNode) {
     visiting.delete(type);
     if (namedTypeName !== void 0 && shouldRegisterNamedType) {
@@ -2120,7 +2500,7 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
         clearNamedTypeRegistration();
         return recordNode;
       }
-      const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file) : void 0;
+      const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
       typeRegistry[namedTypeName] = {
         name: namedTypeName,
         type: recordNode,
@@ -2132,19 +2512,27 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
     return recordNode;
   }
   const properties = [];
-  const fieldInfoMap = getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visiting);
+  const fieldInfoMap = getNamedTypeFieldNodeInfoMap(
+    type,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    extensionRegistry
+  );
   for (const prop of type.getProperties()) {
     const declaration = prop.valueDeclaration ?? prop.declarations?.[0];
     if (!declaration) continue;
     const propType = checker.getTypeOfSymbolAtLocation(prop, declaration);
-    const optional = !!(prop.flags & ts4.SymbolFlags.Optional);
+    const optional = !!(prop.flags & ts3.SymbolFlags.Optional);
     const propTypeNode = resolveTypeNode(
       propType,
       checker,
       file,
       typeRegistry,
       visiting,
-      declaration
+      declaration,
+      extensionRegistry
     );
     const fieldNodeInfo = fieldInfoMap?.get(prop.name);
     properties.push({
@@ -2163,7 +2551,7 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
     additionalProperties: true
   };
   if (namedTypeName !== void 0 && shouldRegisterNamedType) {
-    const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file) : void 0;
+    const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
     typeRegistry[namedTypeName] = {
       name: namedTypeName,
       type: objectNode,
@@ -2174,19 +2562,26 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
   }
   return objectNode;
 }
-function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visiting) {
+function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visiting, extensionRegistry) {
   const symbols = [type.getSymbol(), type.aliasSymbol].filter(
     (s) => s?.declarations != null && s.declarations.length > 0
   );
   for (const symbol of symbols) {
     const declarations = symbol.declarations;
     if (!declarations) continue;
-    const classDecl = declarations.find(ts4.isClassDeclaration);
+    const classDecl = declarations.find(ts3.isClassDeclaration);
     if (classDecl) {
       const map = /* @__PURE__ */ new Map();
       for (const member of classDecl.members) {
-        if (ts4.isPropertyDeclaration(member) && ts4.isIdentifier(member.name)) {
-          const fieldNode = analyzeFieldToIR(member, checker, file, typeRegistry, visiting);
+        if (ts3.isPropertyDeclaration(member) && ts3.isIdentifier(member.name)) {
+          const fieldNode = analyzeFieldToIR(
+            member,
+            checker,
+            file,
+            typeRegistry,
+            visiting,
+            extensionRegistry
+          );
           if (fieldNode) {
             map.set(fieldNode.name, {
               constraints: [...fieldNode.constraints],
@@ -2198,28 +2593,86 @@ function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visitin
       }
       return map;
     }
-    const interfaceDecl = declarations.find(ts4.isInterfaceDeclaration);
+    const interfaceDecl = declarations.find(ts3.isInterfaceDeclaration);
     if (interfaceDecl) {
-      return buildFieldNodeInfoMap(interfaceDecl.members, checker, file, typeRegistry, visiting);
-    }
-    const typeAliasDecl = declarations.find(ts4.isTypeAliasDeclaration);
-    if (typeAliasDecl && ts4.isTypeLiteralNode(typeAliasDecl.type)) {
+      return buildFieldNodeInfoMap(
+        interfaceDecl.members,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        extensionRegistry
+      );
+    }
+    const typeAliasDecl = declarations.find(ts3.isTypeAliasDeclaration);
+    if (typeAliasDecl && ts3.isTypeLiteralNode(typeAliasDecl.type)) {
       return buildFieldNodeInfoMap(
         typeAliasDecl.type.members,
         checker,
         file,
         typeRegistry,
-        visiting
+        visiting,
+        extensionRegistry
       );
     }
   }
   return null;
 }
-function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting) {
+function extractArrayElementTypeNode(sourceNode, checker) {
+  const typeNode = sourceNode === void 0 ? void 0 : extractTypeNodeFromSource(sourceNode);
+  if (typeNode === void 0) {
+    return void 0;
+  }
+  const resolvedTypeNode = resolveAliasedTypeNode(typeNode, checker);
+  if (ts3.isArrayTypeNode(resolvedTypeNode)) {
+    return resolvedTypeNode.elementType;
+  }
+  if (ts3.isTypeReferenceNode(resolvedTypeNode) && ts3.isIdentifier(resolvedTypeNode.typeName) && resolvedTypeNode.typeName.text === "Array" && resolvedTypeNode.typeArguments?.[0]) {
+    return resolvedTypeNode.typeArguments[0];
+  }
+  return void 0;
+}
+function extractUnionMemberTypeNodes(sourceNode, checker) {
+  const typeNode = sourceNode === void 0 ? void 0 : extractTypeNodeFromSource(sourceNode);
+  if (!typeNode) {
+    return [];
+  }
+  const resolvedTypeNode = resolveAliasedTypeNode(typeNode, checker);
+  return ts3.isUnionTypeNode(resolvedTypeNode) ? [...resolvedTypeNode.types] : [];
+}
+function resolveAliasedTypeNode(typeNode, checker, visited = /* @__PURE__ */ new Set()) {
+  if (ts3.isParenthesizedTypeNode(typeNode)) {
+    return resolveAliasedTypeNode(typeNode.type, checker, visited);
+  }
+  if (!ts3.isTypeReferenceNode(typeNode) || !ts3.isIdentifier(typeNode.typeName)) {
+    return typeNode;
+  }
+  const symbol = checker.getSymbolAtLocation(typeNode.typeName);
+  const aliasDecl = symbol?.declarations?.find(ts3.isTypeAliasDeclaration);
+  if (aliasDecl === void 0 || visited.has(aliasDecl)) {
+    return typeNode;
+  }
+  visited.add(aliasDecl);
+  return resolveAliasedTypeNode(aliasDecl.type, checker, visited);
+}
+function isNullishTypeNode(typeNode) {
+  if (typeNode.kind === ts3.SyntaxKind.NullKeyword || typeNode.kind === ts3.SyntaxKind.UndefinedKeyword) {
+    return true;
+  }
+  return ts3.isLiteralTypeNode(typeNode) && (typeNode.literal.kind === ts3.SyntaxKind.NullKeyword || typeNode.literal.kind === ts3.SyntaxKind.UndefinedKeyword);
+}
+function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting, extensionRegistry) {
   const map = /* @__PURE__ */ new Map();
   for (const member of members) {
-    if (ts4.isPropertySignature(member)) {
-      const fieldNode = analyzeInterfacePropertyToIR(member, checker, file, typeRegistry, visiting);
+    if (ts3.isPropertySignature(member)) {
+      const fieldNode = analyzeInterfacePropertyToIR(
+        member,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        extensionRegistry
+      );
       if (fieldNode) {
         map.set(fieldNode.name, {
           constraints: [...fieldNode.constraints],
@@ -2232,8 +2685,8 @@ function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting) {
   return map;
 }
 var MAX_ALIAS_CHAIN_DEPTH = 8;
-function extractTypeAliasConstraintNodes(typeNode, checker, file, depth = 0) {
-  if (!ts4.isTypeReferenceNode(typeNode)) return [];
+function extractTypeAliasConstraintNodes(typeNode, checker, file, extensionRegistry, depth = 0) {
+  if (!ts3.isTypeReferenceNode(typeNode)) return [];
   if (depth >= MAX_ALIAS_CHAIN_DEPTH) {
     const aliasName = typeNode.typeName.getText();
     throw new Error(
@@ -2242,11 +2695,26 @@ function extractTypeAliasConstraintNodes(typeNode, checker, file, depth = 0) {
   }
   const symbol = checker.getSymbolAtLocation(typeNode.typeName);
   if (!symbol?.declarations) return [];
-  const aliasDecl = symbol.declarations.find(ts4.isTypeAliasDeclaration);
+  const aliasDecl = symbol.declarations.find(ts3.isTypeAliasDeclaration);
   if (!aliasDecl) return [];
-  if (ts4.isTypeLiteralNode(aliasDecl.type)) return [];
-  const constraints = extractJSDocConstraintNodes(aliasDecl, file);
-  constraints.push(...extractTypeAliasConstraintNodes(aliasDecl.type, checker, file, depth + 1));
+  if (ts3.isTypeLiteralNode(aliasDecl.type)) return [];
+  const aliasFieldType = resolveTypeNode(
+    checker.getTypeAtLocation(aliasDecl.type),
+    checker,
+    file,
+    {},
+    /* @__PURE__ */ new Set(),
+    aliasDecl.type,
+    extensionRegistry
+  );
+  const constraints = extractJSDocConstraintNodes(
+    aliasDecl,
+    file,
+    makeParseOptions(extensionRegistry, aliasFieldType)
+  );
+  constraints.push(
+    ...extractTypeAliasConstraintNodes(aliasDecl.type, checker, file, extensionRegistry, depth + 1)
+  );
   return constraints;
 }
 function provenanceForNode(node, file) {
@@ -2272,14 +2740,14 @@ function getNamedTypeName(type) {
   const symbol = type.getSymbol();
   if (symbol?.declarations) {
     const decl = symbol.declarations[0];
-    if (decl && (ts4.isClassDeclaration(decl) || ts4.isInterfaceDeclaration(decl) || ts4.isTypeAliasDeclaration(decl))) {
-      const name = ts4.isClassDeclaration(decl) ? decl.name?.text : decl.name.text;
+    if (decl && (ts3.isClassDeclaration(decl) || ts3.isInterfaceDeclaration(decl) || ts3.isTypeAliasDeclaration(decl))) {
+      const name = ts3.isClassDeclaration(decl) ? decl.name?.text : decl.name.text;
       if (name) return name;
     }
   }
   const aliasSymbol = type.aliasSymbol;
   if (aliasSymbol?.declarations) {
-    const aliasDecl = aliasSymbol.declarations.find(ts4.isTypeAliasDeclaration);
+    const aliasDecl = aliasSymbol.declarations.find(ts3.isTypeAliasDeclaration);
     if (aliasDecl) {
       return aliasDecl.name.text;
     }
@@ -2290,24 +2758,24 @@ function getNamedTypeDeclaration(type) {
   const symbol = type.getSymbol();
   if (symbol?.declarations) {
     const decl = symbol.declarations[0];
-    if (decl && (ts4.isClassDeclaration(decl) || ts4.isInterfaceDeclaration(decl) || ts4.isTypeAliasDeclaration(decl))) {
+    if (decl && (ts3.isClassDeclaration(decl) || ts3.isInterfaceDeclaration(decl) || ts3.isTypeAliasDeclaration(decl))) {
       return decl;
     }
   }
   const aliasSymbol = type.aliasSymbol;
   if (aliasSymbol?.declarations) {
-    return aliasSymbol.declarations.find(ts4.isTypeAliasDeclaration);
+    return aliasSymbol.declarations.find(ts3.isTypeAliasDeclaration);
   }
   return void 0;
 }
 function analyzeMethod(method, checker) {
-  if (!ts4.isIdentifier(method.name)) {
+  if (!ts3.isIdentifier(method.name)) {
     return null;
   }
   const name = method.name.text;
   const parameters = [];
   for (const param of method.parameters) {
-    if (ts4.isIdentifier(param.name)) {
+    if (ts3.isIdentifier(param.name)) {
       const paramInfo = analyzeParameter(param, checker);
       parameters.push(paramInfo);
     }
@@ -2318,7 +2786,7 @@ function analyzeMethod(method, checker) {
   return { name, parameters, returnTypeNode, returnType };
 }
 function analyzeParameter(param, checker) {
-  const name = ts4.isIdentifier(param.name) ? param.name.text : "param";
+  const name = ts3.isIdentifier(param.name) ? param.name.text : "param";
   const typeNode = param.type;
   const type = checker.getTypeAtLocation(param);
   const formSpecExportName = detectFormSpecReference(typeNode);
@@ -2327,67 +2795,966 @@ function analyzeParameter(param, checker) {
 }
 function detectFormSpecReference(typeNode) {
   if (!typeNode) return null;
-  if (!ts4.isTypeReferenceNode(typeNode)) return null;
-  const typeName = ts4.isIdentifier(typeNode.typeName) ? typeNode.typeName.text : ts4.isQualifiedName(typeNode.typeName) ? typeNode.typeName.right.text : null;
+  if (!ts3.isTypeReferenceNode(typeNode)) return null;
+  const typeName = ts3.isIdentifier(typeNode.typeName) ? typeNode.typeName.text : ts3.isQualifiedName(typeNode.typeName) ? typeNode.typeName.right.text : null;
   if (typeName !== "InferSchema" && typeName !== "InferFormSchema") return null;
   const typeArg = typeNode.typeArguments?.[0];
-  if (!typeArg || !ts4.isTypeQueryNode(typeArg)) return null;
-  if (ts4.isIdentifier(typeArg.exprName)) {
+  if (!typeArg || !ts3.isTypeQueryNode(typeArg)) return null;
+  if (ts3.isIdentifier(typeArg.exprName)) {
     return typeArg.exprName.text;
   }
-  if (ts4.isQualifiedName(typeArg.exprName)) {
+  if (ts3.isQualifiedName(typeArg.exprName)) {
     return typeArg.exprName.right.text;
   }
   return null;
 }
 
+// src/analyzer/program.ts
+function createProgramContext(filePath) {
+  const absolutePath = path.resolve(filePath);
+  const fileDir = path.dirname(absolutePath);
+  const configPath = ts4.findConfigFile(fileDir, ts4.sys.fileExists.bind(ts4.sys), "tsconfig.json");
+  let compilerOptions;
+  let fileNames;
+  if (configPath) {
+    const configFile = ts4.readConfigFile(configPath, ts4.sys.readFile.bind(ts4.sys));
+    if (configFile.error) {
+      throw new Error(
+        `Error reading tsconfig.json: ${ts4.flattenDiagnosticMessageText(configFile.error.messageText, "\n")}`
+      );
+    }
+    const parsed = ts4.parseJsonConfigFileContent(
+      configFile.config,
+      ts4.sys,
+      path.dirname(configPath)
+    );
+    if (parsed.errors.length > 0) {
+      const errorMessages = parsed.errors.map((e) => ts4.flattenDiagnosticMessageText(e.messageText, "\n")).join("\n");
+      throw new Error(`Error parsing tsconfig.json: ${errorMessages}`);
+    }
+    compilerOptions = parsed.options;
+    fileNames = parsed.fileNames.includes(absolutePath) ? parsed.fileNames : [...parsed.fileNames, absolutePath];
+  } else {
+    compilerOptions = {
+      target: ts4.ScriptTarget.ES2022,
+      module: ts4.ModuleKind.NodeNext,
+      moduleResolution: ts4.ModuleResolutionKind.NodeNext,
+      strict: true,
+      skipLibCheck: true,
+      declaration: true
+    };
+    fileNames = [absolutePath];
+  }
+  const program = ts4.createProgram(fileNames, compilerOptions);
+  const sourceFile = program.getSourceFile(absolutePath);
+  if (!sourceFile) {
+    throw new Error(`Could not find source file: ${absolutePath}`);
+  }
+  return {
+    program,
+    checker: program.getTypeChecker(),
+    sourceFile
+  };
+}
+function findNodeByName(sourceFile, name, predicate, getName) {
+  let result = null;
+  function visit(node) {
+    if (result) return;
+    if (predicate(node) && getName(node) === name) {
+      result = node;
+      return;
+    }
+    ts4.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return result;
+}
+function findClassByName(sourceFile, className) {
+  return findNodeByName(sourceFile, className, ts4.isClassDeclaration, (n) => n.name?.text);
+}
+function findInterfaceByName(sourceFile, interfaceName) {
+  return findNodeByName(sourceFile, interfaceName, ts4.isInterfaceDeclaration, (n) => n.name.text);
+}
+function findTypeAliasByName(sourceFile, aliasName) {
+  return findNodeByName(sourceFile, aliasName, ts4.isTypeAliasDeclaration, (n) => n.name.text);
+}
+function analyzeNamedTypeToIR(filePath, typeName, extensionRegistry) {
+  const ctx = createProgramContext(filePath);
+  const classDecl = findClassByName(ctx.sourceFile, typeName);
+  if (classDecl !== null) {
+    return analyzeClassToIR(classDecl, ctx.checker, filePath, extensionRegistry);
+  }
+  const interfaceDecl = findInterfaceByName(ctx.sourceFile, typeName);
+  if (interfaceDecl !== null) {
+    return analyzeInterfaceToIR(interfaceDecl, ctx.checker, filePath, extensionRegistry);
+  }
+  const typeAlias = findTypeAliasByName(ctx.sourceFile, typeName);
+  if (typeAlias !== null) {
+    const result = analyzeTypeAliasToIR(typeAlias, ctx.checker, filePath, extensionRegistry);
+    if (result.ok) {
+      return result.analysis;
+    }
+    throw new Error(result.error);
+  }
+  throw new Error(
+    `Type "${typeName}" not found as a class, interface, or type alias in ${filePath}`
+  );
+}
+
+// src/validate/constraint-validator.ts
+import { normalizeConstraintTagName as normalizeConstraintTagName2 } from "@formspec/core";
+function addContradiction(ctx, message, primary, related) {
+  ctx.diagnostics.push({
+    code: "CONTRADICTING_CONSTRAINTS",
+    message,
+    severity: "error",
+    primaryLocation: primary,
+    relatedLocations: [related]
+  });
+}
+function addTypeMismatch(ctx, message, primary) {
+  ctx.diagnostics.push({
+    code: "TYPE_MISMATCH",
+    message,
+    severity: "error",
+    primaryLocation: primary,
+    relatedLocations: []
+  });
+}
+function addUnknownExtension(ctx, message, primary) {
+  ctx.diagnostics.push({
+    code: "UNKNOWN_EXTENSION",
+    message,
+    severity: "warning",
+    primaryLocation: primary,
+    relatedLocations: []
+  });
+}
+function addUnknownPathTarget(ctx, message, primary) {
+  ctx.diagnostics.push({
+    code: "UNKNOWN_PATH_TARGET",
+    message,
+    severity: "error",
+    primaryLocation: primary,
+    relatedLocations: []
+  });
+}
+function addConstraintBroadening(ctx, message, primary, related) {
+  ctx.diagnostics.push({
+    code: "CONSTRAINT_BROADENING",
+    message,
+    severity: "error",
+    primaryLocation: primary,
+    relatedLocations: [related]
+  });
+}
+function getExtensionIdFromConstraintId(constraintId) {
+  const separator = constraintId.lastIndexOf("/");
+  if (separator <= 0) {
+    return null;
+  }
+  return constraintId.slice(0, separator);
+}
+function findNumeric(constraints, constraintKind) {
+  return constraints.find((c) => c.constraintKind === constraintKind);
+}
+function findLength(constraints, constraintKind) {
+  return constraints.find((c) => c.constraintKind === constraintKind);
+}
+function findAllowedMembers(constraints) {
+  return constraints.filter(
+    (c) => c.constraintKind === "allowedMembers"
+  );
+}
+function findConstConstraints(constraints) {
+  return constraints.filter(
+    (c) => c.constraintKind === "const"
+  );
+}
+function jsonValueEquals(left, right) {
+  if (left === right) {
+    return true;
+  }
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) {
+      return false;
+    }
+    return left.every((item, index) => jsonValueEquals(item, right[index]));
+  }
+  if (isJsonObject(left) || isJsonObject(right)) {
+    if (!isJsonObject(left) || !isJsonObject(right)) {
+      return false;
+    }
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    if (leftKeys.length !== rightKeys.length) {
+      return false;
+    }
+    return leftKeys.every((key, index) => {
+      const rightKey = rightKeys[index];
+      if (rightKey !== key) {
+        return false;
+      }
+      const leftValue = left[key];
+      const rightValue = right[rightKey];
+      return leftValue !== void 0 && rightValue !== void 0 && jsonValueEquals(leftValue, rightValue);
+    });
+  }
+  return false;
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOrderedBoundConstraint(constraint) {
+  return constraint.constraintKind === "minimum" || constraint.constraintKind === "exclusiveMinimum" || constraint.constraintKind === "minLength" || constraint.constraintKind === "minItems" || constraint.constraintKind === "maximum" || constraint.constraintKind === "exclusiveMaximum" || constraint.constraintKind === "maxLength" || constraint.constraintKind === "maxItems";
+}
+function pathKey(constraint) {
+  return constraint.path?.segments.join(".") ?? "";
+}
+function orderedBoundFamily(kind) {
+  switch (kind) {
+    case "minimum":
+    case "exclusiveMinimum":
+      return "numeric-lower";
+    case "maximum":
+    case "exclusiveMaximum":
+      return "numeric-upper";
+    case "minLength":
+      return "minLength";
+    case "minItems":
+      return "minItems";
+    case "maxLength":
+      return "maxLength";
+    case "maxItems":
+      return "maxItems";
+    default: {
+      const _exhaustive = kind;
+      return _exhaustive;
+    }
+  }
+}
+function isNumericLowerKind(kind) {
+  return kind === "minimum" || kind === "exclusiveMinimum";
+}
+function isNumericUpperKind(kind) {
+  return kind === "maximum" || kind === "exclusiveMaximum";
+}
+function describeConstraintTag(constraint) {
+  return `@${constraint.constraintKind}`;
+}
+function compareConstraintStrength(current, previous) {
+  const family = orderedBoundFamily(current.constraintKind);
+  if (family === "numeric-lower") {
+    if (!isNumericLowerKind(current.constraintKind) || !isNumericLowerKind(previous.constraintKind)) {
+      throw new Error("numeric-lower family received non-numeric lower-bound constraint");
+    }
+    if (current.value !== previous.value) {
+      return current.value > previous.value ? 1 : -1;
+    }
+    if (current.constraintKind === "exclusiveMinimum" && previous.constraintKind === "minimum") {
+      return 1;
+    }
+    if (current.constraintKind === "minimum" && previous.constraintKind === "exclusiveMinimum") {
+      return -1;
+    }
+    return 0;
+  }
+  if (family === "numeric-upper") {
+    if (!isNumericUpperKind(current.constraintKind) || !isNumericUpperKind(previous.constraintKind)) {
+      throw new Error("numeric-upper family received non-numeric upper-bound constraint");
+    }
+    if (current.value !== previous.value) {
+      return current.value < previous.value ? 1 : -1;
+    }
+    if (current.constraintKind === "exclusiveMaximum" && previous.constraintKind === "maximum") {
+      return 1;
+    }
+    if (current.constraintKind === "maximum" && previous.constraintKind === "exclusiveMaximum") {
+      return -1;
+    }
+    return 0;
+  }
+  switch (family) {
+    case "minLength":
+    case "minItems":
+      if (current.value === previous.value) {
+        return 0;
+      }
+      return current.value > previous.value ? 1 : -1;
+    case "maxLength":
+    case "maxItems":
+      if (current.value === previous.value) {
+        return 0;
+      }
+      return current.value < previous.value ? 1 : -1;
+    default: {
+      const _exhaustive = family;
+      return _exhaustive;
+    }
+  }
+}
+function checkConstraintBroadening(ctx, fieldName, constraints) {
+  const strongestByKey = /* @__PURE__ */ new Map();
+  for (const constraint of constraints) {
+    if (!isOrderedBoundConstraint(constraint)) {
+      continue;
+    }
+    const key = `${orderedBoundFamily(constraint.constraintKind)}:${pathKey(constraint)}`;
+    const previous = strongestByKey.get(key);
+    if (previous === void 0) {
+      strongestByKey.set(key, constraint);
+      continue;
+    }
+    const strength = compareConstraintStrength(constraint, previous);
+    if (strength < 0) {
+      const displayFieldName = formatPathTargetFieldName(
+        fieldName,
+        constraint.path?.segments ?? []
+      );
+      addConstraintBroadening(
+        ctx,
+        `Field "${displayFieldName}": ${describeConstraintTag(constraint)} (${String(constraint.value)}) is broader than earlier ${describeConstraintTag(previous)} (${String(previous.value)}). Constraints can only narrow.`,
+        constraint.provenance,
+        previous.provenance
+      );
+      continue;
+    }
+    if (strength <= 0) {
+      continue;
+    }
+    strongestByKey.set(key, constraint);
+  }
+}
+function compareCustomConstraintStrength(current, previous) {
+  const order = current.comparePayloads(current.constraint.payload, previous.constraint.payload);
+  const equalPayloadTiebreaker = order === 0 ? compareSemanticInclusivity(current.role.inclusive, previous.role.inclusive) : order;
+  switch (current.role.bound) {
+    case "lower":
+      return equalPayloadTiebreaker;
+    case "upper":
+      return equalPayloadTiebreaker === 0 ? 0 : -equalPayloadTiebreaker;
+    case "exact":
+      return order === 0 ? 0 : Number.NaN;
+    default: {
+      const _exhaustive = current.role.bound;
+      return _exhaustive;
+    }
+  }
+}
+function compareSemanticInclusivity(currentInclusive, previousInclusive) {
+  if (currentInclusive === previousInclusive) {
+    return 0;
+  }
+  return currentInclusive ? -1 : 1;
+}
+function customConstraintsContradict(lower, upper) {
+  const order = lower.comparePayloads(lower.constraint.payload, upper.constraint.payload);
+  if (order > 0) {
+    return true;
+  }
+  if (order < 0) {
+    return false;
+  }
+  return !lower.role.inclusive || !upper.role.inclusive;
+}
+function describeCustomConstraintTag(constraint) {
+  return constraint.provenance.tagName ?? constraint.constraintId;
+}
+function checkCustomConstraintSemantics(ctx, fieldName, constraints) {
+  if (ctx.extensionRegistry === void 0) {
+    return;
+  }
+  const strongestByKey = /* @__PURE__ */ new Map();
+  const lowerByFamily = /* @__PURE__ */ new Map();
+  const upperByFamily = /* @__PURE__ */ new Map();
+  for (const constraint of constraints) {
+    if (constraint.constraintKind !== "custom") {
+      continue;
+    }
+    const registration = ctx.extensionRegistry.findConstraint(constraint.constraintId);
+    if (registration?.comparePayloads === void 0 || registration.semanticRole === void 0) {
+      continue;
+    }
+    const entry = {
+      constraint,
+      comparePayloads: registration.comparePayloads,
+      role: registration.semanticRole
+    };
+    const familyKey = `${registration.semanticRole.family}:${pathKey(constraint)}`;
+    const boundKey = `${familyKey}:${registration.semanticRole.bound}`;
+    const previous = strongestByKey.get(boundKey);
+    if (previous !== void 0) {
+      const strength = compareCustomConstraintStrength(entry, previous);
+      if (Number.isNaN(strength)) {
+        addContradiction(
+          ctx,
+          `Field "${formatPathTargetFieldName(fieldName, constraint.path?.segments ?? [])}": ${describeCustomConstraintTag(constraint)} conflicts with ${describeCustomConstraintTag(previous.constraint)}`,
+          constraint.provenance,
+          previous.constraint.provenance
+        );
+        continue;
+      }
+      if (strength < 0) {
+        addConstraintBroadening(
+          ctx,
+          `Field "${formatPathTargetFieldName(fieldName, constraint.path?.segments ?? [])}": ${describeCustomConstraintTag(constraint)} is broader than earlier ${describeCustomConstraintTag(previous.constraint)}. Constraints can only narrow.`,
+          constraint.provenance,
+          previous.constraint.provenance
+        );
+        continue;
+      }
+      if (strength > 0) {
+        strongestByKey.set(boundKey, entry);
+      }
+    } else {
+      strongestByKey.set(boundKey, entry);
+    }
+    if (registration.semanticRole.bound === "lower") {
+      lowerByFamily.set(familyKey, strongestByKey.get(boundKey) ?? entry);
+    } else if (registration.semanticRole.bound === "upper") {
+      upperByFamily.set(familyKey, strongestByKey.get(boundKey) ?? entry);
+    }
+  }
+  for (const [familyKey, lower] of lowerByFamily) {
+    const upper = upperByFamily.get(familyKey);
+    if (upper === void 0) {
+      continue;
+    }
+    if (!customConstraintsContradict(lower, upper)) {
+      continue;
+    }
+    addContradiction(
+      ctx,
+      `Field "${formatPathTargetFieldName(fieldName, lower.constraint.path?.segments ?? [])}": ${describeCustomConstraintTag(lower.constraint)} contradicts ${describeCustomConstraintTag(upper.constraint)}`,
+      lower.constraint.provenance,
+      upper.constraint.provenance
+    );
+  }
+}
+function checkNumericContradictions(ctx, fieldName, constraints) {
+  const min = findNumeric(constraints, "minimum");
+  const max = findNumeric(constraints, "maximum");
+  const exMin = findNumeric(constraints, "exclusiveMinimum");
+  const exMax = findNumeric(constraints, "exclusiveMaximum");
+  if (min !== void 0 && max !== void 0 && min.value > max.value) {
+    addContradiction(
+      ctx,
+      `Field "${fieldName}": minimum (${String(min.value)}) is greater than maximum (${String(max.value)})`,
+      min.provenance,
+      max.provenance
+    );
+  }
+  if (exMin !== void 0 && max !== void 0 && exMin.value >= max.value) {
+    addContradiction(
+      ctx,
+      `Field "${fieldName}": exclusiveMinimum (${String(exMin.value)}) is greater than or equal to maximum (${String(max.value)})`,
+      exMin.provenance,
+      max.provenance
+    );
+  }
+  if (min !== void 0 && exMax !== void 0 && min.value >= exMax.value) {
+    addContradiction(
+      ctx,
+      `Field "${fieldName}": minimum (${String(min.value)}) is greater than or equal to exclusiveMaximum (${String(exMax.value)})`,
+      min.provenance,
+      exMax.provenance
+    );
+  }
+  if (exMin !== void 0 && exMax !== void 0 && exMin.value >= exMax.value) {
+    addContradiction(
+      ctx,
+      `Field "${fieldName}": exclusiveMinimum (${String(exMin.value)}) is greater than or equal to exclusiveMaximum (${String(exMax.value)})`,
+      exMin.provenance,
+      exMax.provenance
+    );
+  }
+}
+function checkLengthContradictions(ctx, fieldName, constraints) {
+  const minLen = findLength(constraints, "minLength");
+  const maxLen = findLength(constraints, "maxLength");
+  if (minLen !== void 0 && maxLen !== void 0 && minLen.value > maxLen.value) {
+    addContradiction(
+      ctx,
+      `Field "${fieldName}": minLength (${String(minLen.value)}) is greater than maxLength (${String(maxLen.value)})`,
+      minLen.provenance,
+      maxLen.provenance
+    );
+  }
+  const minItems = findLength(constraints, "minItems");
+  const maxItems = findLength(constraints, "maxItems");
+  if (minItems !== void 0 && maxItems !== void 0 && minItems.value > maxItems.value) {
+    addContradiction(
+      ctx,
+      `Field "${fieldName}": minItems (${String(minItems.value)}) is greater than maxItems (${String(maxItems.value)})`,
+      minItems.provenance,
+      maxItems.provenance
+    );
+  }
+}
+function checkAllowedMembersContradiction(ctx, fieldName, constraints) {
+  const members = findAllowedMembers(constraints);
+  if (members.length < 2) return;
+  const firstSet = new Set(members[0]?.members ?? []);
+  for (let i = 1; i < members.length; i++) {
+    const current = members[i];
+    if (current === void 0) continue;
+    for (const m of firstSet) {
+      if (!current.members.includes(m)) {
+        firstSet.delete(m);
+      }
+    }
+  }
+  if (firstSet.size === 0) {
+    const first = members[0];
+    const second = members[1];
+    if (first !== void 0 && second !== void 0) {
+      addContradiction(
+        ctx,
+        `Field "${fieldName}": allowedMembers constraints have an empty intersection (no valid values remain)`,
+        first.provenance,
+        second.provenance
+      );
+    }
+  }
+}
+function checkConstContradictions(ctx, fieldName, constraints) {
+  const constConstraints = findConstConstraints(constraints);
+  if (constConstraints.length < 2) return;
+  const first = constConstraints[0];
+  if (first === void 0) return;
+  for (let i = 1; i < constConstraints.length; i++) {
+    const current = constConstraints[i];
+    if (current === void 0) continue;
+    if (jsonValueEquals(first.value, current.value)) {
+      continue;
+    }
+    addContradiction(
+      ctx,
+      `Field "${fieldName}": conflicting @const constraints require both ${JSON.stringify(first.value)} and ${JSON.stringify(current.value)}`,
+      first.provenance,
+      current.provenance
+    );
+  }
+}
+function typeLabel(type) {
+  switch (type.kind) {
+    case "primitive":
+      return type.primitiveKind;
+    case "enum":
+      return "enum";
+    case "array":
+      return "array";
+    case "object":
+      return "object";
+    case "record":
+      return "record";
+    case "union":
+      return "union";
+    case "reference":
+      return `reference(${type.name})`;
+    case "dynamic":
+      return `dynamic(${type.dynamicKind})`;
+    case "custom":
+      return `custom(${type.typeId})`;
+    default: {
+      const _exhaustive = type;
+      return String(_exhaustive);
+    }
+  }
+}
+function dereferenceType(ctx, type) {
+  let current = type;
+  const seen = /* @__PURE__ */ new Set();
+  while (current.kind === "reference") {
+    if (seen.has(current.name)) {
+      return current;
+    }
+    seen.add(current.name);
+    const definition = ctx.typeRegistry[current.name];
+    if (definition === void 0) {
+      return current;
+    }
+    current = definition.type;
+  }
+  return current;
+}
+function collectReferencedTypeConstraints(ctx, type) {
+  const collected = [];
+  let current = type;
+  const seen = /* @__PURE__ */ new Set();
+  while (current.kind === "reference") {
+    if (seen.has(current.name)) {
+      break;
+    }
+    seen.add(current.name);
+    const definition = ctx.typeRegistry[current.name];
+    if (definition === void 0) {
+      break;
+    }
+    if (definition.constraints !== void 0) {
+      collected.push(...definition.constraints);
+    }
+    current = definition.type;
+  }
+  return collected;
+}
+function resolvePathTargetType(ctx, type, segments) {
+  const effectiveType = dereferenceType(ctx, type);
+  if (segments.length === 0) {
+    return { kind: "resolved", type: effectiveType };
+  }
+  if (effectiveType.kind === "array") {
+    return resolvePathTargetType(ctx, effectiveType.items, segments);
+  }
+  if (effectiveType.kind === "object") {
+    const [segment, ...rest] = segments;
+    if (segment === void 0) {
+      throw new Error("Invariant violation: object path traversal requires a segment");
+    }
+    const property = effectiveType.properties.find((prop) => prop.name === segment);
+    if (property === void 0) {
+      return { kind: "missing-property", segment };
+    }
+    return resolvePathTargetType(ctx, property.type, rest);
+  }
+  return { kind: "unresolvable", type: effectiveType };
+}
+function isNullType(type) {
+  return type.kind === "primitive" && type.primitiveKind === "null";
+}
+function collectCustomConstraintCandidateTypes(ctx, type) {
+  const effectiveType = dereferenceType(ctx, type);
+  const candidates = [effectiveType];
+  if (effectiveType.kind === "array") {
+    candidates.push(...collectCustomConstraintCandidateTypes(ctx, effectiveType.items));
+  }
+  if (effectiveType.kind === "union") {
+    const memberTypes = effectiveType.members.map((member) => dereferenceType(ctx, member));
+    const nonNullMembers = memberTypes.filter((member) => !isNullType(member));
+    if (nonNullMembers.length === 1 && nonNullMembers.length < memberTypes.length) {
+      const [nullableMember] = nonNullMembers;
+      if (nullableMember !== void 0) {
+        candidates.push(...collectCustomConstraintCandidateTypes(ctx, nullableMember));
+      }
+    }
+  }
+  return candidates;
+}
+function formatPathTargetFieldName(fieldName, path3) {
+  return path3.length === 0 ? fieldName : `${fieldName}.${path3.join(".")}`;
+}
+function checkConstraintOnType(ctx, fieldName, type, constraint) {
+  const effectiveType = dereferenceType(ctx, type);
+  const isNumber = effectiveType.kind === "primitive" && ["number", "integer", "bigint"].includes(effectiveType.primitiveKind);
+  const isString = effectiveType.kind === "primitive" && effectiveType.primitiveKind === "string";
+  const isArray = effectiveType.kind === "array";
+  const isEnum = effectiveType.kind === "enum";
+  const arrayItemType = effectiveType.kind === "array" ? dereferenceType(ctx, effectiveType.items) : void 0;
+  const isStringArray = arrayItemType?.kind === "primitive" && arrayItemType.primitiveKind === "string";
+  const label = typeLabel(effectiveType);
+  const ck = constraint.constraintKind;
+  switch (ck) {
+    case "minimum":
+    case "maximum":
+    case "exclusiveMinimum":
+    case "exclusiveMaximum":
+    case "multipleOf": {
+      if (!isNumber) {
+        addTypeMismatch(
+          ctx,
+          `Field "${fieldName}": constraint "${ck}" is only valid on number fields, but field type is "${label}"`,
+          constraint.provenance
+        );
+      }
+      break;
+    }
+    case "minLength":
+    case "maxLength":
+    case "pattern": {
+      if (!isString && !isStringArray) {
+        addTypeMismatch(
+          ctx,
+          `Field "${fieldName}": constraint "${ck}" is only valid on string fields or string array items, but field type is "${label}"`,
+          constraint.provenance
+        );
+      }
+      break;
+    }
+    case "minItems":
+    case "maxItems":
+    case "uniqueItems": {
+      if (!isArray) {
+        addTypeMismatch(
+          ctx,
+          `Field "${fieldName}": constraint "${ck}" is only valid on array fields, but field type is "${label}"`,
+          constraint.provenance
+        );
+      }
+      break;
+    }
+    case "allowedMembers": {
+      if (!isEnum) {
+        addTypeMismatch(
+          ctx,
+          `Field "${fieldName}": constraint "allowedMembers" is only valid on enum fields, but field type is "${label}"`,
+          constraint.provenance
+        );
+      }
+      break;
+    }
+    case "const": {
+      const isPrimitiveConstType = effectiveType.kind === "primitive" && ["string", "number", "integer", "bigint", "boolean", "null"].includes(
+        effectiveType.primitiveKind
+      ) || effectiveType.kind === "enum";
+      if (!isPrimitiveConstType) {
+        addTypeMismatch(
+          ctx,
+          `Field "${fieldName}": constraint "const" is only valid on primitive or enum fields, but field type is "${label}"`,
+          constraint.provenance
+        );
+        break;
+      }
+      if (effectiveType.kind === "primitive") {
+        const valueType = constraint.value === null ? "null" : Array.isArray(constraint.value) ? "array" : typeof constraint.value;
+        const expectedValueType = effectiveType.primitiveKind === "integer" || effectiveType.primitiveKind === "bigint" ? "number" : effectiveType.primitiveKind;
+        if (valueType !== expectedValueType) {
+          addTypeMismatch(
+            ctx,
+            `Field "${fieldName}": @const value type "${valueType}" is incompatible with field type "${effectiveType.primitiveKind}"`,
+            constraint.provenance
+          );
+        }
+        break;
+      }
+      const memberValues = effectiveType.members.map((member) => member.value);
+      if (!memberValues.some((member) => jsonValueEquals(member, constraint.value))) {
+        addTypeMismatch(
+          ctx,
+          `Field "${fieldName}": @const value ${JSON.stringify(constraint.value)} is not one of the enum members`,
+          constraint.provenance
+        );
+      }
+      break;
+    }
+    case "custom": {
+      checkCustomConstraint(ctx, fieldName, effectiveType, constraint);
+      break;
+    }
+    default: {
+      const _exhaustive = constraint;
+      throw new Error(
+        `Unhandled constraint kind: ${_exhaustive.constraintKind}`
+      );
+    }
+  }
+}
+function checkTypeApplicability(ctx, fieldName, type, constraints) {
+  for (const constraint of constraints) {
+    if (constraint.path) {
+      const resolution = resolvePathTargetType(ctx, type, constraint.path.segments);
+      const targetFieldName = formatPathTargetFieldName(fieldName, constraint.path.segments);
+      if (resolution.kind === "missing-property") {
+        addUnknownPathTarget(
+          ctx,
+          `Field "${targetFieldName}": path-targeted constraint "${constraint.constraintKind}" references unknown path segment "${resolution.segment}"`,
+          constraint.provenance
+        );
+        continue;
+      }
+      if (resolution.kind === "unresolvable") {
+        addTypeMismatch(
+          ctx,
+          `Field "${targetFieldName}": path-targeted constraint "${constraint.constraintKind}" is invalid because type "${typeLabel(resolution.type)}" cannot be traversed`,
+          constraint.provenance
+        );
+        continue;
+      }
+      checkConstraintOnType(ctx, targetFieldName, resolution.type, constraint);
+      continue;
+    }
+    checkConstraintOnType(ctx, fieldName, type, constraint);
+  }
+}
+function checkCustomConstraint(ctx, fieldName, type, constraint) {
+  if (ctx.extensionRegistry === void 0) return;
+  const registration = ctx.extensionRegistry.findConstraint(constraint.constraintId);
+  if (registration === void 0) {
+    addUnknownExtension(
+      ctx,
+      `Field "${fieldName}": custom constraint "${constraint.constraintId}" is not registered in the extension registry`,
+      constraint.provenance
+    );
+    return;
+  }
+  const candidateTypes = collectCustomConstraintCandidateTypes(ctx, type);
+  const normalizedTagName = constraint.provenance.tagName === void 0 ? void 0 : normalizeConstraintTagName2(constraint.provenance.tagName.replace(/^@/, ""));
+  if (normalizedTagName !== void 0) {
+    const tagRegistration = ctx.extensionRegistry.findConstraintTag(normalizedTagName);
+    const extensionId = getExtensionIdFromConstraintId(constraint.constraintId);
+    if (extensionId !== null && tagRegistration?.extensionId === extensionId && tagRegistration.registration.constraintName === registration.constraintName && !candidateTypes.some(
+      (candidateType) => tagRegistration.registration.isApplicableToType?.(candidateType) !== false
+    )) {
+      addTypeMismatch(
+        ctx,
+        `Field "${fieldName}": custom constraint "${constraint.constraintId}" is not applicable to type "${typeLabel(type)}"`,
+        constraint.provenance
+      );
+      return;
+    }
+  }
+  if (registration.applicableTypes === null) {
+    if (!candidateTypes.some((candidateType) => registration.isApplicableToType?.(candidateType) !== false)) {
+      addTypeMismatch(
+        ctx,
+        `Field "${fieldName}": custom constraint "${constraint.constraintId}" is not applicable to type "${typeLabel(type)}"`,
+        constraint.provenance
+      );
+    }
+    return;
+  }
+  const applicableTypes = registration.applicableTypes;
+  const matchesApplicableType = candidateTypes.some(
+    (candidateType) => applicableTypes.includes(candidateType.kind) && registration.isApplicableToType?.(candidateType) !== false
+  );
+  if (!matchesApplicableType) {
+    addTypeMismatch(
+      ctx,
+      `Field "${fieldName}": custom constraint "${constraint.constraintId}" is not applicable to type "${typeLabel(type)}"`,
+      constraint.provenance
+    );
+  }
+}
+function validateFieldNode(ctx, field) {
+  validateConstraints(ctx, field.name, field.type, [
+    ...collectReferencedTypeConstraints(ctx, field.type),
+    ...field.constraints
+  ]);
+  if (field.type.kind === "object") {
+    for (const prop of field.type.properties) {
+      validateObjectProperty(ctx, field.name, prop);
+    }
+  }
+}
+function validateObjectProperty(ctx, parentName, prop) {
+  const qualifiedName = `${parentName}.${prop.name}`;
+  validateConstraints(ctx, qualifiedName, prop.type, [
+    ...collectReferencedTypeConstraints(ctx, prop.type),
+    ...prop.constraints
+  ]);
+  if (prop.type.kind === "object") {
+    for (const nestedProp of prop.type.properties) {
+      validateObjectProperty(ctx, qualifiedName, nestedProp);
+    }
+  }
+}
+function validateConstraints(ctx, name, type, constraints) {
+  checkNumericContradictions(ctx, name, constraints);
+  checkLengthContradictions(ctx, name, constraints);
+  checkAllowedMembersContradiction(ctx, name, constraints);
+  checkConstContradictions(ctx, name, constraints);
+  checkConstraintBroadening(ctx, name, constraints);
+  checkCustomConstraintSemantics(ctx, name, constraints);
+  checkTypeApplicability(ctx, name, type, constraints);
+}
+function validateElement(ctx, element) {
+  switch (element.kind) {
+    case "field":
+      validateFieldNode(ctx, element);
+      break;
+    case "group":
+      for (const child of element.elements) {
+        validateElement(ctx, child);
+      }
+      break;
+    case "conditional":
+      for (const child of element.elements) {
+        validateElement(ctx, child);
+      }
+      break;
+    default: {
+      const _exhaustive = element;
+      throw new Error(`Unhandled element kind: ${_exhaustive.kind}`);
+    }
+  }
+}
+function validateIR(ir, options) {
+  const ctx = {
+    diagnostics: [],
+    extensionRegistry: options?.extensionRegistry,
+    typeRegistry: ir.typeRegistry
+  };
+  for (const element of ir.elements) {
+    validateElement(ctx, element);
+  }
+  return {
+    diagnostics: ctx.diagnostics,
+    valid: ctx.diagnostics.every((d) => d.severity !== "error")
+  };
+}
+
 // src/generators/class-schema.ts
-function generateClassSchemas(analysis, source) {
+function generateClassSchemas(analysis, source, options) {
   const ir = canonicalizeTSDoc(analysis, source);
+  const validationResult = validateIR(ir, {
+    ...options?.extensionRegistry !== void 0 && {
+      extensionRegistry: options.extensionRegistry
+    },
+    ...options?.vendorPrefix !== void 0 && { vendorPrefix: options.vendorPrefix }
+  });
+  if (!validationResult.valid) {
+    throw new Error(formatValidationError(validationResult.diagnostics));
+  }
   return {
-    jsonSchema: generateJsonSchemaFromIR(ir),
+    jsonSchema: generateJsonSchemaFromIR(ir, options),
     uiSchema: generateUiSchemaFromIR(ir)
   };
 }
+function formatValidationError(diagnostics) {
+  const lines = diagnostics.map((diagnostic) => {
+    const primary = formatLocation(diagnostic.primaryLocation);
+    const related = diagnostic.relatedLocations.length > 0 ? ` [related: ${diagnostic.relatedLocations.map(formatLocation).join(", ")}]` : "";
+    return `${diagnostic.code}: ${diagnostic.message} (${primary})${related}`;
+  });
+  return `FormSpec validation failed:
+${lines.map((line) => `- ${line}`).join("\n")}`;
+}
+function formatLocation(location) {
+  return `${location.file}:${String(location.line)}:${String(location.column)}`;
+}
 function generateSchemasFromClass(options) {
   const ctx = createProgramContext(options.filePath);
   const classDecl = findClassByName(ctx.sourceFile, options.className);
   if (!classDecl) {
     throw new Error(`Class "${options.className}" not found in ${options.filePath}`);
   }
-  const analysis = analyzeClassToIR(classDecl, ctx.checker, options.filePath);
-  return generateClassSchemas(analysis, { file: options.filePath });
+  const analysis = analyzeClassToIR(
+    classDecl,
+    ctx.checker,
+    options.filePath,
+    options.extensionRegistry
+  );
+  return generateClassSchemas(
+    analysis,
+    { file: options.filePath },
+    {
+      extensionRegistry: options.extensionRegistry,
+      vendorPrefix: options.vendorPrefix
+    }
+  );
 }
 function generateSchemas(options) {
-  const ctx = createProgramContext(options.filePath);
-  const source = { file: options.filePath };
-  const classDecl = findClassByName(ctx.sourceFile, options.typeName);
-  if (classDecl) {
-    const analysis = analyzeClassToIR(classDecl, ctx.checker, options.filePath);
-    return generateClassSchemas(analysis, source);
-  }
-  const interfaceDecl = findInterfaceByName(ctx.sourceFile, options.typeName);
-  if (interfaceDecl) {
-    const analysis = analyzeInterfaceToIR(interfaceDecl, ctx.checker, options.filePath);
-    return generateClassSchemas(analysis, source);
-  }
-  const typeAlias = findTypeAliasByName(ctx.sourceFile, options.typeName);
-  if (typeAlias) {
-    const result = analyzeTypeAliasToIR(typeAlias, ctx.checker, options.filePath);
-    if (result.ok) {
-      return generateClassSchemas(result.analysis, source);
-    }
-    throw new Error(result.error);
-  }
-  throw new Error(
-    `Type "${options.typeName}" not found as a class, interface, or type alias in ${options.filePath}`
+  const analysis = analyzeNamedTypeToIR(
+    options.filePath,
+    options.typeName,
+    options.extensionRegistry
   );
+  return generateClassSchemas(analysis, { file: options.filePath }, options);
 }
 
 // src/generators/mixed-authoring.ts
 function buildMixedAuthoringSchemas(options) {
   const { filePath, typeName, overlays, ...schemaOptions } = options;
-  const analysis = analyzeNamedType(filePath, typeName);
+  const analysis = analyzeNamedTypeToIR(filePath, typeName, schemaOptions.extensionRegistry);
   const composedAnalysis = composeAnalysisWithOverlays(analysis, overlays);
   const ir = canonicalizeTSDoc(composedAnalysis, { file: filePath });
   return {
@@ -2395,29 +3762,6 @@ function buildMixedAuthoringSchemas(options) {
     uiSchema: generateUiSchemaFromIR(ir)
   };
 }
-function analyzeNamedType(filePath, typeName) {
-  const ctx = createProgramContext(filePath);
-  const source = { file: filePath };
-  const classDecl = findClassByName(ctx.sourceFile, typeName);
-  if (classDecl !== null) {
-    return analyzeClassToIR(classDecl, ctx.checker, source.file);
-  }
-  const interfaceDecl = findInterfaceByName(ctx.sourceFile, typeName);
-  if (interfaceDecl !== null) {
-    return analyzeInterfaceToIR(interfaceDecl, ctx.checker, source.file);
-  }
-  const typeAlias = findTypeAliasByName(ctx.sourceFile, typeName);
-  if (typeAlias !== null) {
-    const result = analyzeTypeAliasToIR(typeAlias, ctx.checker, source.file);
-    if (result.ok) {
-      return result.analysis;
-    }
-    throw new Error(result.error);
-  }
-  throw new Error(
-    `Type "${typeName}" not found as a class, interface, or type alias in ${filePath}`
-  );
-}
 function composeAnalysisWithOverlays(analysis, overlays) {
   const overlayIR = canonicalizeChainDSL(overlays);
   const overlayFields = collectOverlayFields(overlayIR.elements);
@@ -2487,7 +3831,7 @@ function assertSupportedOverlayField(baseField, overlayField) {
       `Mixed-authoring overlay for "${baseField.name}" cannot define constraints; keep constraints on the static model`
     );
   }
-  if (overlayField.required) {
+  if (overlayField.required && !baseField.required) {
     throw new Error(
       `Mixed-authoring overlay for "${baseField.name}" cannot change requiredness; keep requiredness on the static model`
     );
@@ -2577,7 +3921,7 @@ function mergeAnnotations(baseAnnotations, overlayAnnotations) {
   const overlayOnly = overlayAnnotations.filter(
     (annotation) => !baseKeys.has(annotationKey(annotation))
   );
-  return [...overlayOnly, ...baseAnnotations];
+  return [...baseAnnotations, ...overlayOnly];
 }
 function annotationKey(annotation) {
   return annotation.annotationKind === "custom" ? `${annotation.annotationKind}:${annotation.annotationId}` : annotation.annotationKind;