@tsonic/cli 0.0.62 → 0.0.64

package/dist/commands/library-bindings-augment.js

@@ -1,6 +1,7 @@
 import { copyFileSync, existsSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, resolve, posix } from "node:path";
 import { buildModuleDependencyGraph, } from "@tsonic/frontend";
+import { resolveSurfaceCapabilities } from "../surface/profiles.js";
 import * as ts from "typescript";
 const renderDiagnostics = (diags) => {
     return diags
@@ -21,6 +22,10 @@ const printTypeNodeText = (node, sourceFile) => {
         .printNode(ts.EmitHint.Unspecified, node, sourceFile)
         .trim();
 };
+const textContainsIdentifier = (text, identifier) => {
+    const pattern = new RegExp(String.raw `\b${escapeRegExp(identifier)}\b`);
+    return pattern.test(text);
+};
 const ensureUndefinedInType = (typeText) => {
     const trimmed = typeText.trim();
     if (/\bundefined\b/.test(trimmed))
@@ -222,6 +227,36 @@ const patchInternalIndexWithMemberOverrides = (internalIndexDtsPath, overrides)
                         `This property was declared in TS source and should exist in CLR metadata.`,
                 };
             }
+            if (o.isOptional &&
+                o.emitOptionalPropertySyntax &&
+                !o.memberName.startsWith("__tsonic_type_")) {
+                const baseType = (o.replaceWithSourceType ? o.sourceTypeText : undefined) ??
+                    getterMatch?.[2] ??
+                    setterMatch?.[2] ??
+                    "";
+                const nextType = applyWrappersToBaseType(baseType, o.wrappers);
+                const matchForIndent = getterMatch ?? setterMatch;
+                const indent = matchForIndent?.[0].match(/^\s*/)?.[0] ?? "    ";
+                const optionalPropertyLine = `${indent}${o.memberName}?: ${nextType};`;
+                if (getterMatch && setterMatch) {
+                    const getterStart = getterMatch.index ?? 0;
+                    const setterStart = setterMatch.index ?? 0;
+                    const start = Math.min(getterStart, setterStart);
+                    const getterEnd = getterStart + getterMatch[0].length;
+                    const setterEnd = setterStart + setterMatch[0].length;
+                    const end = Math.max(getterEnd, setterEnd);
+                    body = body.slice(0, start) + optionalPropertyLine + body.slice(end);
+                    continue;
+                }
+                if (getterMatch) {
+                    body = body.replace(getterRe, optionalPropertyLine);
+                    continue;
+                }
+                if (setterMatch) {
+                    body = body.replace(setterRe, optionalPropertyLine);
+                    continue;
+                }
+            }
             if (getterMatch) {
                 const baseType = (o.replaceWithSourceType ? o.sourceTypeText : undefined) ??
                     getterMatch[2] ??
@@ -252,7 +287,7 @@ const patchInternalIndexWithMemberOverrides = (internalIndexDtsPath, overrides)
     }
     return { ok: true, value: undefined };
 };
-const patchInternalIndexBrandMarkersOptional = (internalIndexDtsPath, typeNames) => {
+export const patchInternalIndexBrandMarkersOptional = (internalIndexDtsPath, typeNames) => {
     if (!existsSync(internalIndexDtsPath)) {
         return {
             ok: false,
@@ -275,7 +310,7 @@ const patchInternalIndexBrandMarkersOptional = (internalIndexDtsPath, typeNames)
         const head = block.slice(0, open + 1);
         let body = block.slice(open + 1, close);
         const tail = block.slice(close);
-        const brandRe = /(^\s*readonly\s+__tsonic_type_[A-Za-z0-9_]+)\s*:\s*never\s*;/m;
+        const brandRe = /(^\s*readonly\s+__tsonic_type_[A-Za-z0-9_]+)\s*:\s*never\s*;/gm;
         if (!brandRe.test(body))
             continue;
         body = body.replace(brandRe, "$1?: never;");
@@ -290,7 +325,7 @@ const patchInternalIndexBrandMarkersOptional = (internalIndexDtsPath, typeNames)
     }
     return { ok: true, value: undefined };
 };
-const splitTopLevelTypeArgs = (text) => {
+const splitTopLevelCommaSeparated = (text) => {
     const parts = [];
     let depthAngle = 0;
     let depthParen = 0;
@@ -327,11 +362,13 @@ const splitTopLevelTypeArgs = (text) => {
     parts.push(text.slice(start).trim());
     return parts.filter((p) => p.length > 0);
 };
+const splitTopLevelTypeArgs = (text) => {
+    return splitTopLevelCommaSeparated(text);
+};
 const expandUnionsDeep = (typeText) => {
     const unionPrefixRe = /Union_\d+</g;
     let result = typeText;
     // Iterate until no more Union_N< patterns remain
-    // eslint-disable-next-line no-constant-condition
     while (true) {
         unionPrefixRe.lastIndex = 0;
         const prefixMatch = unionPrefixRe.exec(result);
@@ -367,6 +404,26 @@ const expandUnionsDeep = (typeText) => {
     }
     return result;
 };
+const collectSourceTypeImportsForSignature = (signature, typeImportsByLocalName) => {
+    const required = [];
+    for (const [localName, imported] of typeImportsByLocalName) {
+        const source = imported.source.trim();
+        // Relative source imports do not map to published facade paths.
+        if (source.startsWith(".") || source.startsWith("/"))
+            continue;
+        const appearsInSignature = textContainsIdentifier(signature.typeParametersText, localName) ||
+            textContainsIdentifier(signature.parametersText, localName) ||
+            textContainsIdentifier(signature.returnTypeText, localName);
+        if (!appearsInSignature)
+            continue;
+        required.push({
+            source,
+            importedName: imported.importedName,
+            localName,
+        });
+    }
+    return required.sort((a, b) => a.localName.localeCompare(b.localName));
+};
 const patchFacadeWithSourceFunctionSignatures = (facadeDtsPath, signaturesByName) => {
     if (!existsSync(facadeDtsPath)) {
         return {
@@ -384,45 +441,209 @@ const patchFacadeWithSourceFunctionSignatures = (facadeDtsPath, signaturesByName
         if (currentMatch) {
             const existingReturnType = currentMatch[2]?.trim() ?? "";
             const replacement = Array.from(new Set(signatures.map((sig) => {
-                const returnType = sig.returnTypeText.includes("{")
-                    ? expandUnionsDeep(existingReturnType)
-                    : sig.returnTypeText;
+                const existingIsUnknown = existingReturnType === "unknown";
+                const existingHasAnon = /__Anon_/.test(existingReturnType);
+                const existingHasGenericAritySuffix = /\b[A-Za-z_$][\w$]*_\d+\s*</.test(existingReturnType);
+                const returnType = (() => {
+                    if (!sig.returnTypeText.includes("{")) {
+                        return sig.returnTypeText;
+                    }
+                    if (existingIsUnknown) {
+                        return sig.returnTypeText;
+                    }
+                    if (existingHasAnon) {
+                        return expandUnionsDeep(existingReturnType);
+                    }
+                    if (existingHasGenericAritySuffix) {
+                        return sig.returnTypeText;
+                    }
+                    return expandUnionsDeep(existingReturnType);
+                })();
                 return `export declare function ${name}${sig.typeParametersText}(${sig.parametersText}): ${returnType};`;
             }))).join("\n");
             next = next.replace(fnRe, replacement);
             continue;
         }
-        // If no function declaration match, try const Func<...> pattern
-        const constFuncRe = new RegExp(String.raw `^export\s+declare\s+const\s+${escapeRegExp(name)}\s*:\s*Func<([\s\S]+?)>\s*;`, "m");
-        const constMatch = constFuncRe.exec(next);
+        // If no function declaration match, try const callable pattern.
+        const constDeclRe = new RegExp(String.raw `^export\s+declare\s+const\s+${escapeRegExp(name)}\s*:\s*([^;]+);`, "m");
+        const constMatch = constDeclRe.exec(next);
         if (!constMatch || !constMatch[1])
             continue;
-        const funcTypeArgs = splitTopLevelTypeArgs(constMatch[1]);
-        if (funcTypeArgs.length < 2)
+        const constTypeText = constMatch[1].trim();
+        let expectedParamCount;
+        let forcedReturnType;
+        const funcTypeMatch = /^Func<([\s\S]+)>$/.exec(constTypeText);
+        if (funcTypeMatch?.[1]) {
+            const funcTypeArgs = splitTopLevelTypeArgs(funcTypeMatch[1]);
+            if (funcTypeArgs.length < 2)
+                continue;
+            expectedParamCount = funcTypeArgs.length - 1;
+            const lastTypeArg = funcTypeArgs.at(-1);
+            if (!lastTypeArg)
+                continue;
+            forcedReturnType = expandUnionsDeep(lastTypeArg);
+        }
+        const replacement = Array.from(new Set(signatures
+            .filter((sig) => {
+            if (expectedParamCount === undefined)
+                return true;
+            const paramCount = splitTopLevelCommaSeparated(sig.parametersText).length;
+            return paramCount === expectedParamCount;
+        })
+            .map((sig) => {
+            const returnType = forcedReturnType ?? sig.returnTypeText;
+            return `export declare function ${name}${sig.typeParametersText}(${sig.parametersText}): ${returnType};`;
+        }))).join("\n");
+        if (replacement.length === 0)
             continue;
-        // Last arg = return type, remaining args = parameter types
-        const facadeParamTypes = funcTypeArgs.slice(0, -1);
-        const facadeReturnType = funcTypeArgs[funcTypeArgs.length - 1];
-        // Use the first source signature for parameter names
-        const sourceSig = signatures[0];
-        const sourceParams = sourceSig.parametersText
-            .split(",")
-            .map((p) => p.trim())
-            .filter((p) => p.length > 0);
-        // If count mismatch, skip patching for this declaration
-        if (sourceParams.length !== facadeParamTypes.length)
+        next = next.replace(constDeclRe, replacement);
+    }
+    if (next !== original) {
+        writeFileSync(facadeDtsPath, next, "utf-8");
+    }
+    return { ok: true, value: undefined };
+};
+const parseNamedImports = (namedImportsText) => {
+    return namedImportsText
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .map((part) => {
+        const source = part.replace(/^\s*type\s+/, "");
+        const asMatch = /^\s*([A-Za-z_$][\w$]*)\s+as\s+([A-Za-z_$][\w$]*)\s*$/.exec(source);
+        if (asMatch && asMatch[1] && asMatch[2]) {
+            return { imported: asMatch[1], local: asMatch[2] };
+        }
+        const identMatch = /^\s*([A-Za-z_$][\w$]*)\s*$/.exec(source);
+        if (identMatch && identMatch[1]) {
+            return { imported: identMatch[1], local: identMatch[1] };
+        }
+        return undefined;
+    })
+        .filter((specifier) => specifier !== undefined);
+};
+const formatNamedImportSpecifier = (specifier) => {
+    if (specifier.imported === specifier.local) {
+        return specifier.local;
+    }
+    return `${specifier.imported} as ${specifier.local}`;
+};
+const ensureInternalTypeImportsForFacade = (facadeDtsPath) => {
+    if (!existsSync(facadeDtsPath)) {
+        return {
+            ok: false,
+            error: `Facade declaration file not found at ${facadeDtsPath}`,
+        };
+    }
+    const original = readFileSync(facadeDtsPath, "utf-8");
+    const internalImportRe = /^import\s+\*\s+as\s+Internal\s+from\s+['"]([^'"]+)['"];\s*$/m;
+    const internalImportMatch = internalImportRe.exec(original);
+    if (!internalImportMatch || !internalImportMatch[1]) {
+        return { ok: true, value: undefined };
+    }
+    const internalSpecifier = internalImportMatch[1];
+    const exportFromInternalRe = new RegExp(String.raw `^export\s+\{([^}]*)\}\s+from\s+['"]${escapeRegExp(internalSpecifier)}['"];\s*$`, "gm");
+    const neededTypeSpecifiers = new Map();
+    for (const match of original.matchAll(exportFromInternalRe)) {
+        const named = match[1];
+        if (!named)
             continue;
-        // Pair source parameter NAMES with facade parameter TYPES
-        const pairedParams = sourceParams.map((param, idx) => {
-            const colonIdx = param.indexOf(":");
-            const paramName = colonIdx >= 0 ? param.slice(0, colonIdx).trim() : param.trim();
-            return `${paramName}: ${facadeParamTypes[idx]}`;
+        for (const specifier of parseNamedImports(named)) {
+            neededTypeSpecifiers.set(specifier.local, specifier);
+        }
+    }
+    if (neededTypeSpecifiers.size === 0) {
+        return { ok: true, value: undefined };
+    }
+    const existingTypeImportRe = new RegExp(String.raw `^import\s+type\s+\{([^}]*)\}\s+from\s+['"]${escapeRegExp(internalSpecifier)}['"];\s*$`, "m");
+    const existingTypeImportMatch = existingTypeImportRe.exec(original);
+    if (existingTypeImportMatch && existingTypeImportMatch[1]) {
+        for (const specifier of parseNamedImports(existingTypeImportMatch[1])) {
+            neededTypeSpecifiers.set(specifier.local, specifier);
+        }
+    }
+    const sortedSpecifiers = Array.from(neededTypeSpecifiers.values()).sort((a, b) => a.local.localeCompare(b.local));
+    const importLine = `import type { ${sortedSpecifiers
+        .map((specifier) => formatNamedImportSpecifier(specifier))
+        .join(", ")} } from '${internalSpecifier}';`;
+    let next = original;
+    if (existingTypeImportMatch && existingTypeImportMatch[0]) {
+        next = next.replace(existingTypeImportRe, importLine);
+    }
+    else if (internalImportMatch[0]) {
+        const anchor = internalImportMatch[0];
+        next = next.replace(anchor, `${anchor}\n${importLine}`);
+    }
+    if (next !== original) {
+        writeFileSync(facadeDtsPath, next, "utf-8");
+    }
+    return { ok: true, value: undefined };
+};
+const ensureSourceTypeImportsForFacade = (facadeDtsPath, importsByLocalName) => {
+    if (!existsSync(facadeDtsPath)) {
+        return {
+            ok: false,
+            error: `Facade declaration file not found at ${facadeDtsPath}`,
+        };
+    }
+    const original = readFileSync(facadeDtsPath, "utf-8");
+    if (importsByLocalName.size === 0) {
+        return { ok: true, value: undefined };
+    }
+    const existingLocals = new Set();
+    const importRe = /^import\s+(.*)\s+from\s+['"][^'"]+['"];\s*$/gm;
+    for (const match of original.matchAll(importRe)) {
+        const clause = match[1]?.trim();
+        if (!clause)
+            continue;
+        const nsMatch = /^\*\s+as\s+([A-Za-z_$][\w$]*)$/.exec(clause);
+        if (nsMatch?.[1]) {
+            existingLocals.add(nsMatch[1]);
+            continue;
+        }
+        const defaultMatch = /^([A-Za-z_$][\w$]*)$/.exec(clause);
+        if (defaultMatch?.[1]) {
+            existingLocals.add(defaultMatch[1]);
+            continue;
+        }
+        const namedMatch = /^(?:type\s+)?\{([^}]*)\}$/.exec(clause);
+        if (namedMatch?.[1]) {
+            for (const specifier of parseNamedImports(namedMatch[1])) {
+                existingLocals.add(specifier.local);
+            }
+        }
+    }
+    const grouped = new Map();
+    for (const binding of Array.from(importsByLocalName.values()).sort((a, b) => a.localName.localeCompare(b.localName))) {
+        if (existingLocals.has(binding.localName))
+            continue;
+        const list = grouped.get(binding.source) ?? [];
+        list.push({
+            imported: binding.importedName,
+            local: binding.localName,
         });
-        const expandedReturnType = expandUnionsDeep(facadeReturnType);
-        const typeParamsText = sourceSig.typeParametersText;
-        const replacement = `export declare function ${name}${typeParamsText}(${pairedParams.join(", ")}): ${expandedReturnType};`;
-        next = next.replace(constFuncRe, replacement);
+        grouped.set(binding.source, list);
+    }
+    if (grouped.size === 0) {
+        const startMarker = "// Tsonic source function type imports (generated)";
+        const endMarker = "// End Tsonic source function type imports";
+        const next = stripExistingSection(original, startMarker, endMarker);
+        if (next !== original) {
+            writeFileSync(facadeDtsPath, next, "utf-8");
+        }
+        return { ok: true, value: undefined };
     }
+    const lines = [];
+    for (const [source, specifiers] of Array.from(grouped.entries()).sort((a, b) => a[0].localeCompare(b[0]))) {
+        const unique = Array.from(new Map(specifiers.map((specifier) => [
+            `${specifier.imported}|${specifier.local}`,
+            specifier,
+        ])).values()).sort((a, b) => a.local.localeCompare(b.local));
+        lines.push(`import type { ${unique.map((s) => formatNamedImportSpecifier(s)).join(", ")} } from '${source}';`);
+    }
+    const startMarker = "// Tsonic source function type imports (generated)";
+    const endMarker = "// End Tsonic source function type imports";
+    const next = upsertSectionAfterImports(original, startMarker, endMarker, lines.join("\n"));
     if (next !== original) {
         writeFileSync(facadeDtsPath, next, "utf-8");
     }
@@ -678,12 +899,14 @@ const buildModuleSourceIndex = (absoluteFilePath, fileKey) => {
     };
 };
 const typeNodeUsesImportedTypeNames = (node, typeImportsByLocalName) => {
+    const allowlistedImportSources = new Set(["@tsonic/core/types.js"]);
     let found = false;
     const visit = (current) => {
         if (found)
             return;
         if (ts.isTypeReferenceNode(current) && ts.isIdentifier(current.typeName)) {
-            if (typeImportsByLocalName.has(current.typeName.text)) {
+            const imported = typeImportsByLocalName.get(current.typeName.text);
+            if (imported && !allowlistedImportSources.has(imported.source.trim())) {
                 found = true;
                 return;
             }
@@ -777,6 +1000,7 @@ const collectExtensionWrapperImportsFromSourceType = (opts) => {
             localName: ident,
             aliasName: `__TsonicExt_${ident}`,
         });
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         currentNode = args[0];
     }
     return { ok: true, value: wrappers };
@@ -901,7 +1125,7 @@ const printIrType = (type, ctx) => {
             return "unknown";
     }
 };
-const renderExportedTypeAlias = (stmt, internalIndexDts) => {
+const renderExportedTypeAlias = (stmt, internalIndexDts, _sourceAlias) => {
     const typeParams = printTypeParameters(stmt.typeParameters);
     if (stmt.type.kind === "objectType") {
         const arity = stmt.typeParameters?.length ?? 0;
@@ -919,11 +1143,17 @@ const renderExportedTypeAlias = (stmt, internalIndexDts) => {
             : "";
         return {
             ok: true,
-            value: `export type ${stmt.name}${typeParams} = Internal.${internalName}${typeArgs};`,
+            value: {
+                line: `export type ${stmt.name}${typeParams} = ${internalName}${typeArgs};`,
+                internalAliasImport: internalName,
+            },
         };
     }
     const rhs = printIrType(stmt.type, { parentPrecedence: 0 });
-    return { ok: true, value: `export type ${stmt.name}${typeParams} = ${rhs};` };
+    return {
+        ok: true,
+        value: { line: `export type ${stmt.name}${typeParams} = ${rhs};` },
+    };
 };
 /**
  * Overlay already-augmented bindings from dependency assemblies.
@@ -943,9 +1173,7 @@ export const overlayDependencyBindings = (config, bindingsOutDir) => {
         // Skip the current package's own assembly.
         if (assemblyName === config.outputName)
             continue;
-        // Convention: DLL at <project>/dist/<dotnetVersion>/<name>.dll,
-        // bindings at <project>/dist/tsonic/bindings/.
-        const depBindingsDir = join(dirname(dirname(lib)), "tsonic", "bindings");
+        const depBindingsDir = resolveDependencyBindingsDirForDll(lib);
         if (existsSync(depBindingsDir)) {
             depBindingsDirByAssembly.set(assemblyName, depBindingsDir);
         }
@@ -985,6 +1213,22 @@ export const overlayDependencyBindings = (config, bindingsOutDir) => {
     }
     return { ok: true, value: undefined };
 };
+export const resolveDependencyBindingsDirForDll = (dllPath) => {
+    // Walk up from the DLL and resolve the nearest project-style bindings directory:
+    // - <project>/dist/tsonic/bindings
+    let cursor = resolve(dirname(dllPath));
+    for (let i = 0; i < 24; i++) {
+        const projectStyle = join(cursor, "dist", "tsonic", "bindings");
+        if (existsSync(projectStyle))
+            return projectStyle;
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    // No bindings directory found; caller checks existsSync before use.
+    return join(resolve(dirname(dllPath)), "dist", "tsonic", "bindings");
+};
 export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
     const entryPoint = config.entryPoint;
     if (!entryPoint) {
@@ -992,6 +1236,7 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
     }
     const absoluteEntryPoint = resolve(config.projectRoot, entryPoint);
     const absoluteSourceRoot = resolve(config.projectRoot, config.sourceRoot);
+    const surfaceCapabilities = resolveSurfaceCapabilities(config.surface);
     const typeLibraries = config.libraries.filter((lib) => !lib.endsWith(".dll"));
     const allTypeRoots = [...config.typeRoots, ...typeLibraries].map((p) => resolve(config.workspaceRoot, p));
     const compilerOptions = {
@@ -999,6 +1244,8 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
         sourceRoot: absoluteSourceRoot,
         rootNamespace: config.rootNamespace,
         typeRoots: allTypeRoots,
+        surface: config.surface,
+        useStandardLib: surfaceCapabilities.useStandardLib,
         verbose: false,
     };
     const graphResult = buildModuleDependencyGraph(absoluteEntryPoint, compilerOptions);
@@ -1055,6 +1302,7 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
     };
     // 1) Per-namespace exported type aliases (including non-structural aliases).
     const exportedAliasesByNamespace = new Map();
+    const sourceIndexByFileKeyForAliases = new Map();
     for (const m of modules) {
         const isExportedTypeAlias = (stmt) => stmt.kind === "typeAliasDeclaration" && stmt.isExported;
         const exportedAliases = m.body.filter(isExportedTypeAlias);
@@ -1064,27 +1312,60 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
         const internalIndexDts = existsSync(info.internalIndexDtsPath)
             ? readFileSync(info.internalIndexDtsPath, "utf-8")
             : "";
+        const moduleKey = normalizeModuleFileKey(m.filePath);
+        const sourceIndex = (() => {
+            const cached = sourceIndexByFileKeyForAliases.get(moduleKey);
+            if (cached)
+                return { ok: true, value: cached };
+            const absolutePath = resolve(absoluteSourceRoot, moduleKey);
+            const indexed = buildModuleSourceIndex(absolutePath, moduleKey);
+            if (!indexed.ok)
+                return indexed;
+            sourceIndexByFileKeyForAliases.set(moduleKey, indexed.value);
+            return indexed;
+        })();
+        if (!sourceIndex.ok)
+            return sourceIndex;
         for (const stmt of exportedAliases) {
-            const rendered = renderExportedTypeAlias(stmt, internalIndexDts);
+            const rendered = renderExportedTypeAlias(stmt, internalIndexDts, sourceIndex.value.typeAliasesByName.get(stmt.name));
             if (!rendered.ok)
                 return rendered;
-            const list = exportedAliasesByNamespace.get(m.namespace) ?? [];
-            list.push(rendered.value);
-            exportedAliasesByNamespace.set(m.namespace, list);
+            const current = exportedAliasesByNamespace.get(m.namespace) ?? {
+                lines: [],
+                internalAliasImports: new Set(),
+            };
+            current.lines.push(rendered.value.line);
+            if (rendered.value.internalAliasImport) {
+                current.internalAliasImports.add(rendered.value.internalAliasImport);
+            }
+            exportedAliasesByNamespace.set(m.namespace, current);
         }
     }
     const aliasStart = "// Tsonic source type aliases (generated)";
     const aliasEnd = "// End Tsonic source type aliases";
-    for (const [ns, lines] of exportedAliasesByNamespace) {
+    const aliasImportsStart = "// Tsonic source alias imports (generated)";
+    const aliasImportsEnd = "// End Tsonic source alias imports";
+    for (const [ns, aliasData] of exportedAliasesByNamespace) {
         const info = facadesByNamespace.get(ns);
         if (!info)
             continue;
-        if (lines.length === 0)
+        if (aliasData.lines.length === 0)
             continue;
-        const unique = Array.from(new Set(lines)).sort((a, b) => a.localeCompare(b));
+        const unique = Array.from(new Set(aliasData.lines)).sort((a, b) => a.localeCompare(b));
         const body = unique.join("\n");
         const current = readFileSync(info.facadeDtsPath, "utf-8");
-        const next = upsertSection(current, aliasStart, aliasEnd, body);
+        const internalImportMatch = current.match(/^import\s+\*\s+as\s+Internal\s+from\s+['"](.+)['"];\s*$/m);
+        let next = current;
+        if (internalImportMatch?.[1] && aliasData.internalAliasImports.size > 0) {
+            const internalAliasImportLine = `import type { ${Array.from(aliasData.internalAliasImports)
+                .sort((a, b) => a.localeCompare(b))
+                .join(", ")} } from '${internalImportMatch[1]}';`;
+            next = upsertSectionAfterImports(next, aliasImportsStart, aliasImportsEnd, internalAliasImportLine);
+        }
+        else {
+            next = stripExistingSection(next, aliasImportsStart, aliasImportsEnd);
+        }
+        next = upsertSectionAfterImports(next, aliasStart, aliasEnd, body);
         writeFileSync(info.facadeDtsPath, next, "utf-8");
     }
     // 2) Entry-module re-export surface (matches TS semantics for library entrypoints).
@@ -1160,7 +1441,7 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
     // graph and patching the published internal/index.d.ts:
     // - Re-apply ExtensionMethods wrappers (class + interface members)
     // - Preserve optional (`?`) semantics by allowing `undefined` on patched members
-    // - For exported interfaces, preserve source structural member types when safe
+    // - Preserve TS structural typing on interfaces/type-literal aliases (exported + local)
     const sourceIndexByFileKey = new Map();
     for (const m of modules) {
         // Synthetic IR modules (e.g., program-wide anonymous type declarations) do not
@@ -1177,6 +1458,7 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
     const overridesByInternalIndex = new Map();
     const brandOptionalTypesByInternalIndex = new Map();
     const functionSignaturesByFacade = new Map();
+    const sourceTypeImportsByFacade = new Map();
     for (const m of modules) {
         if (m.filePath.startsWith("__tsonic/"))
             continue;
@@ -1187,13 +1469,37 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
         const sourceIndex = sourceIndexByFileKey.get(moduleKey);
         if (!sourceIndex)
             continue;
+        const allInterfaces = m.body.filter((s) => s.kind === "interfaceDeclaration");
+        const allTypeAliases = m.body.filter((s) => s.kind === "typeAliasDeclaration");
         const hasExportedSourceFunctions = sourceIndex.exportedFunctionSignaturesByName.size > 0;
         if (exportedClasses.length === 0 &&
             exportedInterfaces.length === 0 &&
             exportedAliases.length === 0 &&
+            allInterfaces.length === 0 &&
+            allTypeAliases.length === 0 &&
             !hasExportedSourceFunctions)
             continue;
         const info = facadesByNamespace.get(m.namespace) ?? ensureFacade(m.namespace);
+        const brandTargets = brandOptionalTypesByInternalIndex.get(info.internalIndexDtsPath) ??
+            new Set();
+        for (const iface of allInterfaces) {
+            brandTargets.add(iface.name);
+        }
+        for (const alias of allTypeAliases) {
+            const sourceAlias = sourceIndex.typeAliasesByName.get(alias.name);
+            if (!sourceAlias)
+                continue;
+            const aliasType = unwrapParens(sourceAlias.type);
+            if (!ts.isTypeLiteralNode(aliasType))
+                continue;
+            const arity = sourceAlias.typeParameters.length;
+            const internalAliasName = `${alias.name}__Alias${arity > 0 ? `_${arity}` : ""}`;
+            brandTargets.add(alias.name);
+            brandTargets.add(internalAliasName);
+        }
+        if (brandTargets.size > 0) {
+            brandOptionalTypesByInternalIndex.set(info.internalIndexDtsPath, brandTargets);
+        }
         for (const [name, signatures,] of sourceIndex.exportedFunctionSignaturesByName) {
             if (signatures.length === 0)
                 continue;
@@ -1203,6 +1509,28 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
             list.push(...signatures);
             byName.set(name, list);
             functionSignaturesByFacade.set(info.facadeDtsPath, byName);
+            const importsByLocal = sourceTypeImportsByFacade.get(info.facadeDtsPath) ??
+                new Map();
+            for (const signature of signatures) {
+                for (const binding of collectSourceTypeImportsForSignature(signature, sourceIndex.typeImportsByLocalName)) {
+                    const existing = importsByLocal.get(binding.localName);
+                    if (existing) {
+                        if (existing.source !== binding.source ||
+                            existing.importedName !== binding.importedName) {
+                            return {
+                                ok: false,
+                                error: `Conflicting source type import alias '${binding.localName}' while augmenting ${info.facadeDtsPath}.\n` +
+                                    `- ${existing.importedName} from '${existing.source}'\n` +
+                                    `- ${binding.importedName} from '${binding.source}'\n` +
+                                    `Fix: disambiguate source type imports for exported function signatures.`,
+                            };
+                        }
+                        continue;
+                    }
+                    importsByLocal.set(binding.localName, binding);
+                }
+            }
+            sourceTypeImportsByFacade.set(info.facadeDtsPath, importsByLocal);
         }
         for (const cls of exportedClasses) {
             const memberTypes = sourceIndex.memberTypesByClassAndMember.get(cls.name);
@@ -1227,13 +1555,21 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
                 if (!wrappersResult.ok)
                     return wrappersResult;
                 const wrappers = wrappersResult.value;
-                if (wrappers.length === 0 && !sourceMember.isOptional)
+                const canUseSourceTypeText = !typeNodeUsesImportedTypeNames(sourceMember.typeNode, sourceIndex.typeImportsByLocalName);
+                if (!canUseSourceTypeText &&
+                    wrappers.length === 0 &&
+                    !sourceMember.isOptional) {
                     continue;
+                }
                 const list = overridesByInternalIndex.get(info.internalIndexDtsPath) ?? [];
                 list.push({
                     namespace: m.namespace,
                     className: cls.name,
                     memberName: member.name,
+                    sourceTypeText: canUseSourceTypeText
+                        ? sourceMember.typeText
+                        : undefined,
+                    replaceWithSourceType: canUseSourceTypeText,
                     isOptional: sourceMember.isOptional,
                     wrappers,
                 });
@@ -1272,14 +1608,11 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
                         : undefined,
                     replaceWithSourceType: canUseSourceTypeText,
                     isOptional: sourceMember.isOptional,
+                    emitOptionalPropertySyntax: true,
                     wrappers,
                 });
                 overridesByInternalIndex.set(info.internalIndexDtsPath, list);
             }
-            const brandTargets = brandOptionalTypesByInternalIndex.get(info.internalIndexDtsPath) ??
-                new Set();
-            brandTargets.add(iface.name);
-            brandOptionalTypesByInternalIndex.set(info.internalIndexDtsPath, brandTargets);
         }
         for (const alias of exportedAliases) {
             const sourceAlias = sourceIndex.typeAliasesByName.get(alias.name);
@@ -1290,10 +1623,6 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
                 continue;
             const arity = sourceAlias.typeParameters.length;
             const internalAliasName = `${alias.name}__Alias${arity > 0 ? `_${arity}` : ""}`;
-            const brandTargets = brandOptionalTypesByInternalIndex.get(info.internalIndexDtsPath) ??
-                new Set();
-            brandTargets.add(internalAliasName);
-            brandOptionalTypesByInternalIndex.set(info.internalIndexDtsPath, brandTargets);
             for (const member of aliasType.members) {
                 if (!ts.isPropertySignature(member))
                     continue;
@@ -1345,6 +1674,16 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
         if (!result.ok)
             return result;
     }
+    for (const [facadePath, importsByLocalName] of sourceTypeImportsByFacade) {
+        const result = ensureSourceTypeImportsForFacade(facadePath, importsByLocalName);
+        if (!result.ok)
+            return result;
+    }
+    for (const info of facadesByNamespace.values()) {
+        const result = ensureInternalTypeImportsForFacade(info.facadeDtsPath);
+        if (!result.ok)
+            return result;
+    }
     return { ok: true, value: undefined };
 };
 //# sourceMappingURL=library-bindings-augment.js.map