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

package/dist/index.cjs

@@ -31,10 +31,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   buildFormSchemas: () => buildFormSchemas,
+  buildMixedAuthoringSchemas: () => buildMixedAuthoringSchemas,
   categorizationSchema: () => categorizationSchema,
   categorySchema: () => categorySchema,
   controlSchema: () => controlSchema,
+  createExtensionRegistry: () => createExtensionRegistry,
   generateJsonSchema: () => generateJsonSchema,
+  generateJsonSchemaFromIR: () => generateJsonSchemaFromIR,
   generateSchemas: () => generateSchemas,
   generateSchemasFromClass: () => generateSchemasFromClass,
   generateUiSchema: () => generateUiSchema,
@@ -236,7 +239,7 @@ function canonicalizeArrayField(field) {
   const itemsType = {
     kind: "object",
     properties: itemProperties,
-    additionalProperties: false
+    additionalProperties: true
   };
   const type = { kind: "array", items: itemsType };
   const constraints = [];
@@ -271,7 +274,7 @@ function canonicalizeObjectField(field) {
   const type = {
     kind: "object",
     properties,
-    additionalProperties: false
+    additionalProperties: true
   };
   return buildFieldNode(field.name, type, field.required, buildAnnotations(field.label));
 }
@@ -384,6 +387,7 @@ function canonicalizeTSDoc(analysis, source) {
     irVersion: import_core2.IR_VERSION,
     elements,
     typeRegistry: analysis.typeRegistry,
+    ...analysis.annotations !== void 0 && analysis.annotations.length > 0 && { annotations: analysis.annotations },
     provenance
   };
 }
@@ -443,13 +447,26 @@ function wrapInConditional(field, layout, provenance) {
 }
 
 // src/json-schema/ir-generator.ts
-function makeContext() {
-  return { defs: {} };
+function makeContext(options) {
+  const vendorPrefix = options?.vendorPrefix ?? "x-formspec";
+  if (!vendorPrefix.startsWith("x-")) {
+    throw new Error(
+      `Invalid vendorPrefix "${vendorPrefix}". Extension JSON Schema keywords must start with "x-".`
+    );
+  }
+  return {
+    defs: {},
+    extensionRegistry: options?.extensionRegistry,
+    vendorPrefix
+  };
 }
-function generateJsonSchemaFromIR(ir) {
-  const ctx = makeContext();
+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.annotations && typeDef.annotations.length > 0) {
+      applyAnnotations(ctx.defs[name], typeDef.annotations, ctx);
+    }
   }
   const properties = {};
   const required = [];
@@ -461,6 +478,9 @@ function generateJsonSchemaFromIR(ir) {
     properties,
     ...uniqueRequired.length > 0 && { required: uniqueRequired }
   };
+  if (ir.annotations && ir.annotations.length > 0) {
+    applyAnnotations(result, ir.annotations, ctx);
+  }
   if (Object.keys(ctx.defs).length > 0) {
     result.$defs = ctx.defs;
   }
@@ -490,25 +510,54 @@ function collectFields(elements, properties, required, ctx) {
 }
 function generateFieldSchema(field, ctx) {
   const schema = generateTypeNode(field.type, ctx);
+  const itemStringSchema = schema.type === "array" && schema.items?.type === "string" ? schema.items : void 0;
   const directConstraints = [];
+  const itemConstraints = [];
   const pathConstraints = [];
   for (const c of field.constraints) {
     if (c.path) {
       pathConstraints.push(c);
+    } else if (itemStringSchema !== void 0 && isStringItemConstraint(c)) {
+      itemConstraints.push(c);
     } else {
       directConstraints.push(c);
     }
   }
-  applyConstraints(schema, directConstraints);
-  applyAnnotations(schema, field.annotations);
+  applyConstraints(schema, directConstraints, ctx);
+  if (itemStringSchema !== void 0) {
+    applyConstraints(itemStringSchema, itemConstraints, ctx);
+  }
+  const rootAnnotations = [];
+  const itemAnnotations = [];
+  for (const annotation of field.annotations) {
+    if (itemStringSchema !== void 0 && annotation.annotationKind === "format") {
+      itemAnnotations.push(annotation);
+    } else {
+      rootAnnotations.push(annotation);
+    }
+  }
+  applyAnnotations(schema, rootAnnotations, ctx);
+  if (itemStringSchema !== void 0) {
+    applyAnnotations(itemStringSchema, itemAnnotations, ctx);
+  }
   if (pathConstraints.length === 0) {
     return schema;
   }
-  return applyPathTargetedConstraints(schema, pathConstraints);
+  return applyPathTargetedConstraints(schema, pathConstraints, ctx);
 }
-function applyPathTargetedConstraints(schema, pathConstraints) {
+function isStringItemConstraint(constraint) {
+  switch (constraint.constraintKind) {
+    case "minLength":
+    case "maxLength":
+    case "pattern":
+      return true;
+    default:
+      return false;
+  }
+}
+function applyPathTargetedConstraints(schema, pathConstraints, ctx) {
   if (schema.type === "array" && schema.items) {
-    schema.items = applyPathTargetedConstraints(schema.items, pathConstraints);
+    schema.items = applyPathTargetedConstraints(schema.items, pathConstraints, ctx);
     return schema;
   }
   const byTarget = /* @__PURE__ */ new Map();
@@ -522,7 +571,7 @@ function applyPathTargetedConstraints(schema, pathConstraints) {
   const propertyOverrides = {};
   for (const [target, constraints] of byTarget) {
     const subSchema = {};
-    applyConstraints(subSchema, constraints);
+    applyConstraints(subSchema, constraints, ctx);
     propertyOverrides[target] = subSchema;
   }
   if (schema.$ref) {
@@ -566,6 +615,8 @@ function generateTypeNode(type, ctx) {
       return generateArrayType(type, ctx);
     case "object":
       return generateObjectType(type, ctx);
+    case "record":
+      return generateRecordType(type, ctx);
     case "union":
       return generateUnionType(type, ctx);
     case "reference":
@@ -573,7 +624,7 @@ function generateTypeNode(type, ctx) {
     case "dynamic":
       return generateDynamicType(type);
     case "custom":
-      return generateCustomType(type);
+      return generateCustomType(type, ctx);
     default: {
       const _exhaustive = type;
       return _exhaustive;
@@ -622,16 +673,27 @@ function generateObjectType(type, ctx) {
   }
   return schema;
 }
+function generateRecordType(type, ctx) {
+  return {
+    type: "object",
+    additionalProperties: generateTypeNode(type.valueType, ctx)
+  };
+}
 function generatePropertySchema(prop, ctx) {
   const schema = generateTypeNode(prop.type, ctx);
-  applyConstraints(schema, prop.constraints);
-  applyAnnotations(schema, prop.annotations);
+  applyConstraints(schema, prop.constraints, ctx);
+  applyAnnotations(schema, prop.annotations, ctx);
   return schema;
 }
 function generateUnionType(type, ctx) {
   if (isBooleanUnion(type)) {
     return { type: "boolean" };
   }
+  if (isNullableUnion(type)) {
+    return {
+      oneOf: type.members.map((m) => generateTypeNode(m, ctx))
+    };
+  }
   return {
     anyOf: type.members.map((m) => generateTypeNode(m, ctx))
   };
@@ -641,6 +703,13 @@ function isBooleanUnion(type) {
   const kinds = type.members.map((m) => m.kind);
   return kinds.every((k) => k === "primitive") && type.members.every((m) => m.kind === "primitive" && m.primitiveKind === "boolean");
 }
+function isNullableUnion(type) {
+  if (type.members.length !== 2) return false;
+  const nullCount = type.members.filter(
+    (m) => m.kind === "primitive" && m.primitiveKind === "null"
+  ).length;
+  return nullCount === 1;
+}
 function generateReferenceType(type) {
   return { $ref: `#/$defs/${type.name}` };
 }
@@ -661,10 +730,7 @@ function generateDynamicType(type) {
     "x-formspec-schemaSource": type.sourceKey
   };
 }
-function generateCustomType(_type) {
-  return { type: "object" };
-}
-function applyConstraints(schema, constraints) {
+function applyConstraints(schema, constraints, ctx) {
   for (const constraint of constraints) {
     switch (constraint.constraintKind) {
       case "minimum":
@@ -706,9 +772,13 @@ function applyConstraints(schema, constraints) {
       case "uniqueItems":
         schema.uniqueItems = constraint.value;
         break;
+      case "const":
+        schema.const = constraint.value;
+        break;
       case "allowedMembers":
         break;
       case "custom":
+        applyCustomConstraint(schema, constraint, ctx);
         break;
       default: {
         const _exhaustive = constraint;
@@ -717,7 +787,7 @@ function applyConstraints(schema, constraints) {
     }
   }
 }
-function applyAnnotations(schema, annotations) {
+function applyAnnotations(schema, annotations, ctx) {
   for (const annotation of annotations) {
     switch (annotation.annotationKind) {
       case "displayName":
@@ -729,14 +799,21 @@ function applyAnnotations(schema, annotations) {
       case "defaultValue":
         schema.default = annotation.value;
         break;
+      case "format":
+        schema.format = annotation.value;
+        break;
       case "deprecated":
         schema.deprecated = true;
+        if (annotation.message !== void 0 && annotation.message !== "") {
+          schema["x-formspec-deprecation-description"] = annotation.message;
+        }
         break;
       case "placeholder":
         break;
       case "formatHint":
         break;
       case "custom":
+        applyCustomAnnotation(schema, annotation, ctx);
         break;
       default: {
         const _exhaustive = annotation;
@@ -745,11 +822,41 @@ function applyAnnotations(schema, annotations) {
     }
   }
 }
+function generateCustomType(type, ctx) {
+  const registration = ctx.extensionRegistry?.findType(type.typeId);
+  if (registration === void 0) {
+    throw new Error(
+      `Cannot generate JSON Schema for custom type "${type.typeId}" without a matching extension registration`
+    );
+  }
+  return registration.toJsonSchema(type.payload, ctx.vendorPrefix);
+}
+function applyCustomConstraint(schema, constraint, ctx) {
+  const registration = ctx.extensionRegistry?.findConstraint(constraint.constraintId);
+  if (registration === void 0) {
+    throw new Error(
+      `Cannot generate JSON Schema for custom constraint "${constraint.constraintId}" without a matching extension registration`
+    );
+  }
+  Object.assign(schema, registration.toJsonSchema(constraint.payload, ctx.vendorPrefix));
+}
+function applyCustomAnnotation(schema, annotation, ctx) {
+  const registration = ctx.extensionRegistry?.findAnnotation(annotation.annotationId);
+  if (registration === void 0) {
+    throw new Error(
+      `Cannot generate JSON Schema for custom annotation "${annotation.annotationId}" without a matching extension registration`
+    );
+  }
+  if (registration.toJsonSchema === void 0) {
+    return;
+  }
+  Object.assign(schema, registration.toJsonSchema(annotation.value, ctx.vendorPrefix));
+}
 
 // src/json-schema/generator.ts
-function generateJsonSchema(form) {
+function generateJsonSchema(form, options) {
   const ir = canonicalizeChainDSL(form);
-  return generateJsonSchemaFromIR(ir);
+  return generateJsonSchemaFromIR(ir, options);
 }
 
 // src/ui-schema/schema.ts
@@ -887,25 +994,31 @@ function createShowRule(fieldName, value) {
     }
   };
 }
+function flattenConditionSchema(scope, schema) {
+  if (schema.allOf === void 0) {
+    if (scope === "#") {
+      return [schema];
+    }
+    const fieldName = scope.replace("#/properties/", "");
+    return [
+      {
+        properties: {
+          [fieldName]: schema
+        }
+      }
+    ];
+  }
+  return schema.allOf.flatMap((member) => flattenConditionSchema(scope, member));
+}
 function combineRules(parentRule, childRule) {
-  const parentCondition = parentRule.condition;
-  const childCondition = childRule.condition;
   return {
     effect: "SHOW",
     condition: {
       scope: "#",
       schema: {
         allOf: [
-          {
-            properties: {
-              [parentCondition.scope.replace("#/properties/", "")]: parentCondition.schema
-            }
-          },
-          {
-            properties: {
-              [childCondition.scope.replace("#/properties/", "")]: childCondition.schema
-            }
-          }
+          ...flattenConditionSchema(parentRule.condition.scope, parentRule.condition.schema),
+          ...flattenConditionSchema(childRule.condition.scope, childRule.condition.schema)
         ]
       }
     }
@@ -913,10 +1026,14 @@ function combineRules(parentRule, childRule) {
 }
 function fieldNodeToControl(field, parentRule) {
   const displayNameAnnotation = field.annotations.find((a) => a.annotationKind === "displayName");
+  const placeholderAnnotation = field.annotations.find((a) => a.annotationKind === "placeholder");
   const control = {
     type: "Control",
     scope: fieldToScope(field.name),
     ...displayNameAnnotation !== void 0 && { label: displayNameAnnotation.value },
+    ...placeholderAnnotation !== void 0 && {
+      options: { placeholder: placeholderAnnotation.value }
+    },
     ...parentRule !== void 0 && { rule: parentRule }
   };
   return control;
@@ -983,6 +1100,48 @@ function getSchemaExtension(schema, key) {
   return schema[key];
 }
 
+// src/extensions/registry.ts
+function createExtensionRegistry(extensions) {
+  const typeMap = /* @__PURE__ */ new Map();
+  const constraintMap = /* @__PURE__ */ new Map();
+  const annotationMap = /* @__PURE__ */ new Map();
+  for (const ext of extensions) {
+    if (ext.types !== void 0) {
+      for (const type of ext.types) {
+        const qualifiedId = `${ext.extensionId}/${type.typeName}`;
+        if (typeMap.has(qualifiedId)) {
+          throw new Error(`Duplicate custom type ID: "${qualifiedId}"`);
+        }
+        typeMap.set(qualifiedId, type);
+      }
+    }
+    if (ext.constraints !== void 0) {
+      for (const constraint of ext.constraints) {
+        const qualifiedId = `${ext.extensionId}/${constraint.constraintName}`;
+        if (constraintMap.has(qualifiedId)) {
+          throw new Error(`Duplicate custom constraint ID: "${qualifiedId}"`);
+        }
+        constraintMap.set(qualifiedId, constraint);
+      }
+    }
+    if (ext.annotations !== void 0) {
+      for (const annotation of ext.annotations) {
+        const qualifiedId = `${ext.extensionId}/${annotation.annotationName}`;
+        if (annotationMap.has(qualifiedId)) {
+          throw new Error(`Duplicate custom annotation ID: "${qualifiedId}"`);
+        }
+        annotationMap.set(qualifiedId, annotation);
+      }
+    }
+  }
+  return {
+    extensions,
+    findType: (typeId) => typeMap.get(typeId),
+    findConstraint: (constraintId) => constraintMap.get(constraintId),
+    findAnnotation: (annotationId) => annotationMap.get(annotationId)
+  };
+}
+
 // src/json-schema/schema.ts
 var import_zod3 = require("zod");
 var jsonSchemaTypeSchema = import_zod3.z.enum([
@@ -1122,7 +1281,6 @@ var ts4 = __toESM(require("typescript"), 1);
 
 // src/analyzer/jsdoc-constraints.ts
 var ts3 = __toESM(require("typescript"), 1);
-var import_core4 = require("@formspec/core");
 
 // src/analyzer/tsdoc-parser.ts
 var ts2 = __toESM(require("typescript"), 1);
@@ -1152,7 +1310,7 @@ var LENGTH_CONSTRAINT_MAP = {
   minItems: "minItems",
   maxItems: "maxItems"
 };
-var TAGS_REQUIRING_RAW_TEXT = /* @__PURE__ */ new Set(["pattern", "enumOptions"]);
+var TAGS_REQUIRING_RAW_TEXT = /* @__PURE__ */ new Set(["pattern", "enumOptions", "defaultValue"]);
 function createFormSpecTSDocConfig() {
   const config = new import_tsdoc.TSDocConfiguration();
   for (const tagName of Object.keys(import_core3.BUILTIN_CONSTRAINT_DEFINITIONS)) {
@@ -1164,6 +1322,15 @@ function createFormSpecTSDocConfig() {
       })
     );
   }
+  for (const tagName of ["displayName", "description", "format", "placeholder"]) {
+    config.addTagDefinition(
+      new import_tsdoc.TSDocTagDefinition({
+        tagName: "@" + tagName,
+        syntaxKind: import_tsdoc.TSDocTagSyntaxKind.BlockTag,
+        allowMultiple: true
+      })
+    );
+  }
   return config;
 }
 var sharedParser;
@@ -1174,6 +1341,12 @@ function getParser() {
 function parseTSDocTags(node, file = "") {
   const constraints = [];
   const annotations = [];
+  let displayName;
+  let description;
+  let placeholder;
+  let displayNameProvenance;
+  let descriptionProvenance;
+  let placeholderProvenance;
   const sourceFile = node.getSourceFile();
   const sourceText = sourceFile.getFullText();
   const commentRanges = ts2.getLeadingCommentRanges(sourceText, node.getFullStart());
@@ -1193,9 +1366,37 @@ function parseTSDocTags(node, file = "") {
       const docComment = parserContext.docComment;
       for (const block of docComment.customBlocks) {
         const tagName = (0, import_core3.normalizeConstraintTagName)(block.blockTag.tagName.substring(1));
+        if (tagName === "displayName" || tagName === "description" || tagName === "format" || tagName === "placeholder") {
+          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) {
+              description = text2;
+              descriptionProvenance = provenance2;
+            } else if (tagName === "placeholder" && placeholder === void 0) {
+              placeholder = text2;
+              placeholderProvenance = provenance2;
+            }
+          }
+          continue;
+        }
         if (TAGS_REQUIRING_RAW_TEXT.has(tagName)) continue;
         const text = extractBlockText(block).trim();
-        if (text === "") continue;
+        const expectedType = (0, import_core3.isBuiltinConstraintName)(tagName) ? import_core3.BUILTIN_CONSTRAINT_DEFINITIONS[tagName] : void 0;
+        if (text === "" && expectedType !== "boolean") continue;
         const provenance = provenanceForComment(range, sourceFile, file, tagName);
         const constraintNode = parseConstraintValue(tagName, text, provenance);
         if (constraintNode) {
@@ -1203,14 +1404,47 @@ function parseTSDocTags(node, file = "") {
         }
       }
       if (docComment.deprecatedBlock !== void 0) {
+        const message = extractBlockText(docComment.deprecatedBlock).trim();
         annotations.push({
           kind: "annotation",
           annotationKind: "deprecated",
+          ...message !== "" && { message },
           provenance: provenanceForComment(range, sourceFile, file, "deprecated")
         });
       }
+      if (description === void 0 && docComment.remarksBlock !== void 0) {
+        const remarks = extractBlockText(docComment.remarksBlock).trim();
+        if (remarks !== "") {
+          description = remarks;
+          descriptionProvenance = provenanceForComment(range, sourceFile, file, "remarks");
+        }
+      }
     }
   }
+  if (displayName !== void 0 && displayNameProvenance !== void 0) {
+    annotations.push({
+      kind: "annotation",
+      annotationKind: "displayName",
+      value: displayName,
+      provenance: displayNameProvenance
+    });
+  }
+  if (description !== void 0 && descriptionProvenance !== void 0) {
+    annotations.push({
+      kind: "annotation",
+      annotationKind: "description",
+      value: description,
+      provenance: descriptionProvenance
+    });
+  }
+  if (placeholder !== void 0 && placeholderProvenance !== void 0) {
+    annotations.push({
+      kind: "annotation",
+      annotationKind: "placeholder",
+      value: placeholder,
+      provenance: placeholderProvenance
+    });
+  }
   const jsDocTagsAll = ts2.getJSDocTags(node);
   for (const tag of jsDocTagsAll) {
     const tagName = (0, import_core3.normalizeConstraintTagName)(tag.tagName.text);
@@ -1219,47 +1453,39 @@ function parseTSDocTags(node, file = "") {
     if (commentText === void 0 || commentText.trim() === "") continue;
     const text = commentText.trim();
     const provenance = provenanceForJSDocTag(tag, file);
+    if (tagName === "defaultValue") {
+      const defaultValueNode = parseDefaultValueValue(text, provenance);
+      annotations.push(defaultValueNode);
+      continue;
+    }
     const constraintNode = parseConstraintValue(tagName, text, provenance);
     if (constraintNode) {
       constraints.push(constraintNode);
     }
   }
+  return { constraints, annotations };
+}
+function extractDisplayNameMetadata(node) {
   let displayName;
-  let description;
-  let displayNameTag;
-  let descriptionTag;
-  for (const tag of jsDocTagsAll) {
-    const tagName = tag.tagName.text;
+  const memberDisplayNames = /* @__PURE__ */ new Map();
+  for (const tag of ts2.getJSDocTags(node)) {
+    const tagName = (0, import_core3.normalizeConstraintTagName)(tag.tagName.text);
+    if (tagName !== "displayName") continue;
     const commentText = getTagCommentText(tag);
-    if (commentText === void 0 || commentText.trim() === "") {
+    if (commentText === void 0) continue;
+    const text = commentText.trim();
+    if (text === "") continue;
+    const memberTarget = parseMemberTargetDisplayName(text);
+    if (memberTarget) {
+      memberDisplayNames.set(memberTarget.target, memberTarget.label);
       continue;
     }
-    const trimmed = commentText.trim();
-    if (tagName === "Field_displayName") {
-      displayName = trimmed;
-      displayNameTag = tag;
-    } else if (tagName === "Field_description") {
-      description = trimmed;
-      descriptionTag = tag;
-    }
+    displayName ??= text;
   }
-  if (displayName !== void 0 && displayNameTag) {
-    annotations.push({
-      kind: "annotation",
-      annotationKind: "displayName",
-      value: displayName,
-      provenance: provenanceForJSDocTag(displayNameTag, file)
-    });
-  }
-  if (description !== void 0 && descriptionTag) {
-    annotations.push({
-      kind: "annotation",
-      annotationKind: "description",
-      value: description,
-      provenance: provenanceForJSDocTag(descriptionTag, file)
-    });
-  }
-  return { constraints, annotations };
+  return {
+    ...displayName !== void 0 && { displayName },
+    memberDisplayNames
+  };
 }
 function extractPathTarget(text) {
   const trimmed = text.trimStart();
@@ -1323,7 +1549,45 @@ function parseConstraintValue(tagName, text, provenance) {
     }
     return null;
   }
+  if (expectedType === "boolean") {
+    const trimmed = effectiveText.trim();
+    if (trimmed !== "" && trimmed !== "true") {
+      return null;
+    }
+    if (tagName === "uniqueItems") {
+      return {
+        kind: "constraint",
+        constraintKind: "uniqueItems",
+        value: true,
+        ...path3 && { path: path3 },
+        provenance
+      };
+    }
+    return null;
+  }
   if (expectedType === "json") {
+    if (tagName === "const") {
+      const trimmedText = effectiveText.trim();
+      if (trimmedText === "") return null;
+      try {
+        const parsed2 = JSON.parse(trimmedText);
+        return {
+          kind: "constraint",
+          constraintKind: "const",
+          value: parsed2,
+          ...path3 && { path: path3 },
+          provenance
+        };
+      } catch {
+        return {
+          kind: "constraint",
+          constraintKind: "const",
+          value: trimmedText,
+          ...path3 && { path: path3 },
+          provenance
+        };
+      }
+    }
     const parsed = tryParseJson(effectiveText);
     if (!Array.isArray(parsed)) {
       return null;
@@ -1355,6 +1619,34 @@ function parseConstraintValue(tagName, text, provenance) {
     provenance
   };
 }
+function parseDefaultValueValue(text, provenance) {
+  const trimmed = text.trim();
+  let value;
+  if (trimmed === "null") {
+    value = null;
+  } else if (trimmed === "true") {
+    value = true;
+  } else if (trimmed === "false") {
+    value = false;
+  } else {
+    const parsed = tryParseJson(trimmed);
+    value = parsed !== null ? parsed : trimmed;
+  }
+  return {
+    kind: "annotation",
+    annotationKind: "defaultValue",
+    value,
+    provenance
+  };
+}
+function isMemberTargetDisplayName(text) {
+  return parseMemberTargetDisplayName(text) !== null;
+}
+function parseMemberTargetDisplayName(text) {
+  const match = /^:([^\s]+)\s+([\s\S]+)$/.exec(text);
+  if (!match?.[1] || !match[2]) return null;
+  return { target: match[1], label: match[2].trim() };
+}
 function provenanceForComment(range, sourceFile, file, tagName) {
   const { line, character } = sourceFile.getLineAndCharacterOfPosition(range.pos);
   return {
@@ -1436,11 +1728,17 @@ function isObjectType(type) {
 function isTypeReference(type) {
   return !!(type.flags & ts4.TypeFlags.Object) && !!(type.objectFlags & ts4.ObjectFlags.Reference);
 }
+var RESOLVING_TYPE_PLACEHOLDER = {
+  kind: "object",
+  properties: [],
+  additionalProperties: true
+};
 function analyzeClassToIR(classDecl, checker, file = "") {
   const name = classDecl.name?.text ?? "AnonymousClass";
   const fields = [];
   const fieldLayouts = [];
   const typeRegistry = {};
+  const annotations = extractJSDocAnnotationNodes(classDecl, file);
   const visiting = /* @__PURE__ */ new Set();
   const instanceMethods = [];
   const staticMethods = [];
@@ -1463,12 +1761,21 @@ function analyzeClassToIR(classDecl, checker, file = "") {
       }
     }
   }
-  return { name, fields, fieldLayouts, typeRegistry, instanceMethods, staticMethods };
+  return {
+    name,
+    fields,
+    fieldLayouts,
+    typeRegistry,
+    ...annotations.length > 0 && { annotations },
+    instanceMethods,
+    staticMethods
+  };
 }
 function analyzeInterfaceToIR(interfaceDecl, checker, file = "") {
   const name = interfaceDecl.name.text;
   const fields = [];
   const typeRegistry = {};
+  const annotations = extractJSDocAnnotationNodes(interfaceDecl, file);
   const visiting = /* @__PURE__ */ new Set();
   for (const member of interfaceDecl.members) {
     if (ts4.isPropertySignature(member)) {
@@ -1479,7 +1786,15 @@ function analyzeInterfaceToIR(interfaceDecl, checker, file = "") {
     }
   }
   const fieldLayouts = fields.map(() => ({}));
-  return { name, fields, fieldLayouts, typeRegistry, instanceMethods: [], staticMethods: [] };
+  return {
+    name,
+    fields,
+    fieldLayouts,
+    typeRegistry,
+    ...annotations.length > 0 && { annotations },
+    instanceMethods: [],
+    staticMethods: []
+  };
 }
 function analyzeTypeAliasToIR(typeAlias, checker, file = "") {
   if (!ts4.isTypeLiteralNode(typeAlias.type)) {
@@ -1494,6 +1809,7 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "") {
   const name = typeAlias.name.text;
   const fields = [];
   const typeRegistry = {};
+  const annotations = extractJSDocAnnotationNodes(typeAlias, file);
   const visiting = /* @__PURE__ */ new Set();
   for (const member of typeAlias.type.members) {
     if (ts4.isPropertySignature(member)) {
@@ -1510,6 +1826,7 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "") {
       fields,
       fieldLayouts: fields.map(() => ({})),
       typeRegistry,
+      ...annotations.length > 0 && { annotations },
       instanceMethods: [],
       staticMethods: []
     }
@@ -1523,18 +1840,19 @@ function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting) {
   const tsType = checker.getTypeAtLocation(prop);
   const optional = prop.questionToken !== void 0;
   const provenance = provenanceForNode(prop, file);
-  const type = resolveTypeNode(tsType, checker, file, typeRegistry, visiting);
+  let type = resolveTypeNode(tsType, checker, file, typeRegistry, visiting, prop);
   const constraints = [];
   if (prop.type) {
     constraints.push(...extractTypeAliasConstraintNodes(prop.type, checker, file));
   }
   constraints.push(...extractJSDocConstraintNodes(prop, file));
-  const annotations = [];
+  let annotations = [];
   annotations.push(...extractJSDocAnnotationNodes(prop, file));
   const defaultAnnotation = extractDefaultValueAnnotation(prop.initializer, file);
-  if (defaultAnnotation) {
+  if (defaultAnnotation && !annotations.some((a) => a.annotationKind === "defaultValue")) {
     annotations.push(defaultAnnotation);
   }
+  ({ type, annotations } = applyEnumMemberDisplayNames(type, annotations));
   return {
     kind: "field",
     name,
@@ -1553,14 +1871,15 @@ function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visitin
   const tsType = checker.getTypeAtLocation(prop);
   const optional = prop.questionToken !== void 0;
   const provenance = provenanceForNode(prop, file);
-  const type = resolveTypeNode(tsType, checker, file, typeRegistry, visiting);
+  let type = resolveTypeNode(tsType, checker, file, typeRegistry, visiting, prop);
   const constraints = [];
   if (prop.type) {
     constraints.push(...extractTypeAliasConstraintNodes(prop.type, checker, file));
   }
   constraints.push(...extractJSDocConstraintNodes(prop, file));
-  const annotations = [];
+  let annotations = [];
   annotations.push(...extractJSDocAnnotationNodes(prop, file));
+  ({ type, annotations } = applyEnumMemberDisplayNames(type, annotations));
   return {
     kind: "field",
     name,
@@ -1571,7 +1890,69 @@ function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visitin
     provenance
   };
 }
-function resolveTypeNode(type, checker, file, typeRegistry, visiting) {
+function applyEnumMemberDisplayNames(type, annotations) {
+  if (!annotations.some(
+    (annotation) => annotation.annotationKind === "displayName" && annotation.value.trim().startsWith(":")
+  )) {
+    return { type, annotations: [...annotations] };
+  }
+  const consumed = /* @__PURE__ */ new Set();
+  const nextType = rewriteEnumDisplayNames(type, annotations, consumed);
+  if (consumed.size === 0) {
+    return { type, annotations: [...annotations] };
+  }
+  return {
+    type: nextType,
+    annotations: annotations.filter((annotation) => !consumed.has(annotation))
+  };
+}
+function rewriteEnumDisplayNames(type, annotations, consumed) {
+  switch (type.kind) {
+    case "enum":
+      return applyEnumMemberDisplayNamesToEnum(type, annotations, consumed);
+    case "union": {
+      return {
+        ...type,
+        members: type.members.map(
+          (member) => rewriteEnumDisplayNames(member, annotations, consumed)
+        )
+      };
+    }
+    default:
+      return type;
+  }
+}
+function applyEnumMemberDisplayNamesToEnum(type, annotations, consumed) {
+  const displayNames = /* @__PURE__ */ new Map();
+  for (const annotation of annotations) {
+    if (annotation.annotationKind !== "displayName") continue;
+    const parsed = parseEnumMemberDisplayName(annotation.value);
+    if (!parsed) continue;
+    consumed.add(annotation);
+    const member = type.members.find((m) => String(m.value) === parsed.value);
+    if (!member) continue;
+    displayNames.set(String(member.value), parsed.label);
+  }
+  if (displayNames.size === 0) {
+    return type;
+  }
+  return {
+    ...type,
+    members: type.members.map((member) => {
+      const displayName = displayNames.get(String(member.value));
+      return displayName !== void 0 ? { ...member, displayName } : member;
+    })
+  };
+}
+function parseEnumMemberDisplayName(value) {
+  const trimmed = value.trim();
+  const match = /^:([^\s]+)\s+([\s\S]+)$/.exec(trimmed);
+  if (!match?.[1] || !match[2]) return null;
+  const label = match[2].trim();
+  if (label === "") return null;
+  return { value: match[1], label };
+}
+function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode) {
   if (type.flags & ts4.TypeFlags.String) {
     return { kind: "primitive", primitiveKind: "string" };
   }
@@ -1600,7 +1981,7 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting) {
     };
   }
   if (type.isUnion()) {
-    return resolveUnionType(type, checker, file, typeRegistry, visiting);
+    return resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode);
   }
   if (checker.isArrayType(type)) {
     return resolveArrayType(type, checker, file, typeRegistry, visiting);
@@ -1610,70 +1991,102 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting) {
   }
   return { kind: "primitive", primitiveKind: "string" };
 }
-function resolveUnionType(type, checker, file, typeRegistry, visiting) {
+function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode) {
+  const typeName = getNamedTypeName(type);
+  const namedDecl = getNamedTypeDeclaration(type);
+  if (typeName && typeName in typeRegistry) {
+    return { kind: "reference", name: typeName, typeArguments: [] };
+  }
   const allTypes = type.types;
   const nonNullTypes = allTypes.filter(
     (t) => !(t.flags & (ts4.TypeFlags.Null | ts4.TypeFlags.Undefined))
   );
   const hasNull = allTypes.some((t) => t.flags & ts4.TypeFlags.Null);
+  const memberDisplayNames = /* @__PURE__ */ new Map();
+  if (namedDecl) {
+    for (const [value, label] of extractDisplayNameMetadata(namedDecl).memberDisplayNames) {
+      memberDisplayNames.set(value, label);
+    }
+  }
+  if (sourceNode) {
+    for (const [value, label] of extractDisplayNameMetadata(sourceNode).memberDisplayNames) {
+      memberDisplayNames.set(value, label);
+    }
+  }
+  const registerNamed = (result) => {
+    if (!typeName) {
+      return result;
+    }
+    const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file) : void 0;
+    typeRegistry[typeName] = {
+      name: typeName,
+      type: result,
+      ...annotations !== void 0 && annotations.length > 0 && { annotations },
+      provenance: provenanceForDeclaration(namedDecl ?? sourceNode, file)
+    };
+    return { kind: "reference", name: typeName, typeArguments: [] };
+  };
+  const applyMemberLabels = (members2) => members2.map((value) => {
+    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);
   if (isBooleanUnion2) {
     const boolNode = { kind: "primitive", primitiveKind: "boolean" };
-    if (hasNull) {
-      return {
-        kind: "union",
-        members: [boolNode, { kind: "primitive", primitiveKind: "null" }]
-      };
-    }
-    return boolNode;
+    const result = hasNull ? {
+      kind: "union",
+      members: [boolNode, { kind: "primitive", primitiveKind: "null" }]
+    } : boolNode;
+    return registerNamed(result);
   }
   const allStringLiterals = nonNullTypes.every((t) => t.isStringLiteral());
   if (allStringLiterals && nonNullTypes.length > 0) {
     const stringTypes = nonNullTypes.filter((t) => t.isStringLiteral());
     const enumNode = {
       kind: "enum",
-      members: stringTypes.map((t) => ({ value: t.value }))
+      members: applyMemberLabels(stringTypes.map((t) => t.value))
     };
-    if (hasNull) {
-      return {
-        kind: "union",
-        members: [enumNode, { kind: "primitive", primitiveKind: "null" }]
-      };
-    }
-    return enumNode;
+    const result = hasNull ? {
+      kind: "union",
+      members: [enumNode, { kind: "primitive", primitiveKind: "null" }]
+    } : enumNode;
+    return registerNamed(result);
   }
   const allNumberLiterals = nonNullTypes.every((t) => t.isNumberLiteral());
   if (allNumberLiterals && nonNullTypes.length > 0) {
     const numberTypes = nonNullTypes.filter((t) => t.isNumberLiteral());
     const enumNode = {
       kind: "enum",
-      members: numberTypes.map((t) => ({ value: t.value }))
+      members: applyMemberLabels(numberTypes.map((t) => t.value))
     };
-    if (hasNull) {
-      return {
-        kind: "union",
-        members: [enumNode, { kind: "primitive", primitiveKind: "null" }]
-      };
-    }
-    return enumNode;
+    const result = hasNull ? {
+      kind: "union",
+      members: [enumNode, { kind: "primitive", primitiveKind: "null" }]
+    } : enumNode;
+    return registerNamed(result);
   }
   if (nonNullTypes.length === 1 && nonNullTypes[0]) {
-    const inner = resolveTypeNode(nonNullTypes[0], checker, file, typeRegistry, visiting);
-    if (hasNull) {
-      return {
-        kind: "union",
-        members: [inner, { kind: "primitive", primitiveKind: "null" }]
-      };
-    }
-    return inner;
+    const inner = resolveTypeNode(
+      nonNullTypes[0],
+      checker,
+      file,
+      typeRegistry,
+      visiting,
+      sourceNode
+    );
+    const result = hasNull ? {
+      kind: "union",
+      members: [inner, { kind: "primitive", primitiveKind: "null" }]
+    } : inner;
+    return registerNamed(result);
   }
   const members = nonNullTypes.map(
-    (t) => resolveTypeNode(t, checker, file, typeRegistry, visiting)
+    (t) => resolveTypeNode(t, checker, file, typeRegistry, visiting, sourceNode)
   );
   if (hasNull) {
     members.push({ kind: "primitive", primitiveKind: "null" });
   }
-  return { kind: "union", members };
+  return registerNamed({ kind: "union", members });
 }
 function resolveArrayType(type, checker, file, typeRegistry, visiting) {
   const typeArgs = isTypeReference(type) ? type.typeArguments : void 0;
@@ -1681,15 +2094,92 @@ function resolveArrayType(type, checker, file, typeRegistry, visiting) {
   const items = elementType ? resolveTypeNode(elementType, checker, file, typeRegistry, visiting) : { kind: "primitive", primitiveKind: "string" };
   return { kind: "array", items };
 }
+function tryResolveRecordType(type, checker, file, typeRegistry, visiting) {
+  if (type.getProperties().length > 0) {
+    return null;
+  }
+  const indexInfo = checker.getIndexInfoOfType(type, ts4.IndexKind.String);
+  if (!indexInfo) {
+    return null;
+  }
+  const valueType = resolveTypeNode(indexInfo.type, checker, file, typeRegistry, visiting);
+  return { kind: "record", valueType };
+}
+function typeNodeContainsReference(type, targetName) {
+  switch (type.kind) {
+    case "reference":
+      return type.name === targetName;
+    case "array":
+      return typeNodeContainsReference(type.items, targetName);
+    case "record":
+      return typeNodeContainsReference(type.valueType, targetName);
+    case "union":
+      return type.members.some((member) => typeNodeContainsReference(member, targetName));
+    case "object":
+      return type.properties.some(
+        (property) => typeNodeContainsReference(property.type, targetName)
+      );
+    case "primitive":
+    case "enum":
+    case "dynamic":
+    case "custom":
+      return false;
+    default: {
+      const _exhaustive = type;
+      return _exhaustive;
+    }
+  }
+}
 function resolveObjectType(type, checker, file, typeRegistry, visiting) {
+  const typeName = getNamedTypeName(type);
+  const namedTypeName = typeName ?? void 0;
+  const namedDecl = getNamedTypeDeclaration(type);
+  const shouldRegisterNamedType = namedTypeName !== void 0 && !(namedTypeName === "Record" && namedDecl?.getSourceFile().fileName !== file);
+  const clearNamedTypeRegistration = () => {
+    if (namedTypeName === void 0 || !shouldRegisterNamedType) {
+      return;
+    }
+    Reflect.deleteProperty(typeRegistry, namedTypeName);
+  };
   if (visiting.has(type)) {
+    if (namedTypeName !== void 0 && shouldRegisterNamedType) {
+      return { kind: "reference", name: namedTypeName, typeArguments: [] };
+    }
     return { kind: "object", properties: [], additionalProperties: false };
   }
+  if (namedTypeName !== void 0 && shouldRegisterNamedType && !typeRegistry[namedTypeName]) {
+    typeRegistry[namedTypeName] = {
+      name: namedTypeName,
+      type: RESOLVING_TYPE_PLACEHOLDER,
+      provenance: provenanceForDeclaration(namedDecl, file)
+    };
+  }
   visiting.add(type);
-  const typeName = getNamedTypeName(type);
-  if (typeName && typeName in typeRegistry) {
+  if (namedTypeName !== void 0 && shouldRegisterNamedType && typeRegistry[namedTypeName]?.type !== void 0) {
+    if (typeRegistry[namedTypeName].type !== RESOLVING_TYPE_PLACEHOLDER) {
+      visiting.delete(type);
+      return { kind: "reference", name: namedTypeName, typeArguments: [] };
+    }
+  }
+  const recordNode = tryResolveRecordType(type, checker, file, typeRegistry, visiting);
+  if (recordNode) {
     visiting.delete(type);
-    return { kind: "reference", name: typeName, typeArguments: [] };
+    if (namedTypeName !== void 0 && shouldRegisterNamedType) {
+      const isRecursiveRecord = typeNodeContainsReference(recordNode.valueType, namedTypeName);
+      if (!isRecursiveRecord) {
+        clearNamedTypeRegistration();
+        return recordNode;
+      }
+      const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file) : void 0;
+      typeRegistry[namedTypeName] = {
+        name: namedTypeName,
+        type: recordNode,
+        ...annotations !== void 0 && annotations.length > 0 && { annotations },
+        provenance: provenanceForDeclaration(namedDecl, file)
+      };
+      return { kind: "reference", name: namedTypeName, typeArguments: [] };
+    }
+    return recordNode;
   }
   const properties = [];
   const fieldInfoMap = getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visiting);
@@ -1698,7 +2188,14 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
     if (!declaration) continue;
     const propType = checker.getTypeOfSymbolAtLocation(prop, declaration);
     const optional = !!(prop.flags & ts4.SymbolFlags.Optional);
-    const propTypeNode = resolveTypeNode(propType, checker, file, typeRegistry, visiting);
+    const propTypeNode = resolveTypeNode(
+      propType,
+      checker,
+      file,
+      typeRegistry,
+      visiting,
+      declaration
+    );
     const fieldNodeInfo = fieldInfoMap?.get(prop.name);
     properties.push({
       name: prop.name,
@@ -1713,15 +2210,17 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
   const objectNode = {
     kind: "object",
     properties,
-    additionalProperties: false
+    additionalProperties: true
   };
-  if (typeName) {
-    typeRegistry[typeName] = {
-      name: typeName,
+  if (namedTypeName !== void 0 && shouldRegisterNamedType) {
+    const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file) : void 0;
+    typeRegistry[namedTypeName] = {
+      name: namedTypeName,
       type: objectNode,
-      provenance: provenanceForFile(file)
+      ...annotations !== void 0 && annotations.length > 0 && { annotations },
+      provenance: provenanceForDeclaration(namedDecl, file)
     };
-    return { kind: "reference", name: typeName, typeArguments: [] };
+    return { kind: "reference", name: namedTypeName, typeArguments: [] };
   }
   return objectNode;
 }
@@ -1813,6 +2312,12 @@ function provenanceForNode(node, file) {
 function provenanceForFile(file) {
   return { surface: "tsdoc", file, line: 0, column: 0 };
 }
+function provenanceForDeclaration(node, file) {
+  if (!node) {
+    return provenanceForFile(file);
+  }
+  return provenanceForNode(node, file);
+}
 function getNamedTypeName(type) {
   const symbol = type.getSymbol();
   if (symbol?.declarations) {
@@ -1831,6 +2336,20 @@ function getNamedTypeName(type) {
   }
   return null;
 }
+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))) {
+      return decl;
+    }
+  }
+  const aliasSymbol = type.aliasSymbol;
+  if (aliasSymbol?.declarations) {
+    return aliasSymbol.declarations.find(ts4.isTypeAliasDeclaration);
+  }
+  return void 0;
+}
 function analyzeMethod(method, checker) {
   if (!ts4.isIdentifier(method.name)) {
     return null;
@@ -1915,16 +2434,219 @@ function generateSchemas(options) {
   );
 }
 
+// src/generators/mixed-authoring.ts
+function buildMixedAuthoringSchemas(options) {
+  const { filePath, typeName, overlays, ...schemaOptions } = options;
+  const analysis = analyzeNamedType(filePath, typeName);
+  const composedAnalysis = composeAnalysisWithOverlays(analysis, overlays);
+  const ir = canonicalizeTSDoc(composedAnalysis, { file: filePath });
+  return {
+    jsonSchema: generateJsonSchemaFromIR(ir, schemaOptions),
+    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);
+  if (overlayFields.length === 0) {
+    return analysis;
+  }
+  const overlayByName = /* @__PURE__ */ new Map();
+  for (const field of overlayFields) {
+    if (overlayByName.has(field.name)) {
+      throw new Error(`Mixed-authoring overlays define "${field.name}" more than once`);
+    }
+    overlayByName.set(field.name, field);
+  }
+  const mergedFields = [];
+  for (const baseField of analysis.fields) {
+    const overlayField = overlayByName.get(baseField.name);
+    if (overlayField === void 0) {
+      mergedFields.push(baseField);
+      continue;
+    }
+    mergedFields.push(mergeFieldOverlay(baseField, overlayField, analysis.typeRegistry));
+    overlayByName.delete(baseField.name);
+  }
+  if (overlayByName.size > 0) {
+    const unknownFields = [...overlayByName.keys()].sort().join(", ");
+    throw new Error(
+      `Mixed-authoring overlays reference fields that are not present in the static model: ${unknownFields}`
+    );
+  }
+  return {
+    ...analysis,
+    fields: mergedFields
+  };
+}
+function collectOverlayFields(elements) {
+  const fields = [];
+  for (const element of elements) {
+    switch (element.kind) {
+      case "field":
+        fields.push(element);
+        break;
+      case "group":
+        fields.push(...collectOverlayFields(element.elements));
+        break;
+      case "conditional":
+        fields.push(...collectOverlayFields(element.elements));
+        break;
+      default: {
+        const _exhaustive = element;
+        void _exhaustive;
+      }
+    }
+  }
+  return fields;
+}
+function mergeFieldOverlay(baseField, overlayField, typeRegistry) {
+  assertSupportedOverlayField(baseField, overlayField);
+  return {
+    ...baseField,
+    type: mergeFieldType(baseField, overlayField, typeRegistry),
+    annotations: mergeAnnotations(baseField.annotations, overlayField.annotations)
+  };
+}
+function assertSupportedOverlayField(baseField, overlayField) {
+  if (overlayField.constraints.length > 0) {
+    throw new Error(
+      `Mixed-authoring overlay for "${baseField.name}" cannot define constraints; keep constraints on the static model`
+    );
+  }
+  if (overlayField.required) {
+    throw new Error(
+      `Mixed-authoring overlay for "${baseField.name}" cannot change requiredness; keep requiredness on the static model`
+    );
+  }
+}
+function mergeFieldType(baseField, overlayField, typeRegistry) {
+  const { type: baseType } = baseField;
+  const { type: overlayType } = overlayField;
+  if (overlayType.kind === "object" || overlayType.kind === "array") {
+    throw new Error(
+      `Mixed-authoring overlays do not support nested object or array overlays for "${baseField.name}"`
+    );
+  }
+  if (overlayType.kind === "dynamic") {
+    if (!isCompatibleDynamicOverlay(baseField, overlayField, typeRegistry)) {
+      throw new Error(
+        `Mixed-authoring overlay for "${baseField.name}" is incompatible with the static field type`
+      );
+    }
+    return overlayType;
+  }
+  if (!isSameStaticTypeShape(baseType, overlayType)) {
+    throw new Error(
+      `Mixed-authoring overlay for "${baseField.name}" must preserve the static field type`
+    );
+  }
+  return baseType;
+}
+function isCompatibleDynamicOverlay(baseField, overlayField, typeRegistry) {
+  const overlayType = overlayField.type;
+  if (overlayType.kind !== "dynamic") {
+    return false;
+  }
+  const resolvedBaseType = resolveReferenceType(baseField.type, typeRegistry);
+  if (resolvedBaseType === null) {
+    return false;
+  }
+  if (overlayType.dynamicKind === "enum") {
+    return resolvedBaseType.kind === "primitive" ? resolvedBaseType.primitiveKind === "string" : resolvedBaseType.kind === "enum";
+  }
+  return resolvedBaseType.kind === "object" || resolvedBaseType.kind === "record";
+}
+function resolveReferenceType(type, typeRegistry, seen = /* @__PURE__ */ new Set()) {
+  if (type.kind !== "reference") {
+    return type;
+  }
+  if (seen.has(type.name)) {
+    return null;
+  }
+  const definition = typeRegistry[type.name];
+  if (definition === void 0) {
+    return null;
+  }
+  seen.add(type.name);
+  return resolveReferenceType(definition.type, typeRegistry, seen);
+}
+function isSameStaticTypeShape(baseType, overlayType) {
+  if (baseType.kind !== overlayType.kind) {
+    return false;
+  }
+  switch (baseType.kind) {
+    case "primitive":
+      return overlayType.kind === "primitive" && baseType.primitiveKind === overlayType.primitiveKind;
+    case "enum":
+      return overlayType.kind === "enum";
+    case "dynamic":
+      return overlayType.kind === "dynamic" && baseType.dynamicKind === overlayType.dynamicKind && baseType.sourceKey === overlayType.sourceKey;
+    case "record":
+      return overlayType.kind === "record";
+    case "reference":
+      return overlayType.kind === "reference" && baseType.name === overlayType.name;
+    case "union":
+      return overlayType.kind === "union";
+    case "custom":
+      return overlayType.kind === "custom" && baseType.typeId === overlayType.typeId;
+    case "object":
+    case "array":
+      return true;
+    default: {
+      const _exhaustive = baseType;
+      return _exhaustive;
+    }
+  }
+}
+function mergeAnnotations(baseAnnotations, overlayAnnotations) {
+  const baseKeys = new Set(baseAnnotations.map(annotationKey));
+  const overlayOnly = overlayAnnotations.filter(
+    (annotation) => !baseKeys.has(annotationKey(annotation))
+  );
+  return [...overlayOnly, ...baseAnnotations];
+}
+function annotationKey(annotation) {
+  return annotation.annotationKind === "custom" ? `${annotation.annotationKind}:${annotation.annotationId}` : annotation.annotationKind;
+}
+
 // src/index.ts
-function buildFormSchemas(form) {
+function buildFormSchemas(form, options) {
   return {
-    jsonSchema: generateJsonSchema(form),
+    jsonSchema: generateJsonSchema(form, options),
     uiSchema: generateUiSchema(form)
   };
 }
 function writeSchemas(form, options) {
-  const { outDir, name = "schema", indent = 2 } = options;
-  const { jsonSchema, uiSchema: uiSchema2 } = buildFormSchemas(form);
+  const { outDir, name = "schema", indent = 2, extensionRegistry, vendorPrefix } = options;
+  const buildOptions = extensionRegistry === void 0 && vendorPrefix === void 0 ? void 0 : {
+    extensionRegistry,
+    vendorPrefix
+  };
+  const { jsonSchema, uiSchema: uiSchema2 } = buildFormSchemas(form, buildOptions);
   if (!fs.existsSync(outDir)) {
     fs.mkdirSync(outDir, { recursive: true });
   }
@@ -1937,10 +2659,13 @@ function writeSchemas(form, options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   buildFormSchemas,
+  buildMixedAuthoringSchemas,
   categorizationSchema,
   categorySchema,
   controlSchema,
+  createExtensionRegistry,
   generateJsonSchema,
+  generateJsonSchemaFromIR,
   generateSchemas,
   generateSchemasFromClass,
   generateUiSchema,