@adhisang/minecraft-modding-mcp 4.2.1 → 6.0.0

package/dist/resources.js

@@ -30,7 +30,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
             throw e;
         }
     });
@@ -41,7 +41,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
             throw e;
         }
     });
@@ -50,13 +50,31 @@ export function registerResources(server, sourceService) {
         try {
             const result = await sourceService.getClassSource({
                 artifactId: params.artifactId,
-                className: decodeTemplateParam(params, "className")
+                className: decodeTemplateParam(params, "className"),
+                // A "text/x-java" source resource must return real Java, not the default
+                // metadata outline; match the sibling class-source-json resource.
+                mode: "full"
             });
             return textResource(uri.href, result.sourceText);
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
+            throw e;
+        }
+    });
+    server.resource("class-source-json", new ResourceTemplate("mc://source-json/{artifactId}/{className}", { list: undefined }), { description: "JSON envelope of a class's full source plus metadata (artifactId, mappingApplied, totalLines, returnedRange, provenance, warnings) — the structured alternative to the raw-text class-source resource, easier to cite and continue.", mimeType: "application/json" }, async (uri, params) => {
+        try {
+            const result = await sourceService.getClassSource({
+                artifactId: params.artifactId,
+                className: decodeTemplateParam(params, "className"),
+                mode: "full"
+            });
+            return objectResource(uri.href, result);
+        }
+        catch (e) {
+            if (isAppError(e))
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
             throw e;
         }
     });
@@ -70,15 +88,33 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
+            throw e;
+        }
+    });
+    server.resource("find-mapping", new ResourceTemplate("mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}", { list: undefined }), { description: "Look up a CLASS mapping between two naming namespaces. This URI carries no owner, so field/method lookups (which need an owner) must use the find-member-mapping resource or the find-mapping tool.", mimeType: "application/json" }, async (uri, params) => {
+        try {
+            const result = await sourceService.findMapping({
+                version: params.version,
+                kind: params.kind,
+                name: decodeTemplateParam(params, "name"),
+                sourceMapping: params.sourceMapping,
+                targetMapping: params.targetMapping
+            });
+            return objectResource(uri.href, result);
+        }
+        catch (e) {
+            if (isAppError(e))
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
             throw e;
         }
     });
-    server.resource("find-mapping", new ResourceTemplate("mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}", { list: undefined }), { description: "Look up a mapping for a class, field, or method between two naming namespaces.", mimeType: "application/json" }, async (uri, params) => {
+    server.resource("find-member-mapping", new ResourceTemplate("mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{owner}/{name}", { list: undefined }), { description: "Look up a FIELD or METHOD mapping between two naming namespaces, including the owner class the member belongs to (required for member lookups). For exact method overload resolution, use the find-mapping tool with a descriptor.", mimeType: "application/json" }, async (uri, params) => {
         try {
             const result = await sourceService.findMapping({
                 version: params.version,
                 kind: params.kind,
+                owner: decodeTemplateParam(params, "owner"),
                 name: decodeTemplateParam(params, "name"),
                 sourceMapping: params.sourceMapping,
                 targetMapping: params.targetMapping
@@ -87,7 +123,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
             throw e;
         }
     });
@@ -101,7 +137,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
             throw e;
         }
     });
@@ -112,7 +148,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
             throw e;
         }
     });

package/dist/response-utils.d.ts

@@ -46,14 +46,29 @@ export declare const TOOL_PRESERVE_PAYLOAD_KEYS: Record<string, ReadonlySet<stri
  * payload fields do not leak through as explicit nulls.
  */
 export declare function compactResponse(obj: Record<string, unknown>, preserveKeys?: ReadonlySet<string>): Record<string, unknown>;
-/** resolve-artifact compact: omit debug/diagnostic fields. */
-export declare function compactArtifactResponse(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * resolve-artifact compact: omit debug/diagnostic fields. When `include` is provided,
+ * any field protected by a present include group is kept (re-added).
+ */
+export declare function compactArtifactResponse(obj: Record<string, unknown>, include?: ReadonlySet<string>): Record<string, unknown>;
 /** get-class-source compact: drop provenance, artifactContents, qualityFlags. */
 export declare function compactSourceResponse(obj: Record<string, unknown>): Record<string, unknown>;
 /** get-class-members compact: drop provenance, artifactContents, qualityFlags, context. */
 export declare function compactMembersResponse(obj: Record<string, unknown>): Record<string, unknown>;
-/** Light compact projection: drop the artifactContents summary only. */
-export declare function compactLightResponse(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Default diagnostic strip for get-class-source / get-class-members. Drops the
+ * three diagnostic fields (provenance, artifactContents, qualityFlags) that the
+ * common path never needs, applied unless the caller passes includeProvenance.
+ * Unlike compactMembersResponse this KEEPS members' `context` — only compact:true
+ * drops context. Reuses SOURCE_COMPACT_OMIT_KEYS (exactly those three keys).
+ */
+export declare function stripSourceDiagnostics(obj: Record<string, unknown>): Record<string, unknown>;
+export declare function stripMembersDiagnostics(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Light compact projection: drop the artifactContents summary only. When `include`
+ * contains "artifact", the summary is kept (re-added).
+ */
+export declare function compactLightResponse(obj: Record<string, unknown>, include?: ReadonlySet<string>): Record<string, unknown>;
 /**
  * Mapping tool compact: project candidates for size reduction.
  *
@@ -67,3 +82,13 @@ export declare function compactLightResponse(obj: Record<string, unknown>): Reco
  *   seeing.
  */
 export declare function compactMappingResponse(obj: Record<string, unknown>): Record<string, unknown>;
+export type ResponseDetailLevel = "summary" | "standard" | "full";
+/** Expert + batch tools that accept the detail/include response contract. */
+export declare const DETAIL_ENABLED_TOOL_NAMES: Set<string>;
+/** Per-tool default detail level, chosen so default output is byte-identical to the old compact defaults. */
+export declare const DEFAULT_DETAIL_BY_TOOL: Record<string, ResponseDetailLevel>;
+/**
+ * Project an expert/batch tool result for the requested detail level + include set.
+ * Reuses the existing compact omit-sets; see the block comment above for the mapping.
+ */
+export declare function projectByDetail(tool: string, result: Record<string, unknown>, detail: ResponseDetailLevel, include: ReadonlySet<string>): Record<string, unknown>;

package/dist/response-utils.js

@@ -126,9 +126,32 @@ const ARTIFACT_COMPACT_OMIT_KEYS = new Set([
     "repoUrl",
     "resolvedSourceJarPath"
 ]);
-/** resolve-artifact compact: omit debug/diagnostic fields. */
-export function compactArtifactResponse(obj) {
-    return projectOmitKeys(obj, ARTIFACT_COMPACT_OMIT_KEYS);
+/**
+ * include-group => the resolve-artifact fields that group re-adds (un-omits) when present.
+ * Used by the detail/include projection so callers can opt specific diagnostics back in.
+ */
+const ARTIFACT_INCLUDE_PROTECTS = {
+    provenance: ["provenance"],
+    artifact: ["artifactContents"],
+    samples: ["sampleEntries"],
+    candidates: ["adjacentSourceCandidates"],
+    paths: ["binaryJarPath", "resolvedSourceJarPath", "coordinate", "repoUrl"]
+};
+/**
+ * resolve-artifact compact: omit debug/diagnostic fields. When `include` is provided,
+ * any field protected by a present include group is kept (re-added).
+ */
+export function compactArtifactResponse(obj, include) {
+    if (!include || include.size === 0) {
+        return projectOmitKeys(obj, ARTIFACT_COMPACT_OMIT_KEYS);
+    }
+    const omit = new Set(ARTIFACT_COMPACT_OMIT_KEYS);
+    for (const group of include) {
+        for (const protectedKey of ARTIFACT_INCLUDE_PROTECTS[group] ?? []) {
+            omit.delete(protectedKey);
+        }
+    }
+    return projectOmitKeys(obj, omit);
 }
 /** Fields to omit from get-class-source in compact mode. */
 const SOURCE_COMPACT_OMIT_KEYS = new Set([
@@ -151,12 +174,31 @@ const MEMBERS_COMPACT_OMIT_KEYS = new Set([
 export function compactMembersResponse(obj) {
     return projectOmitKeys(obj, MEMBERS_COMPACT_OMIT_KEYS);
 }
+/**
+ * Default diagnostic strip for get-class-source / get-class-members. Drops the
+ * three diagnostic fields (provenance, artifactContents, qualityFlags) that the
+ * common path never needs, applied unless the caller passes includeProvenance.
+ * Unlike compactMembersResponse this KEEPS members' `context` — only compact:true
+ * drops context. Reuses SOURCE_COMPACT_OMIT_KEYS (exactly those three keys).
+ */
+export function stripSourceDiagnostics(obj) {
+    return projectOmitKeys(obj, SOURCE_COMPACT_OMIT_KEYS);
+}
+export function stripMembersDiagnostics(obj) {
+    return projectOmitKeys(obj, SOURCE_COMPACT_OMIT_KEYS);
+}
 /** Fields to omit from search-class-source / list-artifact-files in compact mode. */
 const LIGHT_COMPACT_OMIT_KEYS = new Set([
     "artifactContents"
 ]);
-/** Light compact projection: drop the artifactContents summary only. */
-export function compactLightResponse(obj) {
+/**
+ * Light compact projection: drop the artifactContents summary only. When `include`
+ * contains "artifact", the summary is kept (re-added).
+ */
+export function compactLightResponse(obj, include) {
+    if (include?.has("artifact")) {
+        return obj;
+    }
     return projectOmitKeys(obj, LIGHT_COMPACT_OMIT_KEYS);
 }
 /** Max number of unresolved candidates that get full metadata in compact mode. */
@@ -224,4 +266,52 @@ export function compactMappingResponse(obj) {
     }
     return projected;
 }
+/** Expert + batch tools that accept the detail/include response contract. */
+export const DETAIL_ENABLED_TOOL_NAMES = COMPACT_ENABLED_TOOL_NAMES;
+/** Per-tool default detail level, chosen so default output is byte-identical to the old compact defaults. */
+export const DEFAULT_DETAIL_BY_TOOL = {
+    "resolve-artifact": "summary",
+    "find-mapping": "summary",
+    "resolve-method-mapping-exact": "summary",
+    "resolve-workspace-symbol": "summary",
+    "check-symbol-exists": "summary",
+    "get-class-source": "standard",
+    "get-class-members": "standard",
+    "search-class-source": "standard",
+    "list-artifact-files": "standard"
+};
+/** Extra keys omitted from get-class-members at detail=summary (beyond the diagnostic strip). */
+const MEMBERS_SUMMARY_EXTRA_OMIT = new Set(["context"]);
+/**
+ * Project an expert/batch tool result for the requested detail level + include set.
+ * Reuses the existing compact omit-sets; see the block comment above for the mapping.
+ */
+export function projectByDetail(tool, result, detail, include) {
+    let out = result;
+    // Phase-4 diagnostic strip for source/members, now detail/include-aware:
+    // kept at detail=full or when include opts provenance back in.
+    const keepDiagnostics = detail === "full" || include.has("provenance");
+    if (!keepDiagnostics) {
+        if (tool === "get-class-source")
+            out = stripSourceDiagnostics(out);
+        if (tool === "get-class-members")
+            out = stripMembersDiagnostics(out);
+    }
+    if (detail === "summary") {
+        if (tool === "resolve-artifact") {
+            out = compactArtifactResponse(out, include);
+        }
+        if (COMPACT_MAPPING_TOOL_NAMES.has(tool) && !include.has("candidates")) {
+            out = compactMappingResponse(out);
+        }
+        if (tool === "get-class-members") {
+            out = projectOmitKeys(out, MEMBERS_SUMMARY_EXTRA_OMIT);
+        }
+        if (COMPACT_LIGHT_TOOL_NAMES.has(tool)) {
+            out = compactLightResponse(out, include);
+        }
+        out = compactResponse(out, TOOL_PRESERVE_PAYLOAD_KEYS[tool]);
+    }
+    return out;
+}
 //# sourceMappingURL=response-utils.js.map

package/dist/source/access-validate.js

@@ -11,6 +11,11 @@ function normalizeAccessWidenerNamespace(namespace) {
     if (normalized === "named") {
         return "yarn";
     }
+    // Fabric/Loom call the obfuscated namespace "official"; treat it as obfuscated
+    // (matches the tiny-parser alias) instead of silently assuming intermediary.
+    if (normalized === "official") {
+        return "obfuscated";
+    }
     if (normalized === "obfuscated" ||
         normalized === "mojang" ||
         normalized === "intermediary" ||
@@ -39,8 +44,13 @@ export async function validateAccessWidener(svc, input) {
     const headerNamespaceRaw = normalizeOptionalString(parsed.namespace);
     const overrideMapping = input.mapping ? normalizeMapping(input.mapping) : undefined;
     const headerNamespace = normalizeAccessWidenerNamespace(headerNamespaceRaw);
-    if (!headerNamespace && headerNamespaceRaw && !overrideMapping) {
-        warnings.push(`Unsupported access widener namespace "${headerNamespaceRaw}". Assuming intermediary.`);
+    if (!headerNamespace && !overrideMapping) {
+        // No usable namespace resolved and no override: surface the intermediary
+        // assumption so it is never silent (previously only warned when a header
+        // namespace was present but unsupported).
+        warnings.push(headerNamespaceRaw
+            ? `Unsupported access widener namespace "${headerNamespaceRaw}". Assuming intermediary.`
+            : `Access widener namespace not declared; assuming intermediary. Pass mapping=… to set it explicitly.`);
     }
     const awNamespace = overrideMapping ?? headerNamespace ?? "intermediary";
     if (overrideMapping && headerNamespace && overrideMapping !== headerNamespace) {

package/dist/source/artifact-resolver.js

@@ -54,7 +54,7 @@ export function hasExactVersionToken(path, version) {
     // Avoid prefix false-positives like "1.21.1" matching "1.21.10".
     const cached = VERSION_TOKEN_REGEX_CACHE.get(normalizedVersion);
     const pattern = cached
-        ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, normalizedVersion, new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}([^0-9a-z]|$)`, "i"));
+        ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, normalizedVersion, new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}(?![0-9a-z]|\\.[0-9])`, "i"));
     return pattern.test(normalizedPath);
 }
 function inferMergedRuntimeNamespaceHint(path) {
@@ -1228,7 +1228,7 @@ export async function resolveArtifact(svc, input) {
         resolved.artifactAlias = artifactAlias;
         await svc.ingestIfNeeded(resolved);
         let sampleEntries;
-        if (input.compact === false && resolved.sourceJarPath) {
+        if (input.includeSampleEntries && resolved.sourceJarPath) {
             try {
                 const javaEntries = await listJavaEntries(resolved.sourceJarPath);
                 const MAX_SAMPLE = 10;

package/dist/source/class-source/members-builder.d.ts

@@ -31,5 +31,48 @@ export type MemberSliceResult = {
     methods: SignatureMember[];
     truncated: boolean;
     returnedTotal: number;
+    /** Absolute offset to resume from when more members remain after this page. */
+    nextOffset?: number;
 };
-export declare function sliceMembersWithLimit(remapped: Omit<RemappedMembers, "counts">, totalCount: number, maxMembers: number, warnings: string[]): MemberSliceResult;
+export declare function sliceMembersWithLimit(remapped: Omit<RemappedMembers, "counts">, totalCount: number, maxMembers: number, warnings: string[], offset?: number): MemberSliceResult;
+/** Slim per-member wire shape: only what an agent reading Java needs. */
+export type WireMember = {
+    name: string;
+    javaSignature: string;
+    /**
+     * JVM descriptor. Always present on methods/constructors (overload
+     * disambiguation for @At/@Shadow matching); omitted on FIELD members by
+     * default (the single type is already in javaSignature) unless
+     * keepFieldDescriptors is set.
+     */
+    jvmDescriptor?: string;
+    /** Present only when members span multiple owners (includeInherited). */
+    ownerFqn?: string;
+    /** Present only when true. */
+    isSynthetic?: boolean;
+};
+export type WireMembersBlock = {
+    /** Hoisted owner when every member shares one owner (the common, non-inherited case). */
+    ownerFqn?: string;
+    constructors: WireMember[];
+    fields: WireMember[];
+    methods: WireMember[];
+};
+/**
+ * Project the internal six-field SignatureMember arrays to the slim wire shape.
+ * `ownerFqn` is hoisted to the block level when all members share a single owner
+ * (so it is not repeated per member); when members span multiple owners — the
+ * includeInherited case — it stays per member and the block-level field is omitted.
+ * `accessFlags` is dropped (javaSignature already encodes the modifiers);
+ * `isSynthetic` is emitted only when true. `jvmDescriptor` is always kept on
+ * methods/constructors (overload disambiguation) and, on FIELD members, only when
+ * keepFieldDescriptors is set (the field's single type is already in javaSignature).
+ *
+ * The owner anchor is derived from the members themselves (not from the looked-up
+ * class name) so it is correct in the requested namespace regardless of remapping.
+ */
+export declare function projectMembersForWire(slice: {
+    constructors: SignatureMember[];
+    fields: SignatureMember[];
+    methods: SignatureMember[];
+}, includeInherited: boolean, keepFieldDescriptors?: boolean): WireMembersBlock;

package/dist/source/class-source/members-builder.js

@@ -23,13 +23,22 @@ export async function remapAndCountMembers(svc, input) {
     };
     return { constructors, fields, methods, counts };
 }
-export function sliceMembersWithLimit(remapped, totalCount, maxMembers, warnings) {
+export function sliceMembersWithLimit(remapped, totalCount, maxMembers, warnings, offset = 0) {
+    // Members form a single flat sequence in [constructors, fields, methods]
+    // order; offset skips that many from the start before taking maxMembers.
+    let toSkip = Math.max(0, offset);
     let remaining = maxMembers;
     const takeWithinLimit = (members) => {
+        if (toSkip >= members.length) {
+            toSkip -= members.length;
+            return [];
+        }
+        const afterSkip = toSkip > 0 ? members.slice(toSkip) : members;
+        toSkip = 0;
         if (remaining <= 0) {
             return [];
         }
-        const slice = members.slice(0, remaining);
+        const slice = afterSkip.slice(0, remaining);
         remaining -= slice.length;
         return slice;
     };
@@ -37,10 +46,48 @@ export function sliceMembersWithLimit(remapped, totalCount, maxMembers, warnings
     const fields = takeWithinLimit(remapped.fields);
     const methods = takeWithinLimit(remapped.methods);
     const returnedTotal = constructors.length + fields.length + methods.length;
-    const truncated = returnedTotal < totalCount;
+    const consumed = Math.min(Math.max(0, offset), totalCount) + returnedTotal;
+    const truncated = consumed < totalCount;
     if (truncated) {
         warnings.push(`Member list was truncated to ${returnedTotal} entries (from ${totalCount}).`);
     }
-    return { constructors, fields, methods, truncated, returnedTotal };
+    return {
+        constructors,
+        fields,
+        methods,
+        truncated,
+        returnedTotal,
+        ...(truncated ? { nextOffset: consumed } : {})
+    };
+}
+/**
+ * Project the internal six-field SignatureMember arrays to the slim wire shape.
+ * `ownerFqn` is hoisted to the block level when all members share a single owner
+ * (so it is not repeated per member); when members span multiple owners — the
+ * includeInherited case — it stays per member and the block-level field is omitted.
+ * `accessFlags` is dropped (javaSignature already encodes the modifiers);
+ * `isSynthetic` is emitted only when true. `jvmDescriptor` is always kept on
+ * methods/constructors (overload disambiguation) and, on FIELD members, only when
+ * keepFieldDescriptors is set (the field's single type is already in javaSignature).
+ *
+ * The owner anchor is derived from the members themselves (not from the looked-up
+ * class name) so it is correct in the requested namespace regardless of remapping.
+ */
+export function projectMembersForWire(slice, includeInherited, keepFieldDescriptors = false) {
+    const owners = new Set([...slice.constructors, ...slice.fields, ...slice.methods].map((m) => m.ownerFqn));
+    const hoistOwner = !includeInherited && owners.size === 1;
+    const toWire = (m, keepDescriptor) => ({
+        name: m.name,
+        javaSignature: m.javaSignature,
+        ...(keepDescriptor ? { jvmDescriptor: m.jvmDescriptor } : {}),
+        ...(hoistOwner ? {} : { ownerFqn: m.ownerFqn }),
+        ...(m.isSynthetic ? { isSynthetic: true } : {})
+    });
+    return {
+        ...(hoistOwner ? { ownerFqn: [...owners][0] } : {}),
+        constructors: slice.constructors.map((m) => toWire(m, true)),
+        fields: slice.fields.map((m) => toWire(m, keepFieldDescriptors)),
+        methods: slice.methods.map((m) => toWire(m, true))
+    };
 }
 //# sourceMappingURL=members-builder.js.map

package/dist/source/class-source/snippet-builder.d.ts

@@ -15,5 +15,18 @@ export type SnippetBuildResult = {
     returnedEnd: number;
     truncated: boolean;
     charsTruncated: boolean;
+    /**
+     * First line the caller has NOT yet fully received, when more source remains.
+     * Safe to pass back as `startLine` to continue reading. Undefined when the
+     * response already reached the end of the file.
+     */
+    nextStartLine?: number;
+    /**
+     * True when the requested window begins past the end of the file. The returned
+     * window is empty (returnedEnd < returnedStart) rather than clamped into the
+     * last real line, so paginated readers can detect overshoot instead of silently
+     * re-reading the final line.
+     */
+    outOfRange?: boolean;
 };
 export declare function buildClassSourceSnippet(input: SnippetBuildInput): SnippetBuildResult;

package/dist/source/class-source/snippet-builder.js

@@ -1,6 +1,13 @@
 import * as classSourceHelpers from "../class-source-helpers.js";
+import { sliceToMaxCharsSafe } from "../../text-truncate.js";
 export function buildClassSourceSnippet(input) {
-    const lines = input.content.split(/\r?\n/);
+    const rawLines = input.content.split(/\r?\n/);
+    // A trailing newline produces a final empty element that is not a real source
+    // line. Drop a single one so totalLines and line addressing reflect the actual
+    // source (decompiled Java almost always ends with a trailing newline).
+    const lines = rawLines.length > 1 && rawLines[rawLines.length - 1] === ""
+        ? rawLines.slice(0, -1)
+        : rawLines;
     const totalLines = lines.length;
     let sourceText;
     let returnedStart;
@@ -15,7 +22,20 @@ export function buildClassSourceSnippet(input) {
     else {
         const requestedStart = input.startLine ?? 1;
         const requestedEnd = input.endLine ?? totalLines;
-        const normalizedStart = Math.min(Math.max(1, requestedStart), Math.max(totalLines, 1));
+        if (requestedStart > totalLines) {
+            // The window begins past EOF: return an empty selection instead of clamping
+            // into the last real line, so paginated readers can detect the overshoot.
+            return {
+                sourceText: "",
+                totalLines,
+                returnedStart: requestedStart,
+                returnedEnd: requestedStart - 1,
+                truncated: true,
+                charsTruncated: false,
+                outOfRange: true
+            };
+        }
+        const normalizedStart = Math.max(1, requestedStart);
         const normalizedEnd = Math.min(Math.max(normalizedStart, requestedEnd), Math.max(totalLines, 1));
         let selectedLines = lines.slice(normalizedStart - 1, normalizedEnd);
         const clippedByRange = normalizedStart !== requestedStart || normalizedEnd !== requestedEnd;
@@ -30,9 +50,38 @@ export function buildClassSourceSnippet(input) {
         truncated = clippedByRange || clippedByMax;
     }
     if (input.maxChars != null && sourceText.length > input.maxChars) {
-        sourceText = sourceText.slice(0, input.maxChars);
+        sourceText = sliceToMaxCharsSafe(sourceText, input.maxChars);
         charsTruncated = true;
         truncated = true;
+        if (input.mode !== "metadata") {
+            const survivingNewlines = (sourceText.match(/\n/g) ?? []).length;
+            returnedEnd = sourceText.endsWith("\n")
+                ? returnedStart + survivingNewlines - 1
+                : returnedStart + survivingNewlines;
+        }
+    }
+    let nextStartLine;
+    // Metadata mode returns a synthesized outline, not a line window into the
+    // source, so its returnedStart/returnedEnd are not line-addressable and a
+    // char cut must not yield a (bogus) line continuation.
+    if (truncated && input.mode !== "metadata") {
+        if (charsTruncated) {
+            // A mid-line character cut may leave the final returned line partial.
+            // Count only the complete (newline-terminated) lines and resume from the
+            // first line not fully returned, re-reading any partial line in full.
+            // Require forward progress: when the cut lands inside the first returned
+            // line (no complete line returned), resuming at the same startLine with
+            // the same maxChars would loop, so emit no continuation — the caller must
+            // raise maxChars instead.
+            const completeLines = (sourceText.match(/\n/g) ?? []).length;
+            const resume = returnedStart + completeLines;
+            if (resume > returnedStart && resume <= totalLines) {
+                nextStartLine = resume;
+            }
+        }
+        else if (returnedEnd < totalLines) {
+            nextStartLine = returnedEnd + 1;
+        }
     }
     return {
         sourceText,
@@ -40,7 +89,8 @@ export function buildClassSourceSnippet(input) {
         returnedStart,
         returnedEnd,
         truncated,
-        charsTruncated
+        charsTruncated,
+        ...(nextStartLine != null ? { nextStartLine } : {})
     };
 }
 //# sourceMappingURL=snippet-builder.js.map

package/dist/source/class-source-helpers.d.ts

@@ -9,16 +9,16 @@ export declare function extractDecompiledMembers(className: string, filePath: st
     fields: DecompiledMember[];
     methods: DecompiledMember[];
 };
-export declare function computeLineBraceDepths(lines: string[]): number[];
+export declare function computeLineBraceDepths(lines: string[], strippedLines?: string[]): number[];
 export declare function computeBraceRange(lines: string[], symbols: Array<{
     symbolKind: string;
     symbolName: string;
     line: number;
-}>, simpleName: string): {
+}>, simpleName: string, strippedLines?: string[]): {
     declarationLine: number;
     endLine: number;
 } | undefined;
-export declare function scanBraceRange(lines: string[], declarationLine: number): {
+export declare function scanBraceRange(lines: string[], declarationLine: number, strippedLines?: string[]): {
     declarationLine: number;
     endLine: number;
 };
@@ -28,7 +28,7 @@ export declare function computeNestedTypeRanges(lines: string[], symbols: Array<
 }>, outerBody: {
     declarationLine: number;
     endLine: number;
-}): Array<{
+}, strippedLines?: string[]): Array<{
     declarationLine: number;
     endLine: number;
 }>;