From d753660d66b0032a1c795b7b414d54b68e3927c9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 3 Jul 2026 21:38:42 +0800
Subject: [PATCH] docs(fs-local): a null before-image still renders a
 whole-file diff card
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The writeText comment still said a null `before` (a create or an
undiffable binary file) means "a consumer renders no result-time diff,
only the call-time whole-file card." That is stale since write's
presentResult renders a whole-file diff for a null before-image. Correct
it: a null `before` gives no contextual-hunk basis, so the consumer falls
back to a whole-file diff — the tool still renders a result diff card, not
the raw result text.
---
 packages/fs/fs-local/src/index.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index 30c65058c9..8ce96fe49d 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -148,8 +148,9 @@ export class LocalFileSystem extends FileSystem {
 
       // Capture the prior text (the before/after diff basis) BEFORE the write.
       // `null` for a create (no existing file) OR an existing-but-undiffable
-      // file (binary/invalid-UTF-8) — a consumer renders no result-time diff for
-      // either, only the call-time whole-file card.
+      // file (binary/invalid-UTF-8) — a null `before` gives no contextual-hunk
+      // basis, so a consumer falls back to a whole-file diff (the tool still
+      // renders a result-time diff card, not the raw result text).
       const before = existing ? await readTextForDiff(target.targetKey, signal) : null
       await writeFileAtomic(target.targetKey, content, existing?.mode, signal, this.internals)
       const after = await probe(target.targetKey)