@contractkit/plugin-typescript 0.20.0 → 0.21.0

package/dist/path-utils.d.ts

@@ -6,6 +6,17 @@ export declare function commonDir(files: string[], rootDir: string): string;
 export declare function computeOpOutPath(filePath: string, baseDir: string, output: string | undefined, defaultSuffix: string, commonRoot: string, meta?: Record<string, string>): string;
 export declare function computeContractOutPath(filePath: string, baseDir: string, output: string | undefined, defaultSuffix: string, commonRoot: string, meta?: Record<string, string>): string;
 export declare function computeSdkOutPath(filePath: string, rootDir: string, clientOutput: string | undefined, commonRoot: string, meta?: Record<string, string>): string | null;
+/**
+ * Resolve the output path for a synthesized `<area>.client.ts` — the file holding the
+ * `<Area>Client` class that aggregates an area's inlined methods and subarea wiring.
+ *
+ * Uses the same `output.clients` template as leaf clients, with `{filename}` and `{area}`
+ * substituted to the area name and `{subarea}` substituted to the empty string. Resulting
+ * double-slashes from the empty substitution are collapsed, and a final segment that
+ * would otherwise begin with a dot (e.g. `.client.ts` from `{subarea}.client.ts`) is
+ * prefixed with the area so the file isn't hidden.
+ */
+export declare function computeSdkAreaClientOutPath(area: string, rootDir: string, clientOutput: string | undefined): string;
 export declare function computeSdkTypeOutPath(filePath: string, rootDir: string, typeOutput: string, commonRoot: string, meta?: Record<string, string>): string | null;
 export declare function generateBarrelFiles(contractPaths: string[]): {
     outPath: string;

package/dist/path-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGtE,eAAO,MAAM,eAAe,QAAY,CAAC;AAEzC,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEtF;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAclE;AAID,wBAAgB,gBAAgB,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,CAiBR;AAED,wBAAgB,sBAAsB,CAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,CAER;AAID,wBAAgB,iBAAiB,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,GAAG,IAAI,CAkBf;AAED,wBAAgB,qBAAqB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,GAAG,IAAI,CAef;AAED,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAiBnG;AAED,wBAAgB,6BAA6B,CACzC,MAAM,EAAE,UAAU,EAAE,EACpB,YAAY,EAAE,gBAAgB,EAAE,EAChC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,gBAAgB,GAAE,GAAG,CAAC,MAAM,CAAa,GAC1C,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CA0CpB"}
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGtE,eAAO,MAAM,eAAe,QAAY,CAAC;AAEzC,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEtF;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAclE;AAID,wBAAgB,gBAAgB,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,CAiBR;AAED,wBAAgB,sBAAsB,CAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,CAER;AAID,wBAAgB,iBAAiB,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,GAAG,IAAI,CAkBf;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAoBnH;AAED,wBAAgB,qBAAqB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,GAAG,IAAI,CAef;AAED,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAiBnG;AAED,wBAAgB,6BAA6B,CACzC,MAAM,EAAE,UAAU,EAAE,EACpB,YAAY,EAAE,gBAAgB,EAAE,EAChC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,gBAAgB,GAAE,GAAG,CAAC,MAAM,CAAa,GAC1C,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CA0CpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
   "author": {
     "name": "Marooned Software",
@@ -29,8 +29,8 @@
     "@contractkit/core": "0.16.0"
   },
   "devDependencies": {
-    "@repo/config-typescript": "0.1.0",
-    "@repo/config-eslint": "0.3.1"
+    "@repo/config-eslint": "0.3.1",
+    "@repo/config-typescript": "0.1.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly --declaration",

package/src/codegen-sdk.ts

@@ -972,23 +972,25 @@ export interface SdkClientInfo {
 }
 
 /**
- * One area-level (no-subarea) `.ck` file whose methods are inlined directly into the
- * generated `<Area>Client` class instead of getting a standalone `*.client.ts`.
+ * One area-level (no-subarea) `.ck` file whose methods are merged into the area's
+ * `<Area>Client` (emitted to its own `<area>.client.ts`).
  */
 export interface SdkAreaInlineFile {
     /** Parsed AST. */
     root: OpRootNode;
-    /** Codegen options for this file (must have `outPath` pointing at the SDK aggregator file so type-import paths resolve correctly). */
+    /** Codegen options for this file (must have `outPath` pointing at the area client file so type-import paths resolve correctly). */
     codegenOptions: SdkCodegenOptions;
 }
 
 /** A grouping of files that share the same `keys.area`. */
 export interface SdkAreaInfo {
     area: string;
-    /** Files for which all methods are inlined into the area client (no subarea). */
-    inlineFiles: SdkAreaInlineFile[];
-    /** Per-file leaf clients exposed as named properties on the area client. */
-    subareaClients: { propertyName: string; client: SdkClientInfo }[];
+    /**
+     * Reference to the `<Area>Client` class — the file that holds it lives at
+     * `client.importPath` (relative to `sdk.ts`) and is generated separately by
+     * {@link generateAreaClient}. The aggregator just imports it.
+     */
+    client: SdkClientInfo;
 }
 
 export interface SdkAggregatorInput {
@@ -1002,88 +1004,105 @@ export interface SdkAggregatorInput {
     sdkClassName?: string;
 }
 
+/** Inputs to {@link generateAreaClient}. */
+export interface AreaClientInput {
+    /** Area name (e.g. `payments`). Drives the generated class name (`PaymentsClient`). */
+    area: string;
+    /** Output path of the generated `<area>.client.ts` file. Used to resolve relative type / leaf-client / sdk-options imports. */
+    outPath: string;
+    /** Files contributing inlined methods to the area client (typically area-level files with no subarea). */
+    inlineFiles: SdkAreaInlineFile[];
+    /** Subarea leaf clients exposed as named properties on the area client. */
+    subareaClients: { propertyName: string; client: SdkClientInfo }[];
+    /** Path to `sdk-options.ts`, used for `SdkFetch` and runtime helpers. */
+    sdkOptionsPath: string;
+}
+
 /**
- * Generate the SDK aggregator (`sdk.ts`) — the entry-point file consumers import.
+ * Generate a complete `<area>.client.ts` file: the `<Area>Client` class with
+ * subarea property fields, a constructor that wires them, and inlined methods
+ * merged from every area-level file in `inlineFiles`.
  *
- * Emits one `<Area>Client` class per area (combining inlined area-level methods with
- * subarea property wiring), one `class Sdk` exposing area properties + flat top-level
- * properties, plus all imports needed by the inlined methods.
+ * Emitted by the plugin alongside the per-leaf `*.client.ts` files. The SDK
+ * aggregator just imports the resulting class — see {@link generateSdkAggregator}.
  *
- * @throws if two area-level files in the same area produce the same method name.
+ * @throws if two area-level files contribute the same method name to the area —
+ * disambiguate via `sdk:` on the operation, or move one into a subarea.
  */
-export function generateSdkAggregator(input: SdkAggregatorInput): string {
-    const sdkOptionsImportPath = input.sdkOptionsImportPath ?? './sdk-options.js';
-    const sdkClassName = input.sdkClassName ?? 'Sdk';
-
-    // ── Pre-render inline method blocks per area (also collects type/runtime needs) ──
-    const inlinedByArea = new Map<string, { lines: string[]; methodNames: Set<string> }>();
-    const typesByImportPath = new Map<string, Set<string>>(); // path → set of type names
+export function generateAreaClient(input: AreaClientInput): string {
+    const { area, outPath, inlineFiles, subareaClients, sdkOptionsPath } = input;
+    const className = deriveAreaClientClassName(area);
+
+    // ── Merge inputs across all inline files ────────────────────────────────
+    const collectedMethodLines: string[] = [];
+    const seenMethods = new Set<string>();
+    const typesByImportPath = new Map<string, Set<string>>();
     const unresolvedTypes = new Set<string>();
     let needsJson = false;
     let needsBigIntReplacer = false;
     let needsBigIntReviver = false;
     let needsQueryString = false;
 
-    for (const area of input.areas) {
-        const collected: string[] = [];
-        const seenMethods = new Set<string>();
-        for (const inline of area.inlineFiles) {
-            const includeInternal = inline.codegenOptions.includeInternal ?? false;
-            // Collect method names + source lines
-            const { lines: methodLines, methodNames } = generateClientMethods(inline.root, inline.codegenOptions);
-            for (const name of methodNames) {
-                if (seenMethods.has(name)) {
-                    throw new Error(
-                        `[sdk] duplicate method '${name}' in area '${area.area}': two area-level files contribute the same method. Disambiguate via 'sdk:' or move one into a subarea.`,
-                    );
-                }
-                seenMethods.add(name);
+    for (const inline of inlineFiles) {
+        const includeInternal = inline.codegenOptions.includeInternal ?? false;
+        const { lines: methodLines, methodNames } = generateClientMethods(inline.root, inline.codegenOptions);
+        for (const name of methodNames) {
+            if (seenMethods.has(name)) {
+                throw new Error(
+                    `[sdk] duplicate method '${name}' in area '${area}': two area-level files contribute the same method. Disambiguate via 'sdk:' or move one into a subarea.`,
+                );
             }
-            collected.push(...methodLines);
-            // Side info for imports
-            if (sdkNeedsJson(inline.root, includeInternal)) needsJson = true;
-            if (sdkNeedsBigIntReplacer(inline.root, includeInternal)) needsBigIntReplacer = true;
-            if (sdkNeedsBigIntReviver(inline.root, includeInternal)) needsBigIntReviver = true;
-            if (sdkNeedsQueryString(inline.root, includeInternal)) needsQueryString = true;
-            // Type imports: rebuild what generateTypeImports would produce, but key by import path so multiple files merge
-            const typesForFile = collectTypes(inline.root, inline.codegenOptions.modelsWithInput, inline.codegenOptions.modelsWithOutput, includeInternal);
-            const { modelOutPaths, outPath } = inline.codegenOptions;
-            if (modelOutPaths && outPath) {
-                const fromDir = dirname(outPath);
-                for (const t of typesForFile) {
-                    const typeOutPath = modelOutPaths.get(t);
-                    if (typeOutPath) {
-                        let rel = relative(fromDir, typeOutPath).replace(/\.ts$/, '.js');
-                        if (!rel.startsWith('.')) rel = './' + rel;
-                        const set = typesByImportPath.get(rel) ?? new Set();
-                        set.add(t);
-                        typesByImportPath.set(rel, set);
-                    } else {
-                        unresolvedTypes.add(t);
-                    }
+            seenMethods.add(name);
+        }
+        collectedMethodLines.push(...methodLines);
+        if (sdkNeedsJson(inline.root, includeInternal)) needsJson = true;
+        if (sdkNeedsBigIntReplacer(inline.root, includeInternal)) needsBigIntReplacer = true;
+        if (sdkNeedsBigIntReviver(inline.root, includeInternal)) needsBigIntReviver = true;
+        if (sdkNeedsQueryString(inline.root, includeInternal)) needsQueryString = true;
+
+        // Resolve each file's type refs against THIS file's modelOutPaths, but
+        // produce import paths relative to the area client's outPath (not the
+        // contributing file's outPath, which pointed at the now-defunct sdk.ts).
+        const typesForFile = collectTypes(
+            inline.root,
+            inline.codegenOptions.modelsWithInput,
+            inline.codegenOptions.modelsWithOutput,
+            includeInternal,
+        );
+        const { modelOutPaths } = inline.codegenOptions;
+        if (modelOutPaths) {
+            const fromDir = dirname(outPath);
+            for (const t of typesForFile) {
+                const typeOutPath = modelOutPaths.get(t);
+                if (typeOutPath) {
+                    let rel = relative(fromDir, typeOutPath).replace(/\.ts$/, '.js');
+                    if (!rel.startsWith('.')) rel = './' + rel;
+                    const set = typesByImportPath.get(rel) ?? new Set();
+                    set.add(t);
+                    typesByImportPath.set(rel, set);
+                } else {
+                    unresolvedTypes.add(t);
                 }
             }
         }
-        inlinedByArea.set(area.area, { lines: collected, methodNames: seenMethods });
     }
 
-    // ── Imports ──
+    // ── Imports ─────────────────────────────────────────────────────────────
+    let sdkOptionsRel = relative(dirname(outPath), sdkOptionsPath).replace(/\.ts$/, '.js');
+    if (!sdkOptionsRel.startsWith('.')) sdkOptionsRel = './' + sdkOptionsRel;
+
     const lines: string[] = [];
     const jsonImport = needsJson ? ', JsonValue' : '';
-    lines.push(`import type { SdkFetch${jsonImport} } from '${sdkOptionsImportPath}';`);
+    lines.push(`import type { SdkFetch${jsonImport} } from '${sdkOptionsRel}';`);
     const valueImports: string[] = [];
     if (needsBigIntReplacer) valueImports.push('bigIntReplacer');
     if (needsBigIntReviver) valueImports.push('parseJson');
     if (needsQueryString) valueImports.push('buildQueryString');
     if (valueImports.length > 0) {
-        lines.push(`import { ${valueImports.join(', ')} } from '${sdkOptionsImportPath}';`);
+        lines.push(`import { ${valueImports.join(', ')} } from '${sdkOptionsRel}';`);
     }
-    lines.push(`import type { SdkOptions } from '${sdkOptionsImportPath}';`);
-    lines.push(`import { createSdkFetch } from '${sdkOptionsImportPath}';`);
 
-    // Type imports inlined from area-level files
-    const typeImportPaths = [...typesByImportPath.keys()].sort();
-    for (const path of typeImportPaths) {
+    for (const path of [...typesByImportPath.keys()].sort()) {
         const names = [...typesByImportPath.get(path)!].sort();
         lines.push(`import type { ${names.join(', ')} } from '${path}';`);
     }
@@ -1091,7 +1110,52 @@ export function generateSdkAggregator(input: SdkAggregatorInput): string {
         lines.push(`import type { ${t} } from './${pascalToDotCase(t)}.js';`);
     }
 
-    // Leaf client imports (top-level + subarea)
+    // Leaf client imports (subareas only — top-level clients live next to sdk.ts).
+    const importedClients = new Set<string>();
+    for (const sc of subareaClients) {
+        const key = `${sc.client.className}|${sc.client.importPath}`;
+        if (importedClients.has(key)) continue;
+        importedClients.add(key);
+        lines.push(`import { ${sc.client.className} } from '${sc.client.importPath}';`);
+    }
+    lines.push('');
+
+    // ── <Area>Client class ──────────────────────────────────────────────────
+    lines.push(`export class ${className} {`);
+    for (const sc of subareaClients) {
+        lines.push(`    readonly ${sc.propertyName}: ${sc.client.className};`);
+    }
+    if (subareaClients.length > 0) lines.push('');
+    if (collectedMethodLines.length > 0 || subareaClients.length > 0) {
+        const fetchModifier = collectedMethodLines.length > 0 ? 'private ' : '';
+        lines.push(`    constructor(${fetchModifier}fetch: SdkFetch) {`);
+        for (const sc of subareaClients) {
+            lines.push(`        this.${sc.propertyName} = new ${sc.client.className}(fetch);`);
+        }
+        lines.push('    }');
+    }
+    for (const ln of collectedMethodLines) lines.push(ln);
+    lines.push('}');
+    lines.push('');
+
+    return lines.join('\n');
+}
+
+/**
+ * Generate the SDK aggregator (`sdk.ts`) — the entry-point file consumers import.
+ *
+ * Imports every `<Area>Client` (one per area, generated by {@link generateAreaClient}
+ * to its own `<area>.client.ts`) and every leaf top-level client, then emits a
+ * `class Sdk` that exposes them as properties.
+ */
+export function generateSdkAggregator(input: SdkAggregatorInput): string {
+    const sdkOptionsImportPath = input.sdkOptionsImportPath ?? './sdk-options.js';
+    const sdkClassName = input.sdkClassName ?? 'Sdk';
+
+    const lines: string[] = [];
+    lines.push(`import type { SdkOptions } from '${sdkOptionsImportPath}';`);
+    lines.push(`import { createSdkFetch } from '${sdkOptionsImportPath}';`);
+
     const importedClients = new Set<string>();
     const pushClientImport = (c: SdkClientInfo): void => {
         const key = `${c.className}|${c.importPath}`;
@@ -1099,41 +1163,14 @@ export function generateSdkAggregator(input: SdkAggregatorInput): string {
         importedClients.add(key);
         lines.push(`import { ${c.className} } from '${c.importPath}';`);
     };
+    // Areas first, then top-level — keeps the aggregator's import order stable.
+    for (const area of input.areas) pushClientImport(area.client);
     for (const c of input.topLevelClients) pushClientImport(c);
-    for (const area of input.areas) {
-        for (const sc of area.subareaClients) pushClientImport(sc.client);
-    }
     lines.push('');
 
-    // ── <Area>Client classes ──
-    for (const area of input.areas) {
-        const areaClassName = deriveAreaClientClassName(area.area);
-        const inlined = inlinedByArea.get(area.area)!;
-        lines.push(`class ${areaClassName} {`);
-        // Subarea property declarations
-        for (const sc of area.subareaClients) {
-            lines.push(`    readonly ${sc.propertyName}: ${sc.client.className};`);
-        }
-        if (area.subareaClients.length > 0) lines.push('');
-        // Constructor
-        if (inlined.lines.length > 0 || area.subareaClients.length > 0) {
-            const fetchModifier = inlined.lines.length > 0 ? 'private ' : '';
-            lines.push(`    constructor(${fetchModifier}fetch: SdkFetch) {`);
-            for (const sc of area.subareaClients) {
-                lines.push(`        this.${sc.propertyName} = new ${sc.client.className}(fetch);`);
-            }
-            lines.push('    }');
-        }
-        // Inlined methods (already class-body indented)
-        for (const ln of inlined.lines) lines.push(ln);
-        lines.push('}');
-        lines.push('');
-    }
-
-    // ── Sdk aggregator ──
     lines.push(`export class ${sdkClassName} {`);
     for (const area of input.areas) {
-        lines.push(`    readonly ${deriveAreaPropertyName(area.area)}: ${deriveAreaClientClassName(area.area)};`);
+        lines.push(`    readonly ${deriveAreaPropertyName(area.area)}: ${area.client.className};`);
     }
     for (const c of input.topLevelClients) {
         lines.push(`    readonly ${c.propertyName}: ${c.className};`);
@@ -1142,7 +1179,7 @@ export function generateSdkAggregator(input: SdkAggregatorInput): string {
     lines.push('    constructor(options: SdkOptions) {');
     lines.push('        const sdkFetch = options.fetch ?? createSdkFetch(options);');
     for (const area of input.areas) {
-        lines.push(`        this.${deriveAreaPropertyName(area.area)} = new ${deriveAreaClientClassName(area.area)}(sdkFetch);`);
+        lines.push(`        this.${deriveAreaPropertyName(area.area)} = new ${area.client.className}(sdkFetch);`);
     }
     for (const c of input.topLevelClients) {
         lines.push(`        this.${c.propertyName} = new ${c.className}(sdkFetch);`);

package/src/index.ts

@@ -25,8 +25,11 @@ import {
     generateSdk,
     generateSdkOptions,
     generateSdkAggregator,
+    generateAreaClient,
     deriveClientClassName,
     deriveClientPropertyName,
+    deriveAreaClientClassName,
+    deriveAreaPropertyName,
     deriveSubareaClientClassName,
     deriveSubareaPropertyName,
     getAreaSubarea,
@@ -42,6 +45,7 @@ import {
     computeOpOutPath,
     computeContractOutPath,
     computeSdkOutPath,
+    computeSdkAreaClientOutPath,
     computeSdkTypeOutPath,
     generateBarrelFiles,
     computePubliclyReachableTypes,
@@ -548,12 +552,13 @@ function collectSdkOutput(
     }
 
     // ── Global files: sdk-options, aggregator, barrels, root index ──
-    // The aggregator inlines area-only op roots, so its content depends on each inline root's
-    // full AST. Caching it gains little — the codegen is fast and any inline-root change rebuilds
-    // the file anyway. Same for barrels (one line per imported file). Always regenerate.
+    // sdk-options.ts is a constant; the aggregator is small (just imports + a wrapper class)
+    // and depends on the cross-cutting client list, so it's cheap to regenerate every run.
+    // Per-area `<area>.client.ts` files are cached as their own units below.
     globalFiles.push({ relativePath: sdkOptionsPath, content: generateSdkOptions() });
 
     const hasAnything = sdkClientInfos.length > 0 || areaBuckets.size > 0;
+    const areaClientOutPaths = new Map<string, string>(); // area → absolute outPath of <area>.client.ts
     if (hasAnything) {
         const sdkEntryDir = dirname(sdkEntryPath);
         const sdkOptionsRel = relative(sdkEntryDir, sdkOptionsPath).replace(/\.ts$/, '.js');
@@ -565,52 +570,104 @@ function collectSdkOutput(
                   .join('') + 'Sdk'
             : 'Sdk';
 
-        const toClientImport = (info: { outPath: string; className: string; propertyName: string }): SdkClientInfo => {
-            let rel = relative(sdkEntryDir, info.outPath).replace(/\.ts$/, '.js');
+        const toClientImport = (sourceDir: string, info: { outPath: string; className: string; propertyName: string }): SdkClientInfo => {
+            let rel = relative(sourceDir, info.outPath).replace(/\.ts$/, '.js');
             if (!rel.startsWith('.')) rel = './' + rel;
             return { className: info.className, propertyName: info.propertyName, importPath: rel };
         };
 
-        const topLevelClients: SdkClientInfo[] = topLevelEntries.map(e => ({
-            className: deriveClientClassName(e.ast.file),
-            propertyName: deriveClientPropertyName(e.ast.file),
-            importPath: (() => {
-                const rel = relative(sdkEntryDir, e.outPath).replace(/\.ts$/, '.js');
-                return rel.startsWith('.') ? rel : './' + rel;
-            })(),
-        }));
-
-        const areas: SdkAreaInfo[] = [...areaBuckets.entries()]
-            .sort(([a], [b]) => a.localeCompare(b))
-            .map(([area, bucket]) => ({
-                area,
-                inlineFiles: bucket.inlineRoots.map(root => ({
-                    root,
-                    codegenOptions: {
-                        typeImportPathTemplate: undefined,
-                        outPath: sdkEntryPath,
-                        modelOutPaths: sdkModelOutPaths,
-                        sdkOptionsPath,
-                        modelsWithInput,
-                        modelsWithOutput,
-                        includeInternal: config.includeInternal,
-                    },
-                })),
-                subareaClients: bucket.leaves
-                    .sort((a, b) => a.subarea.localeCompare(b.subarea))
-                    .map(l => ({
+        const topLevelClients: SdkClientInfo[] = topLevelEntries.map(e =>
+            toClientImport(sdkEntryDir, {
+                outPath: e.outPath,
+                className: deriveClientClassName(e.ast.file),
+                propertyName: deriveClientPropertyName(e.ast.file),
+            }),
+        );
+
+        // ── Per-area `<area>.client.ts` units ──
+        const areaInfos: SdkAreaInfo[] = [];
+        const sortedAreas = [...areaBuckets.entries()].sort(([a], [b]) => a.localeCompare(b));
+        for (const [area, bucket] of sortedAreas) {
+            const areaClientOutPath = computeSdkAreaClientOutPath(area, sdkBase, config.output!.clients);
+            areaClientOutPaths.set(area, areaClientOutPath);
+            const areaClassName = deriveAreaClientClassName(area);
+            const areaPropertyName = deriveAreaPropertyName(area);
+            sdkClientInfos.push({ outPath: areaClientOutPath, className: areaClassName, propertyName: areaPropertyName });
+
+            const subareaClients = bucket.leaves
+                .sort((a, b) => a.subarea.localeCompare(b.subarea))
+                .map(l => ({
+                    propertyName: deriveSubareaPropertyName(l.subarea),
+                    client: toClientImport(dirname(areaClientOutPath), {
+                        outPath: l.outPath,
+                        className: deriveSubareaClientClassName(area, l.subarea),
                         propertyName: deriveSubareaPropertyName(l.subarea),
-                        client: toClientImport({
-                            outPath: l.outPath,
-                            className: deriveSubareaClientClassName(area, l.subarea),
-                            propertyName: deriveSubareaPropertyName(l.subarea),
-                        }),
-                    })),
+                    }),
+                }));
+
+            // Fingerprint covers every input the area client depends on:
+            //  - all inline roots (full AST)
+            //  - subarea client metadata (className / propertyName / import path)
+            //  - the modelOutPaths slice for refs across all inline roots
+            //  - modelsWithInput/Output slices
+            const allInlineRefs = new Set<string>();
+            for (const r of bucket.inlineRoots) {
+                for (const ref of collectOpRootRefs(r, modelMap)) allInlineRefs.add(ref);
+            }
+            const fingerprint = hashFingerprint({
+                kind: 'sdk-area-client',
+                v: TYPESCRIPT_CODEGEN_VERSION,
+                outPath: areaClientOutPath,
+                area,
+                inlineRoots: bucket.inlineRoots,
+                subareaClients,
+                outPathSlice: sliceOutPathMap(allInlineRefs, sdkModelOutPaths, modelsWithInput, modelsWithOutput),
+                modelsWithInput: sliceModelSet(allInlineRefs, new Set(), modelsWithInput),
+                modelsWithOutput: sliceModelSet(allInlineRefs, new Set(), modelsWithOutput),
+                sdkOptionsPath,
+                includeInternal: config.includeInternal ?? false,
+                sub: subConfigKey,
+            });
+
+            const inlineFilesForGen = bucket.inlineRoots.map(root => ({
+                root,
+                codegenOptions: {
+                    typeImportPathTemplate: undefined,
+                    outPath: areaClientOutPath,
+                    modelOutPaths: sdkModelOutPaths,
+                    sdkOptionsPath,
+                    modelsWithInput,
+                    modelsWithOutput,
+                    includeInternal: config.includeInternal,
+                },
             }));
 
+            units.push({
+                key: `sdk-area-client::${areaClientOutPath}`,
+                fingerprint,
+                render: () => [
+                    {
+                        relativePath: areaClientOutPath,
+                        content: generateAreaClient({
+                            area,
+                            outPath: areaClientOutPath,
+                            inlineFiles: inlineFilesForGen,
+                            subareaClients,
+                            sdkOptionsPath,
+                        }),
+                    },
+                ],
+            });
+
+            areaInfos.push({
+                area,
+                client: toClientImport(sdkEntryDir, { outPath: areaClientOutPath, className: areaClassName, propertyName: areaPropertyName }),
+            });
+        }
+
         globalFiles.push({
             relativePath: sdkEntryPath,
-            content: generateSdkAggregator({ topLevelClients, areas, sdkOptionsImportPath, sdkClassName }),
+            content: generateSdkAggregator({ topLevelClients, areas: areaInfos, sdkOptionsImportPath, sdkClassName }),
         });
     }
 

package/src/path-utils.ts

@@ -96,6 +96,38 @@ export function computeSdkOutPath(
     return join(baseOutDir, relDir, defaultOutName);
 }
 
+/**
+ * Resolve the output path for a synthesized `<area>.client.ts` — the file holding the
+ * `<Area>Client` class that aggregates an area's inlined methods and subarea wiring.
+ *
+ * Uses the same `output.clients` template as leaf clients, with `{filename}` and `{area}`
+ * substituted to the area name and `{subarea}` substituted to the empty string. Resulting
+ * double-slashes from the empty substitution are collapsed, and a final segment that
+ * would otherwise begin with a dot (e.g. `.client.ts` from `{subarea}.client.ts`) is
+ * prefixed with the area so the file isn't hidden.
+ */
+export function computeSdkAreaClientOutPath(area: string, rootDir: string, clientOutput: string | undefined): string {
+    const filename = area;
+    const baseOutDir = resolve(rootDir);
+    const fixHiddenSegment = (path: string): string => {
+        const segments = path.split('/');
+        const last = segments[segments.length - 1] ?? '';
+        if (last.startsWith('.')) segments[segments.length - 1] = `${filename}${last}`;
+        return segments.join('/');
+    };
+    if (clientOutput && TEMPLATE_VAR_RE.test(clientOutput)) {
+        const resolved = resolveTemplate(clientOutput, { filename, dir: '', ext: 'ck', area, subarea: '' });
+        const cleaned = fixHiddenSegment(resolved.replace(/\/+/g, '/').replace(/^\//, ''));
+        if (includesFilename(cleaned)) return join(baseOutDir, cleaned);
+        return join(baseOutDir, cleaned, `${filename}.client.ts`);
+    }
+    if (clientOutput) {
+        if (includesFilename(clientOutput)) return join(baseOutDir, clientOutput);
+        return join(baseOutDir, clientOutput, `${filename}.client.ts`);
+    }
+    return join(baseOutDir, `${filename}.client.ts`);
+}
+
 export function computeSdkTypeOutPath(
     filePath: string,
     rootDir: string,