pi-hashline-edit-pro 2.8.4 → 3.0.1

package/src/hashline/hash.ts

@@ -7,36 +7,20 @@ import {
   persistSnapshot,
 } from "../hash-store";
 import { xxh32, initHasher } from "./hasher";
-import { HASH_LEN, ALPH, ALPH_RE, HASH_CLASS, HASH_RUN } from "./alphabet";
-export { initHasher, HASH_LEN, ALPH_RE, HASH_CLASS, HASH_RUN };
+import { HASH_LEN, ANCHOR_COUNT, anchorAt, anchorIndex, HASH_CLASS, HASH_RUN } from "./alphabet";
+export { initHasher, HASH_LEN, HASH_CLASS, HASH_RUN };
 
 export const ANCHOR_LEN = HASH_LEN;
 
 export const HASH_SEP = "│";
 
-export const HASH_SPACE = ALPH.length ** HASH_LEN;
+export const HASH_SPACE = ANCHOR_COUNT;
 export const MAX_HASH_LINES = HASH_SPACE;
 
-export const HASH_PROBE_STRIDE = ALPH.length ** 2 + ALPH.length + 1;
-
-function idxToHash(idx: number): string {
-  let out = "";
-  for (let j = 0; j < HASH_LEN; j++) {
-    out = ALPH[idx % ALPH.length]! + out;
-    idx = Math.floor(idx / ALPH.length);
-  }
-  return out;
-}
-
-const hashCache = new Map<number, string>();
+export const HASH_PROBE_STRIDE = 571;
 
 function hashAt(idx: number): string {
-  let hash = hashCache.get(idx);
-  if (hash === undefined) {
-    hash = idxToHash(idx);
-    hashCache.set(idx, hash);
-  }
-  return hash;
+  return anchorAt(idx);
 }
 
 export const HL_PREFIX_PLUS_RE = new RegExp(
@@ -182,13 +166,7 @@ export async function lineHashes(
 }
 
 function hashToIndex(hash: string): number {
-  let idx = 0;
-  for (let j = 0; j < HASH_LEN; j++) {
-    const charIdx = ALPH.indexOf(hash[j]!);
-    if (charIdx < 0) return -1;
-    idx = idx * ALPH.length + charIdx;
-  }
-  return idx;
+  return anchorIndex(hash);
 }
 
 function nearestNew(

package/src/hashline/parse.ts

@@ -1,8 +1,8 @@
 import {
 	ANCHOR_LEN,
-	ALPH_RE,
 	HASH_CLASS,
 } from "./hash";
+import { ALPH_RE } from "./alphabet";
 import { NEW_CONTENT_NOT_ARRAY_MSG } from "../constants";
 
 const HASH_EXTRACT_RE = new RegExp(HASH_CLASS);
@@ -13,11 +13,11 @@ function diagRef(ref: string): string {
 	const trimmed = ref.trim();
 
 	if (!trimmed.length) {
-		return `[E_BAD_REF] Invalid anchor. Expected a 3-char alphanumeric anchor (e.g. "aB3").`;
+		return `[E_BAD_REF] Invalid anchor. Expected a 4-char alphanumeric anchor (e.g. "Hasu").`;
 	}
 
 	if (/^\d+/.test(trimmed)) {
-		return `[E_BAD_REF] Invalid anchor. Use the anchor alone (e.g. "aB3"): no line numbers or trailing content.`;
+		return `[E_BAD_REF] Invalid anchor. Use the anchor alone (e.g. "Hasu"): no line numbers or trailing content.`;
 	}
 	if (trimmed.includes("│") && trimmed.includes("\n")) {
 		const lines = trimmed.split(/\r?\n/);
@@ -26,16 +26,16 @@ function diagRef(ref: string): string {
 		const hashRe = HASH_EXTRACT_RE;
 		const firstMatch = first.match(hashRe);
 		const lastMatch = last.match(hashRe);
-		const firstHash = firstMatch?.[0] ?? "aB3";
-		const lastHash = lastMatch?.[0] ?? "aB3";
+		const firstHash = firstMatch?.[0] ?? "Hasu";
+		const lastHash = lastMatch?.[0] ?? "Hasu";
 		const preview = first.slice(0, 60);
-		return `[E_BAD_REF] Invalid anchor — remove_from and remove_to must each be a single bare 3-char hash (e.g. "aB3"), not a block with HASH│content. Received ${lines.length} lines starting "${preview}…" — use only the first hash "${firstHash}" as remove_from and "${lastHash}" as remove_to, and put the new content (without HASH│) in replacement_lines.`;
+		return `[E_BAD_REF] Invalid anchor — remove_from and remove_to must each be a single bare 4-char hash (e.g. "Hasu"), not a block with HASH│content. Received ${lines.length} lines starting "${preview}…" — use only the first hash "${firstHash}" as remove_from and "${lastHash}" as remove_to, and put the new content (without HASH│) in replacement_lines.`;
 	}
 	if (trimmed.includes("│")) {
-		return `[E_BAD_REF] Invalid anchor "${trimmed}": use only the 3-char anchor, drop everything from "│" onward.`;
+		return `[E_BAD_REF] Invalid anchor "${trimmed}": use only the 4-char anchor, drop everything from "│" onward.`;
 	}
 
-	return `[E_BAD_REF] Invalid anchor "${trimmed}". Expected a 3-char alphanumeric anchor (e.g. "aB3").`;
+	return `[E_BAD_REF] Invalid anchor "${trimmed}". Expected a 4-char alphanumeric anchor (e.g. "Hasu").`;
 }
 
 function parseRef(ref: string): Anchor {
@@ -60,7 +60,13 @@ function unwrapJsonEnvelope(line: string, warnings?: string[]): string {
   if (!match) return line;
   const withoutDot = line.trim().slice(0, -1);
   try {
-    JSON.parse(withoutDot);
+    const parsed: unknown = JSON.parse(withoutDot);
+    if (Array.isArray(parsed) && parsed.length === 1 && typeof parsed[0] === "string") {
+      warnings?.push(
+        '[E_BAD_SHAPE] Unwrapped JSON array syntax from a replacement_lines element.',
+      );
+      return parsed[0];
+    }
     return line;
   } catch {
     warnings?.push(

package/src/hashline/resolve.ts

@@ -159,12 +159,12 @@ function assertItem(edit: Record<string, unknown>): void {
 
   if ("remove_from" in edit && typeof edit.remove_from !== "string") {
     throw new Error(
-      `[E_BAD_SHAPE] Field "remove_from" must be an anchor string (3-char anchor).`,
+      `[E_BAD_SHAPE] Field "remove_from" must be an anchor string (4-char anchor).`,
     );
   }
   if ("remove_to" in edit && typeof edit.remove_to !== "string") {
     throw new Error(
-      `[E_BAD_SHAPE] Field "remove_to" must be an anchor string (3-char anchor).`,
+      `[E_BAD_SHAPE] Field "remove_to" must be an anchor string (4-char anchor).`,
     );
   }
   if (!("replacement_lines" in edit)) {
@@ -175,7 +175,7 @@ function assertItem(edit: Record<string, unknown>): void {
   }
   if (typeof edit.remove_from !== "string" || typeof edit.remove_to !== "string") {
     throw new Error(
-      `[E_BAD_SHAPE] The edit requires "remove_from" and "remove_to" anchor strings (3-char anchors from read output).`,
+      `[E_BAD_SHAPE] The edit requires "remove_from" and "remove_to" anchor strings (4-char anchors from read output).`,
     );
   }
 }

package/src/insert.ts

@@ -8,7 +8,7 @@ import { MAX_HASH_LINES, parseHashRef, resolveAnchorLine, type Anchor } from "./
 import { stripAnchorRow } from "./hashline/resolve";
 import { loadP, loadGuide } from "./prompts";
 import { normReq } from "./payload-contract";
-import { isRec, rejectUnknownFields, splitLines } from "./utils";
+import { decodeStringArray, isRec, rejectUnknownFields, splitLines } from "./utils";
 import { clearBoundaryBypass } from "./boundary-bypass";
 import type { RPreview, RRState } from "./replace-render";
 import { queuedEdit, editToolBase, editRenderCallWrapper, editRenderResultWrapper } from "./edit-common";
@@ -31,7 +31,7 @@ export function assertInsertReq(request: unknown): asserts request is InsertReq
     throw new Error('[E_BAD_SHAPE] Insert request requires a non-empty "path" string.');
   }
   if (typeof request.anchor !== "string" || request.anchor.length === 0) {
-    throw new Error('[E_BAD_SHAPE] Insert request requires an "anchor" string (3-char anchor from read output).');
+    throw new Error('[E_BAD_SHAPE] Insert request requires an "anchor" string (4-char anchor from read output).');
   }
   if (request.direction !== "before" && request.direction !== "after") {
     throw new Error('[E_BAD_SHAPE] Insert request "direction" must be "before" or "after".');
@@ -49,23 +49,23 @@ const insertToolSchema = Type.Object(
     }),
     anchor: Type.String({
       description:
-        'Bare 3-char anchor only (e.g. "aB3"): copy just the anchor from the leftmost column of a read row like `aB3│content`; never the line content. A pasted diff row like `+aB3│x` or an `anchor│` prefix is stripped automatically with a warning. The anchored line is preserved; the new lines go after or before it.',
+        'Bare 4-char anchor from a read row like `Hasu│content`, never the content. A pasted `+Hasu│x` diff row or `anchor│` prefix is stripped with a warning. The anchor line is preserved; lines go after or before it.',
     }),
     direction: Type.Union(
       [
-        Type.Literal("after", { description: "Insert the lines after the anchor line" }),
-        Type.Literal("before", { description: "Insert the lines before the anchor line" }),
+        Type.Literal("after"),
+        Type.Literal("before"),
       ],
       { description: '"after" or "before"' },
     ),
     lines: Type.Array(
       Type.String({
         description:
-          "One line to insert. Each element is exactly one line; do not embed \\n inside an element: use separate elements.",
+          "One line to insert; never embed \\n inside an element.",
       }),
       {
         description:
-          'Lines to insert as an array of strings, one element per line. Use [""] for a blank line. The anchor line is preserved; never include it in lines.',
+          'One string per line; [""] is a blank line; never include the anchor line.',
       }
     ),
   },
@@ -101,15 +101,20 @@ function buildInsertEdit(
   return { editParams, anchorLine };
 }
 
-export async function insertPreview(request: unknown, cwd: string): Promise<RPreview> {
+export async function insertPreview(request: unknown, cwd: string, signal?: AbortSignal): Promise<RPreview> {
   try {
     const normalized = normReq(request);
+    if (isRec(normalized)) {
+      const expanded = decodeStringArray(normalized.lines);
+      if (expanded) normalized.lines = expanded;
+    }
     assertInsertReq(normalized);
     const { ref } = parseInsertAnchor(normalized.anchor);
     const preload = await readNormFile(normalized.path, cwd, {
       accessMode: constants.R_OK,
       maxLines: MAX_HASH_LINES,
       noPersist: true,
+      signal,
     });
     const { editParams } = buildInsertEdit(normalized, preload, ref);
     const pipe = await execPipeline(editParams, cwd, {
@@ -117,9 +122,11 @@ export async function insertPreview(request: unknown, cwd: string): Promise<RPre
       noPersist: true,
       preloadedNorm: preload,
       skipBoundaryDedup: true,
+      signal,
     });
     return previewFromPipe(pipe);
   } catch (error: unknown) {
+    if (signal?.aborted) throw error;
     return previewError(error);
   }
 }
@@ -163,6 +170,14 @@ export function buildInsertToolDef(): InsertToolDef {
     renderResult: editRenderResultWrapper,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const canonical = normReq(params);
+      const insertWarnings: string[] = [];
+      if (isRec(canonical)) {
+        const expanded = decodeStringArray(canonical.lines);
+        if (expanded) {
+          insertWarnings.push('[E_BAD_SHAPE] Unwrapped JSON array syntax from a lines element.');
+          canonical.lines = expanded;
+        }
+      }
       assertInsertReq(canonical);
       const req = canonical;
       const path = req.path;
@@ -188,7 +203,7 @@ export function buildInsertToolDef(): InsertToolDef {
           verb: "inserted",
           noopNoun: "Insertion",
           foldedAnchorLines: anchorLine === undefined ? 0 : 1,
-          prefixWarnings: anchorWarnings,
+          prefixWarnings: [...anchorWarnings, ...insertWarnings],
           onApplied: () => clearBoundaryBypass(mutationTargetPath),
         });
       });

package/src/payload-contract.ts

@@ -4,22 +4,22 @@ import { isRec, normalizeFilePath, rejectUnknownFields } from "./utils";
 const replacementLinesSchema = Type.Array(
   Type.String({
     description:
-      "One replacement line. Each element is exactly one line; do not embed \\n inside an element: use separate elements.",
+      "One replacement line; never embed \\n inside an element.",
   }),
   {
     description:
-      "Replacement lines as an array of strings, one element per line. Use [] to delete the range.",
+      "One string per line. Use [] to delete the range.",
   },
 );
 
 const removeFromSchema = Type.String({
   description:
-    "Bare 3-char anchor only (e.g. \"aB3\"): copy just the anchor from the leftmost column of a read row like `aB3│content`; never the line content. Marks the FIRST line to remove (inclusive)",
+    "Bare 4-char anchor from a read row like `Hasu│content` (the leftmost column), never the row content. Marks the FIRST line to remove (inclusive)",
 });
 
 const removeToSchema = Type.String({
   description:
-    "Bare 3-char anchor only (e.g. \"aB3\"): copy just the anchor from the leftmost column of a read row like `aB3│content`; never the line content. Marks the LAST line to remove (inclusive)",
+    "Bare 4-char anchor from a read row like `Hasu│content` (the leftmost column), never the row content. Marks the LAST line to remove (inclusive)",
 });
 
 export const editToolSchema = Type.Object(
@@ -27,7 +27,7 @@ export const editToolSchema = Type.Object(
     path: Type.Optional(
       Type.String({
         description:
-          "Path to edit. Required: always provide it explicitly; it is only auto-resolved from the anchors as a fallback when omitted by mistake.",
+          "Path to edit; always provide it explicitly — it is only auto-resolved from the anchors as a fallback.",
       }),
     ),
     remove_from: removeFromSchema,

package/src/replace-diff.ts

@@ -4,7 +4,10 @@ import {
   _lineHashesPure,
   ANCHOR_LEN,
   HASH_SEP,
+  changedRange,
 } from "./hashline";
+import { MAX_DIFF_INPUT_BYTES } from "./constants";
+import { splitLines } from "./utils";
 import {
   detectEnding,
   toLF,
@@ -48,9 +51,63 @@ export function genDiff(
   oldContentHashes?: string[],
   limits?: DiffLimits,
 ): { diff: string; firstChangedLine: number | undefined; lineNumbers: (number|undefined)[] } {
-  const effectiveNewHashes = newContentHashes ?? _lineHashesPure(newContent);
   const maxLineBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxLineBytes ?? DEFAULT_MAX_BYTES);
   const maxBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxBytes ?? DEFAULT_MAX_BYTES);
+  if (!limits?.unlimited && Buffer.byteLength(oldContent, "utf-8") + Buffer.byteLength(newContent, "utf-8") > MAX_DIFF_INPUT_BYTES) {
+    const guardedRange = changedRange(oldContent, newContent);
+    const guardNote = `[diff truncated at ${formatSize(maxBytes)}; use read to see the rest.]`;
+    if (!guardedRange || !newContentHashes) {
+      return { diff: ` ...\n${guardNote}`, firstChangedLine: guardedRange?.firstChangedLine, lineNumbers: [undefined, undefined] };
+    }
+    const newLines = splitLines(newContent);
+    const oldLines = splitLines(oldContent);
+    const first = guardedRange.firstChangedLine;
+    const last = guardedRange.lastChangedLine;
+    const suffixLen = newLines.length - last;
+    const oldLast = oldLines.length - suffixLen;
+    const beforeStart = Math.max(1, first - contextLines);
+    const afterEnd = Math.min(newLines.length, last + contextLines);
+    const guarded: string[] = [];
+    const guardedNumbers: (number|undefined)[] = [];
+    let guardedBytes = 0;
+    const pushGuarded = (text: string, num?: number): boolean => {
+      const size = Buffer.byteLength(text, "utf-8") + 1;
+      if (guardedBytes + size > maxBytes) return false;
+      guardedBytes += size;
+      guarded.push(text);
+      guardedNumbers.push(num);
+      return true;
+    };
+    const pushGuardedRow = (prefix: " " | "+" | "-", line: string, hash: string | undefined, num?: number): boolean => {
+      const full = fmtDiffLine(prefix, line, hash);
+      if (Buffer.byteLength(full, "utf-8") > maxLineBytes) {
+        const marker = `[Row is ${formatSize(Buffer.byteLength(full, "utf-8"))}, exceeds ${formatSize(maxLineBytes)}; content not shown. Use read to see the full line.]`;
+        return pushGuarded(fmtDiffLine(prefix, marker, hash), num);
+      }
+      return pushGuarded(full, num);
+    };
+    if (beforeStart > 1) pushGuarded(" ...", undefined);
+    for (let n = beforeStart; n < first; n++) {
+      if (!pushGuardedRow(" ", newLines[n - 1]!, newContentHashes[n - 1], n)) break;
+    }
+    if (oldContent.length > 0) {
+      for (let n = first; n <= Math.min(oldLast, oldLines.length); n++) {
+        if (!pushGuardedRow("-", oldLines[n - 1]!, oldContentHashes?.[n - 1], n)) break;
+      }
+    }
+    for (let n = first; n <= last; n++) {
+      if (!pushGuardedRow("+", newLines[n - 1]!, newContentHashes[n - 1], n)) break;
+    }
+    for (let n = last + 1; n <= afterEnd; n++) {
+      if (!pushGuardedRow(" ", newLines[n - 1]!, newContentHashes[n - 1], n)) break;
+    }
+    guarded.push(" ...");
+    guardedNumbers.push(undefined);
+    guarded.push(guardNote);
+    guardedNumbers.push(undefined);
+    return { diff: guarded.join("\n"), firstChangedLine: first, lineNumbers: guardedNumbers };
+  }
+  const effectiveNewHashes = newContentHashes ?? _lineHashesPure(newContent);
 
   const parts = Diff.diffLines(oldContent, newContent);
   const output: string[] = [];

package/src/replace-render.ts

@@ -19,6 +19,7 @@ export type RRState = {
 	preview?: RPreview;
 	previewGeneration?: number;
 	previewTimer?: ReturnType<typeof setTimeout>;
+	previewAbort?: AbortController;
 };
 
 type DiffRowKind = "added" | "removed" | "context";
@@ -232,7 +233,7 @@ export function reuseMarkdown(context: any, content: string, theme: any): Markdo
 }
 
 export function makeRenderCall(
-	preview: (args: unknown, cwd: string) => Promise<RPreview>,
+	preview: (args: unknown, cwd: string, signal?: AbortSignal) => Promise<RPreview>,
 	options: { getInput?: (args: unknown) => { path?: string } | null; toolName?: string } = {},
 ) {
 	const getInput = options.getInput ?? getPreviewInput;
@@ -244,6 +245,10 @@ export function makeRenderCall(
 				clearTimeout(context.state.previewTimer);
 				context.state.previewTimer = undefined;
 			}
+			if (context.state.previewAbort) {
+				context.state.previewAbort.abort();
+				context.state.previewAbort = undefined;
+			}
 		};
 		if (context.executionStarted) {
 			cancelPendingPreview();
@@ -265,8 +270,12 @@ export function makeRenderCall(
 				context.state.previewGeneration = previewGeneration;
 				context.state.previewTimer = setTimeout(() => {
 					context.state.previewTimer = undefined;
-					preview(args, context.cwd)
+					const controller = new AbortController();
+					context.state.previewAbort = controller;
+					preview(args, context.cwd, controller.signal)
 						.then((result) => {
+							if (controller.signal.aborted) return;
+							if (context.state.previewAbort === controller) context.state.previewAbort = undefined;
 							if (
 								context.state.argsKey === argsKey &&
 								context.state.previewGeneration === previewGeneration
@@ -276,6 +285,8 @@ export function makeRenderCall(
 							}
 						})
 						.catch((err: unknown) => {
+							if (controller.signal.aborted) return;
+							if (context.state.previewAbort === controller) context.state.previewAbort = undefined;
 							if (
 								context.state.argsKey === argsKey &&
 								context.state.previewGeneration === previewGeneration
@@ -311,6 +322,10 @@ export function renderEditResult(
 			clearTimeout(renderState.previewTimer);
 			renderState.previewTimer = undefined;
 		}
+		if (renderState.previewAbort) {
+			renderState.previewAbort.abort();
+			renderState.previewAbort = undefined;
+		}
 		renderState.preview = undefined;
 		renderState.previewGeneration = (renderState.previewGeneration ?? 0) + 1;
 	}

package/src/replace-undo.ts

@@ -105,6 +105,9 @@ export function regUndo(pi: ExtensionAPI): void {
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const path = params.path;
+      if (typeof path !== "string" || path.length === 0) {
+        throw new Error('[E_BAD_SHAPE] Undo request requires a non-empty "path" string.');
+      }
       const { resolved: mutationTargetPath } = await resolveInCwd(path, ctx.cwd);
 
       const undo = await getUndo(mutationTargetPath);

package/src/replace.ts

@@ -9,7 +9,7 @@ import {
 } from "./replace-diff";
 import { readNormFile, type NormFile } from "./file-reader";
 import { editToolSchema, type ReqParams, assertReq, normReq } from "./payload-contract";
-import { isRec } from "./utils";
+import { decodeStringArray, isRec } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { type FileIdentity } from "./fs-write";
 import { applyEdit,
@@ -160,11 +160,17 @@ export async function execPipeline(
   const path = params.path;
 
   const editWarnings: string[] = [];
+  let replacementLines = params.replacement_lines;
+  const expandedReplacement = decodeStringArray(replacementLines);
+  if (expandedReplacement) {
+    editWarnings.push('[E_BAD_SHAPE] Unwrapped JSON array syntax from a replacement_lines element.');
+    replacementLines = expandedReplacement;
+  }
   const edit = resEdit(
     {
       remove_from: params.remove_from,
       remove_to: params.remove_to,
-      replacement_lines: params.replacement_lines,
+      replacement_lines: replacementLines,
     },
     editWarnings,
   );
@@ -246,6 +252,7 @@ export function previewError(error: unknown): RPreview {
 export async function compPreview(
   request: unknown,
   cwd: string,
+  signal?: AbortSignal,
 ): Promise<RPreview> {
   try {
     const normalized = normReq(request);
@@ -253,10 +260,11 @@ export async function compPreview(
     const pipe = await execPipeline(
       normalized,
       cwd,
-      { accessMode: constants.R_OK, noPersist: true },
+      { accessMode: constants.R_OK, noPersist: true, signal },
     );
     return previewFromPipe(pipe);
   } catch (error: unknown) {
+    if (signal?.aborted) throw error;
     return previewError(error);
   }
 }

package/src/served.ts

@@ -1,4 +1,5 @@
 import { loadHashStore, parseStoredServed, STORE_NOT_OPEN_MESSAGE, withStore, type HashStore } from "./hash-store";
+import { withBusyRetry } from "./hash-store/retry";
 import { HASH_CLASS } from "./hashline/alphabet";
 import { contentChecksum } from "./hashline/hasher";
 
@@ -37,7 +38,7 @@ export function buildServedMap(fileHashes: string[], fileLines: string[], wanted
 }
 
 export function getServed(store: HashStore, path: string): Map<string, string> | undefined {
-  const row = store.stmts.servedGet(path);
+  const row = withBusyRetry(() => store.stmts.servedGet(path));
   const parsed = parseStoredServed(row, () => store.stmts.servedDelete(path));
   if (!parsed) return undefined;
   return parsed;

package/src/utils.ts

@@ -114,7 +114,7 @@ export function getCached<K, V>(map: Map<K, V>, key: K, compute: (key: K) => V):
 }
 
 export function isHashRow(line: string): boolean {
-	return /^[A-Za-z0-9]{3}│/.test(line);
+	return /^[A-Za-z0-9]{4}│/.test(line);
 }
 
 function gutterWidth(max: number, fallback: number): number {
@@ -168,3 +168,84 @@ function formatLineLimit(displayPath: string, limit: number, count: number | und
 	const detail = count === undefined ? `has more than ${limit}` : `has ${count}`;
 	return `[E_FILE_TOO_LARGE] ${displayPath} ${detail} lines, exceeding the ${limit}-line hashline limit. For very large files, use write.`;
 }
+
+function escapeRawControl(value: string): string {
+	if (value === "\b") return "\\b";
+	if (value === "\t") return "\\t";
+	if (value === "\n") return "\\n";
+	if (value === "\f") return "\\f";
+	if (value === "\r") return "\\r";
+	const hex = value.charCodeAt(0).toString(16).padStart(4, "0");
+	return `\\u${hex}`;
+}
+
+function escapeControls(value: string): string {
+	let out = "";
+	for (const char of value) {
+		out += char.charCodeAt(0) < 32 ? escapeRawControl(char) : char;
+	}
+	return out;
+}
+
+function decodeArraySegment(segment: string): string | undefined {
+	const trimmed = segment.trim();
+	if (trimmed.length < 2 || !trimmed.startsWith('"') || !trimmed.endsWith('"')) return undefined;
+	try {
+		const cleaned = escapeControls(trimmed);
+		const parsed: unknown = JSON.parse(cleaned);
+		return typeof parsed === "string" ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function splitArraySegments(inner: string): string[] | undefined {
+	const segments: string[] = [];
+	let current = "";
+	let inQuotes = false;
+	let escaped = false;
+	for (const char of inner) {
+		if (inQuotes) {
+			current += char;
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === '"') inQuotes = false;
+			continue;
+		}
+		if (char === '"') {
+			inQuotes = true;
+			current += char;
+			continue;
+		}
+		if (char === ",") {
+			segments.push(current);
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	if (inQuotes || escaped) return undefined;
+	segments.push(current);
+	return segments;
+}
+
+function decodeArrayText(value: unknown): string[] | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return undefined;
+	const segments = splitArraySegments(trimmed.slice(1, -1));
+	if (!segments) return undefined;
+	const decoded: string[] = [];
+	for (const segment of segments) {
+		const part = decodeArraySegment(segment);
+		if (part === undefined) return undefined;
+		decoded.push(part);
+	}
+	return decoded.length > 0 ? decoded : undefined;
+}
+
+export function decodeStringArray(value: unknown): string[] | undefined {
+	if (typeof value === "string") return decodeArrayText(value);
+	if (Array.isArray(value) && value.length === 1) return decodeArrayText(value[0]);
+	return undefined;
+}