@oh-my-pi/hashline 15.5.15 → 15.7.0

package/dist/types/apply.d.ts

@@ -5,4 +5,4 @@ import type { ApplyResult, Edit } from "./types";
  * Returns the post-edit text and the first changed line number (1-indexed).
  * Throws if an anchor is out of bounds.
  */
-export declare function applyEdits(text: string, edits: Edit[]): ApplyResult;
+export declare function applyEdits(text: string, edits: readonly Edit[]): ApplyResult;

package/dist/types/block.d.ts

@@ -0,0 +1,24 @@
+import type { BlockResolver, Edit } from "./types";
+export interface ResolveBlockEditsOptions {
+    /**
+     * How to handle a block edit that cannot be resolved (missing resolver or a
+     * `null` span). `"throw"` (default) raises a `blockUnresolvedMessage` error —
+     * used by the authoritative apply + final preview paths. `"drop"` silently
+     * skips the edit — used by the streaming preview, where a half-written file
+     * or transient parse error must not throw.
+     */
+    onUnresolved?: "throw" | "drop";
+}
+/** True when at least one edit is an unresolved `replace block N:` edit. */
+export declare function hasBlockEdit(edits: readonly Edit[]): boolean;
+/**
+ * Resolve every `replace block N:` edit in `edits` against `text` (parsed as
+ * the language inferred from `path`). Non-block edits pass through untouched.
+ * Returns a fresh edit list with no `block` variants. The fast path returns the
+ * input unchanged when there is nothing to resolve.
+ *
+ * Synthesized inserts/deletes carry sequential `index` values for readability
+ * only — {@link applyEdits} re-derives every edit's index from array order, so
+ * the passthrough edits keeping their original indices is harmless.
+ */
+export declare function resolveBlockEdits(edits: readonly Edit[], text: string, path: string, resolver: BlockResolver | undefined, options?: ResolveBlockEditsOptions): readonly Edit[];

package/dist/types/format.d.ts

@@ -10,6 +10,8 @@ export declare const HL_FILE_PREFIX = "\u00B6";
 export declare const HL_PAYLOAD_REPLACE = "+";
 /** Hunk-header keyword for concrete line replacement. */
 export declare const HL_REPLACE_KEYWORD = "replace";
+/** Hunk-header sub-keyword: `replace block N:` resolves N to a tree-sitter block range. */
+export declare const HL_BLOCK_KEYWORD = "block";
 /** Hunk-header keyword for concrete line deletion. */
 export declare const HL_DELETE_KEYWORD = "delete";
 /** Hunk-header keyword for insertion operations. */

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./apply";
+export * from "./block";
 export * from "./diff-preview";
 export * from "./format";
 export * from "./fs";

package/dist/types/input.d.ts

@@ -1,4 +1,4 @@
-import type { ApplyResult, Edit, SplitOptions } from "./types";
+import type { ApplyResult, BlockResolver, Edit, SplitOptions } from "./types";
 interface RawSection {
     path: string;
     fileHash?: string;
@@ -49,16 +49,23 @@ export declare class PatchSection {
      * {@link Patcher} owns tag validation and recovery; reach for this
      * method directly when you've already validated the file content and
      * just want the result.
+     *
+     * `blockResolver` resolves any `replace block N:` edits against `text`; an
+     * unresolvable block throws (this is the final, authoritative preview path).
      */
-    applyTo(text: string): ApplyResult;
+    applyTo(text: string, blockResolver?: BlockResolver): ApplyResult;
     /**
      * Streaming-tolerant counterpart to {@link applyTo}. Uses
      * {@link parsePatchStreaming} so a trailing in-flight op (no payload yet,
      * or a per-token parse error mid-stream) does not throw or emit a phantom
      * empty-payload edit. Intended for incremental diff previews; the writer
      * path should always use {@link applyTo}.
+     *
+     * `blockResolver` resolves any `replace block N:` edits against `text`; an
+     * unresolvable block is silently dropped so a half-written file does not
+     * throw mid-stream.
      */
-    applyPartialTo(text: string): ApplyResult;
+    applyPartialTo(text: string, blockResolver?: BlockResolver): ApplyResult;
 }
 /**
  * A parsed hashline patch — zero or more {@link PatchSection}s, each rooted

package/dist/types/messages.d.ts

@@ -26,8 +26,32 @@ export declare const BARE_BODY_AUTO_PIPED_WARNING = "Auto-prefixed bare body row
 export declare const MINUS_ROW_REJECTED = "`-` rows are not valid; hashline ranges already name the lines being changed. To insert a literal line starting with `-`, write `+-\u2026`.";
 /** Error text emitted when a replace hunk has no body. */
 export declare const EMPTY_REPLACE = "`replace N..M:` needs at least one `+TEXT` body row. To delete lines, use `delete N..M`.";
+/** Error text emitted when a `replace block N:` hunk has no body. */
+export declare const EMPTY_BLOCK = "`replace block N:` needs at least one `+TEXT` body row. To delete a block, use `delete N..M` with the block's line range.";
+/**
+ * Error text emitted when a `replace block N:` anchor cannot be resolved to a
+ * syntactic block (unrecognized language, blank/out-of-range line, no node
+ * begins on line N such as a lone closing delimiter, or the resolved block has
+ * a syntax error). Names the offending line and steers back to an explicit
+ * `replace N..M:` range.
+ */
+export declare function blockUnresolvedMessage(line: number): string;
+/**
+ * Error text emitted when a `replace block N:` edit reaches a code path that
+ * has no {@link BlockResolver} wired in. Indicates a host-configuration bug
+ * rather than authored-input error.
+ */
+export declare const BLOCK_RESOLVER_UNAVAILABLE = "`replace block N:` is not available here (no tree-sitter block resolver is configured). Use `replace N..M:` with an explicit range.";
+/**
+ * Internal invariant error: `applyEdits` received an unresolved `replace block
+ * N:` edit. Block edits must be expanded by `resolveBlockEdits` before reaching
+ * the applier; hitting this is a wiring bug, not authored-input error.
+ */
+export declare const UNRESOLVED_BLOCK_INTERNAL = "internal error: unresolved `replace block` edit reached the applier (resolveBlockEdits was not run).";
 /** Error text emitted when a delete hunk receives a body row. */
 export declare const DELETE_TAKES_NO_BODY = "`delete N..M` does not take body rows. Remove the body, or use `replace N..M:`.";
+/** Error text emitted when a `delete block N` hunk receives a body row. */
+export declare const DELETE_BLOCK_TAKES_NO_BODY = "`delete block N` does not take body rows. Remove the body, or use `replace block N:` to replace the block.";
 /** Error text emitted when an insert hunk has no body. */
 export declare const EMPTY_INSERT = "`insert` needs at least one `+TEXT` body row.";
 /** Warning text emitted by `Recovery` when an external write fits a cached snapshot. */
@@ -44,3 +68,18 @@ export declare const RECOVERY_SESSION_CHAIN_WARNING = "Recovered from a stale fi
  * model verifies before continuing.
  */
 export declare const RECOVERY_SESSION_REPLAY_WARNING = "Recovered by replaying your edits onto the current file content \u2014 your previous edit in this session changed line(s) you re-targeted with a stale hash. Verify the diff matches your intent before continuing.";
+/**
+ * Warning emitted when an `insert head:` / `insert tail:` edit is applied to an
+ * existing file whose snapshot tag is stale (the file drifted since the read).
+ * Head/tail insert position is content-independent — "start"/"end" cannot move
+ * with drift — so this is non-fatal: the edit applies onto the live content and
+ * we surface the drift instead of hard-failing (unlike an anchored mismatch).
+ */
+export declare const HEADTAIL_DRIFT_WARNING = "Applied an `insert head:`/`insert tail:` edit onto the current file content even though the snapshot tag was stale (the file changed since your read). Head/tail position is content-independent, so the insert was not rejected \u2014 but re-read if the drift was unexpected.";
+/**
+ * Error text emitted when a hashline section omits the mandatory snapshot tag.
+ * The tag is REQUIRED on every section, enforced identically by the apply path
+ * ({@link Patcher.prepare}) and the preview/diff path, so both surfaces reuse
+ * this single builder to stay in lockstep.
+ */
+export declare function missingSnapshotTagMessage(sectionPath: string): string;

package/dist/types/patcher.d.ts

@@ -3,12 +3,18 @@ import type { Patch, PatchSection } from "./input";
 import { type LineEnding } from "./normalize";
 import { Recovery } from "./recovery";
 import type { SnapshotStore } from "./snapshots";
-import type { ApplyResult } from "./types";
+import type { ApplyResult, BlockResolver } from "./types";
 export interface PatcherOptions {
     /** Storage backend used for all reads and writes. */
     fs: Filesystem;
     /** Snapshot store that minted and resolves hashline section tags. Required. */
     snapshots: SnapshotStore;
+    /**
+     * Resolves `replace block N:` anchors to concrete line spans via tree-sitter.
+     * Optional: when omitted, any `replace block N:` edit throws on apply (the
+     * host did not wire a resolver). Plain line-range ops never need it.
+     */
+    blockResolver?: BlockResolver;
 }
 /** Per-section result returned by {@link Patcher.apply} / {@link Patcher.commit}. */
 export interface PatchSectionResult {
@@ -69,6 +75,7 @@ export declare class Patcher {
     readonly fs: Filesystem;
     readonly snapshots: SnapshotStore;
     readonly recovery: Recovery;
+    readonly blockResolver: BlockResolver | undefined;
     constructor(options: PatcherOptions);
     /**
      * Apply every section in `patch`. `prepare` runs the full apply for each

package/dist/types/tokenizer.d.ts

@@ -6,9 +6,15 @@ export declare function parseLid(raw: string, lineNum: number): Anchor;
 export type BlockTarget = {
     kind: "replace";
     range: ParsedRange;
+} | {
+    kind: "block";
+    anchor: Anchor;
 } | {
     kind: "delete";
     range: ParsedRange;
+} | {
+    kind: "delete_block";
+    anchor: Anchor;
 } | {
     kind: "insert_before";
     anchor: Anchor;

package/dist/types/types.d.ts

@@ -39,6 +39,22 @@ export type Edit = {
     lineNum: number;
     index: number;
     oldAssertion?: string;
+} | {
+    /**
+     * Deferred block edit (`replace block N:` / `delete block N`). The exact
+     * line span is unknown at parse time — it is computed by
+     * {@link resolveBlockEdits} once file text + path (→ language) are
+     * available, then expanded into concrete edits: a non-empty `payloads`
+     * (from `replace block`) becomes the same `replacement` inserts + deletes
+     * that `replace start..end:` produces; an empty `payloads` (from `delete
+     * block`) becomes a pure range deletion. `applyEdits` never sees this
+     * variant.
+     */
+    kind: "block";
+    anchor: Anchor;
+    payloads: string[];
+    lineNum: number;
+    index: number;
 };
 /** Result of applying a parsed set of edits to a text body. */
 export interface ApplyResult {
@@ -85,3 +101,29 @@ export interface CompactDiffOptions {
     /** Maximum entries kept on each side of an unchanged-context truncation (default 2). */
     maxUnchangedRun?: number;
 }
+/**
+ * Resolved 1-indexed inclusive line span of a `replace block N:` target.
+ */
+export interface BlockSpan {
+    /** First line of the block (1-indexed, inclusive). */
+    start: number;
+    /** Last line of the block (1-indexed, inclusive). */
+    end: number;
+}
+/** Request handed to a {@link BlockResolver} to resolve one `replace block N:` anchor. */
+export interface BlockResolverRequest {
+    /** Target file path (used to infer language by extension). */
+    path: string;
+    /** Full text the block must be resolved against (the snapshot the tag names). */
+    text: string;
+    /** 1-indexed line the block must begin on. */
+    line: number;
+}
+/**
+ * Resolves a `replace block N:` anchor to the line span of the syntactic block
+ * that begins on line N. Returns `null` when no block can be resolved
+ * (unrecognized language, blank/out-of-range line, no node begins there, or the
+ * resolved subtree has a syntax error). Pure seam: the hashline core declares
+ * the contract; the host injects a tree-sitter-backed implementation.
+ */
+export type BlockResolver = (request: BlockResolverRequest) => BlockSpan | null;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "15.5.15",
+	"version": "15.7.0",
 	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -34,7 +34,7 @@
 	},
 	"dependencies": {
 		"diff": "^9.0.0",
-		"lru-cache": "11.3.6"
+		"lru-cache": "11.5.1"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/apply.ts

@@ -7,6 +7,7 @@
  * which fixes the common model mistake of a payload that duplicates or drops
  * the closing delimiter bordering the range (balance-validated; see below).
  */
+import { UNRESOLVED_BLOCK_INTERNAL } from "./messages";
 import { cloneCursor } from "./tokenizer";
 import type { Anchor, ApplyResult, Cursor, Edit } from "./types";
 
@@ -29,7 +30,7 @@ function getCursorAnchors(cursor: Cursor): Anchor[] {
 	return cursor.kind === "before_anchor" || cursor.kind === "after_anchor" ? [cursor.anchor] : [];
 }
 
-function getEditAnchors(edit: Edit): Anchor[] {
+function getEditAnchors(edit: AppliedEdit): Anchor[] {
 	if (edit.kind === "delete") return [edit.anchor];
 	return getCursorAnchors(edit.cursor);
 }
@@ -407,9 +408,17 @@ function repairBoundaryBalance(
  * Returns the post-edit text and the first changed line number (1-indexed).
  * Throws if an anchor is out of bounds.
  */
-export function applyEdits(text: string, edits: Edit[]): ApplyResult {
+export function applyEdits(text: string, edits: readonly Edit[]): ApplyResult {
 	if (edits.length === 0) return { text, firstChangedLine: undefined };
 
+	// Block edits are deferred until `resolveBlockEdits` expands them into
+	// concrete inserts + deletes. Reaching the applier with one still present
+	// is an internal wiring bug, not authored-input error.
+	for (const edit of edits) {
+		if (edit.kind === "block") throw new Error(UNRESOLVED_BLOCK_INTERNAL);
+	}
+	const appliedEdits = edits as readonly AppliedEdit[];
+
 	const fileLines = text.split("\n");
 	const lineOrigins: LineOrigin[] = fileLines.map(() => "original");
 
@@ -418,7 +427,7 @@ export function applyEdits(text: string, edits: Edit[]): ApplyResult {
 		if (firstChangedLine === undefined || line < firstChangedLine) firstChangedLine = line;
 	};
 
-	const targetEdits = edits.map((edit, index) => cloneAppliedEdit(edit, index));
+	const targetEdits = appliedEdits.map((edit, index) => cloneAppliedEdit(edit, index));
 	validateLineBounds(targetEdits, fileLines);
 	const { edits: repaired, warnings } = repairBoundaryBalance(targetEdits, fileLines);
 

package/src/block.ts

@@ -0,0 +1,84 @@
+/**
+ * Expand deferred `replace block N:` edits into concrete inserts + deletes.
+ *
+ * The hashline parser cannot expand a block edit on its own — the line span is
+ * unknown until file text + path (→ language) are available. This transform
+ * runs at every apply/preview boundary that has text: it calls the injected
+ * {@link BlockResolver} to resolve each block's `[start, end]` span, then emits
+ * the exact same `before_anchor` replacement inserts + range deletes that
+ * `replace start..end:` produces in the parser. After it runs, no `block` edits
+ * remain, so {@link applyEdits} (and recovery) only ever see resolved edits.
+ */
+import { BLOCK_RESOLVER_UNAVAILABLE, blockUnresolvedMessage } from "./messages";
+import type { BlockResolver, Cursor, Edit } from "./types";
+
+export interface ResolveBlockEditsOptions {
+	/**
+	 * How to handle a block edit that cannot be resolved (missing resolver or a
+	 * `null` span). `"throw"` (default) raises a `blockUnresolvedMessage` error —
+	 * used by the authoritative apply + final preview paths. `"drop"` silently
+	 * skips the edit — used by the streaming preview, where a half-written file
+	 * or transient parse error must not throw.
+	 */
+	onUnresolved?: "throw" | "drop";
+}
+
+/** True when at least one edit is an unresolved `replace block N:` edit. */
+export function hasBlockEdit(edits: readonly Edit[]): boolean {
+	return edits.some(edit => edit.kind === "block");
+}
+
+/**
+ * Resolve every `replace block N:` edit in `edits` against `text` (parsed as
+ * the language inferred from `path`). Non-block edits pass through untouched.
+ * Returns a fresh edit list with no `block` variants. The fast path returns the
+ * input unchanged when there is nothing to resolve.
+ *
+ * Synthesized inserts/deletes carry sequential `index` values for readability
+ * only — {@link applyEdits} re-derives every edit's index from array order, so
+ * the passthrough edits keeping their original indices is harmless.
+ */
+export function resolveBlockEdits(
+	edits: readonly Edit[],
+	text: string,
+	path: string,
+	resolver: BlockResolver | undefined,
+	options: ResolveBlockEditsOptions = {},
+): readonly Edit[] {
+	if (!hasBlockEdit(edits)) return edits;
+	const onUnresolved = options.onUnresolved ?? "throw";
+	const resolved: Edit[] = [];
+	let synthIndex = 0;
+	for (const edit of edits) {
+		if (edit.kind !== "block") {
+			resolved.push(edit);
+			continue;
+		}
+		const span = resolver ? resolver({ path, text, line: edit.anchor.line }) : null;
+		if (span === null) {
+			if (onUnresolved === "drop") continue;
+			throw new Error(
+				`line ${edit.lineNum}: ${resolver ? blockUnresolvedMessage(edit.anchor.line) : BLOCK_RESOLVER_UNAVAILABLE}`,
+			);
+		}
+		// Mirror the parser's `replace start..end:` expansion exactly: one
+		// `before_anchor` replacement insert per payload row at `span.start`,
+		// then one delete per line across `[span.start, span.end]`. An empty
+		// `payloads` (from `delete block N`) emits no inserts — a pure deletion.
+		for (const payload of edit.payloads) {
+			const cursor: Cursor = { kind: "before_anchor", anchor: { line: span.start } };
+			resolved.push({
+				kind: "insert",
+				cursor,
+				text: payload,
+				lineNum: edit.lineNum,
+				index: synthIndex++,
+				mode: "replacement",
+			});
+		}
+		for (let line = span.start; line <= span.end; line++) {
+			resolved.push({ kind: "delete", anchor: { line }, lineNum: edit.lineNum, index: synthIndex++ });
+		}
+	}
+	return resolved;
+}

package/src/format.ts

@@ -14,6 +14,8 @@ export const HL_PAYLOAD_REPLACE = "+";
 
 /** Hunk-header keyword for concrete line replacement. */
 export const HL_REPLACE_KEYWORD = "replace";
+/** Hunk-header sub-keyword: `replace block N:` resolves N to a tree-sitter block range. */
+export const HL_BLOCK_KEYWORD = "block";
 /** Hunk-header keyword for concrete line deletion. */
 export const HL_DELETE_KEYWORD = "delete";
 /** Hunk-header keyword for insertion operations. */

package/src/grammar.lark

@@ -3,15 +3,17 @@ begin_patch: "*** Begin Patch" LF
 end_patch:   "*** End Patch" LF?
 
 file_patch: file_header hunk+
-file_header: "¶" filename ("#" file_hash)? LF
+file_header: "¶" filename "#" file_hash LF
 file_hash: /[0-9A-F]{4}/
 filename: /[^\s#]+/
 
-hunk: body_hunk | delete_hunk
+hunk: body_hunk | delete_hunk | delete_block_hunk
 body_hunk:   body_header emit_op+
 delete_hunk: "delete " header_range LF
-body_header: (replace_anchor | insert_anchor) LF
+delete_block_hunk: "delete block " LID LF
+body_header: (replace_anchor | replace_block_anchor | insert_anchor) LF
 replace_anchor: "replace " header_range ":"
+replace_block_anchor: "replace block " LID ":"
 insert_anchor:  "insert " insert_pos ":"
 insert_pos: "before " LID | "after " LID | "head" | "tail"
 emit_op: "+" /(.*)/ LF

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./apply";
+export * from "./block";
 export * from "./diff-preview";
 export * from "./format";
 export * from "./fs";

package/src/input.ts

@@ -9,10 +9,11 @@
  */
 import * as path from "node:path";
 import { applyEdits } from "./apply";
+import { resolveBlockEdits } from "./block";
 import { HL_FILE_HASH_LENGTH, HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
 import { parsePatch, parsePatchStreaming } from "./parser";
 import { Tokenizer } from "./tokenizer";
-import type { ApplyResult, Edit, SplitOptions } from "./types";
+import type { ApplyResult, BlockResolver, Edit, SplitOptions } from "./types";
 
 // Pure classification — single shared tokenizer is safe.
 const TOKENIZER = new Tokenizer();
@@ -251,6 +252,8 @@ export class PatchSection {
 	get hasAnchorScopedEdit(): boolean {
 		return this.edits.some(edit => {
 			if (edit.kind === "delete") return true;
+			// A `replace block N:` edit is anchored to concrete content on line N.
+			if (edit.kind === "block") return true;
 			return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor";
 		});
 	}
@@ -263,6 +266,10 @@ export class PatchSection {
 				lines.add(edit.anchor.line);
 				continue;
 			}
+			if (edit.kind === "block") {
+				lines.add(edit.anchor.line);
+				continue;
+			}
 			if (edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor") {
 				lines.add(edit.cursor.anchor.line);
 			}
@@ -276,10 +283,14 @@ export class PatchSection {
 	 * {@link Patcher} owns tag validation and recovery; reach for this
 	 * method directly when you've already validated the file content and
 	 * just want the result.
+	 *
+	 * `blockResolver` resolves any `replace block N:` edits against `text`; an
+	 * unresolvable block throws (this is the final, authoritative preview path).
 	 */
-	applyTo(text: string): ApplyResult {
+	applyTo(text: string, blockResolver?: BlockResolver): ApplyResult {
 		const { edits, warnings } = this.parse();
-		const result = applyEdits(text, [...edits]);
+		const resolved = resolveBlockEdits(edits, text, this.path, blockResolver, { onUnresolved: "throw" });
+		const result = applyEdits(text, resolved);
 		// Preserve parse warnings so consumers don't need to call `parse()`
 		// separately.
 		const merged = warnings.length === 0 ? result.warnings : [...warnings, ...(result.warnings ?? [])];
@@ -294,10 +305,15 @@ export class PatchSection {
 	 * or a per-token parse error mid-stream) does not throw or emit a phantom
 	 * empty-payload edit. Intended for incremental diff previews; the writer
 	 * path should always use {@link applyTo}.
+	 *
+	 * `blockResolver` resolves any `replace block N:` edits against `text`; an
+	 * unresolvable block is silently dropped so a half-written file does not
+	 * throw mid-stream.
 	 */
-	applyPartialTo(text: string): ApplyResult {
+	applyPartialTo(text: string, blockResolver?: BlockResolver): ApplyResult {
 		const { edits, warnings } = parsePatchStreaming(this.diff);
-		const result = applyEdits(text, [...edits]);
+		const resolved = resolveBlockEdits(edits, text, this.path, blockResolver, { onUnresolved: "drop" });
+		const result = applyEdits(text, resolved);
 		const merged = warnings.length === 0 ? result.warnings : [...warnings, ...(result.warnings ?? [])];
 		return merged && merged.length > 0
 			? { ...result, warnings: merged }

package/src/messages.ts

@@ -5,6 +5,8 @@
  * them.
  */
 
+import { HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+
 /** Lines of context shown either side of a hash mismatch. */
 export const MISMATCH_CONTEXT = 2;
 
@@ -40,9 +42,48 @@ export const MINUS_ROW_REJECTED =
 /** Error text emitted when a replace hunk has no body. */
 export const EMPTY_REPLACE = "`replace N..M:` needs at least one `+TEXT` body row. To delete lines, use `delete N..M`.";
 
+/** Error text emitted when a `replace block N:` hunk has no body. */
+export const EMPTY_BLOCK =
+	"`replace block N:` needs at least one `+TEXT` body row. To delete a block, use `delete N..M` with the block's line range.";
+
+/**
+ * Error text emitted when a `replace block N:` anchor cannot be resolved to a
+ * syntactic block (unrecognized language, blank/out-of-range line, no node
+ * begins on line N such as a lone closing delimiter, or the resolved block has
+ * a syntax error). Names the offending line and steers back to an explicit
+ * `replace N..M:` range.
+ */
+export function blockUnresolvedMessage(line: number): string {
+	return (
+		`\`replace block ${line}:\` could not resolve a syntactic block beginning on line ${line}. ` +
+		`The language may be unsupported, the line may be blank or a closing delimiter, or the block may not parse. ` +
+		`Use \`replace ${line}..M:\` with the block's explicit end line instead.`
+	);
+}
+
+/**
+ * Error text emitted when a `replace block N:` edit reaches a code path that
+ * has no {@link BlockResolver} wired in. Indicates a host-configuration bug
+ * rather than authored-input error.
+ */
+export const BLOCK_RESOLVER_UNAVAILABLE =
+	"`replace block N:` is not available here (no tree-sitter block resolver is configured). Use `replace N..M:` with an explicit range.";
+
+/**
+ * Internal invariant error: `applyEdits` received an unresolved `replace block
+ * N:` edit. Block edits must be expanded by `resolveBlockEdits` before reaching
+ * the applier; hitting this is a wiring bug, not authored-input error.
+ */
+export const UNRESOLVED_BLOCK_INTERNAL =
+	"internal error: unresolved `replace block` edit reached the applier (resolveBlockEdits was not run).";
+
 /** Error text emitted when a delete hunk receives a body row. */
 export const DELETE_TAKES_NO_BODY = "`delete N..M` does not take body rows. Remove the body, or use `replace N..M:`.";
 
+/** Error text emitted when a `delete block N` hunk receives a body row. */
+export const DELETE_BLOCK_TAKES_NO_BODY =
+	"`delete block N` does not take body rows. Remove the body, or use `replace block N:` to replace the block.";
+
 /** Error text emitted when an insert hunk has no body. */
 export const EMPTY_INSERT = "`insert` needs at least one `+TEXT` body row.";
 
@@ -65,3 +106,23 @@ export const RECOVERY_SESSION_CHAIN_WARNING =
  */
 export const RECOVERY_SESSION_REPLAY_WARNING =
 	"Recovered by replaying your edits onto the current file content — your previous edit in this session changed line(s) you re-targeted with a stale hash. Verify the diff matches your intent before continuing.";
+
+/**
+ * Warning emitted when an `insert head:` / `insert tail:` edit is applied to an
+ * existing file whose snapshot tag is stale (the file drifted since the read).
+ * Head/tail insert position is content-independent — "start"/"end" cannot move
+ * with drift — so this is non-fatal: the edit applies onto the live content and
+ * we surface the drift instead of hard-failing (unlike an anchored mismatch).
+ */
+export const HEADTAIL_DRIFT_WARNING =
+	"Applied an `insert head:`/`insert tail:` edit onto the current file content even though the snapshot tag was stale (the file changed since your read). Head/tail position is content-independent, so the insert was not rejected — but re-read if the drift was unexpected.";
+
+/**
+ * Error text emitted when a hashline section omits the mandatory snapshot tag.
+ * The tag is REQUIRED on every section, enforced identically by the apply path
+ * ({@link Patcher.prepare}) and the preview/diff path, so both surfaces reuse
+ * this single builder to stay in lockstep.
+ */
+export function missingSnapshotTagMessage(sectionPath: string): string {
+	return `Missing hashline snapshot tag for edit to ${sectionPath}; use \`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}tag\` from your latest read/search output. To create a new file, use the write tool.`;
+}

package/src/parser.ts

@@ -6,7 +6,9 @@
 import { HL_PAYLOAD_REPLACE } from "./format";
 import {
 	BARE_BODY_AUTO_PIPED_WARNING,
+	DELETE_BLOCK_TAKES_NO_BODY,
 	DELETE_TAKES_NO_BODY,
+	EMPTY_BLOCK,
 	EMPTY_INSERT,
 	EMPTY_REPLACE,
 	MINUS_ROW_REJECTED,
@@ -159,7 +161,8 @@ export class Executor {
 	endStreaming(): { edits: Edit[]; warnings: string[] } {
 		this.#consumePendingSkippableComments();
 		if (this.#pending && this.#pending.payloads.length > 0) this.#flushPending();
-		else if (this.#pending?.target.kind === "delete") this.#flushPending();
+		else if (this.#pending?.target.kind === "delete" || this.#pending?.target.kind === "delete_block")
+			this.#flushPending();
 		else this.#pending = undefined;
 		this.#validateNoOverlappingDeletes();
 		return { edits: this.#edits, warnings: this.#warnings };
@@ -204,6 +207,7 @@ export class Executor {
 			);
 		}
 		if (pending.target.kind === "delete") throw new Error(`line ${lineNum}: ${DELETE_TAKES_NO_BODY}`);
+		if (pending.target.kind === "delete_block") throw new Error(`line ${lineNum}: ${DELETE_BLOCK_TAKES_NO_BODY}`);
 		pending.payloads.push({ kind: "literal", text, lineNum });
 	}
 
@@ -213,6 +217,8 @@ export class Executor {
 		if (this.#pending) {
 			if (text.trim().length === 0) return;
 			if (this.#pending.target.kind === "delete") throw new Error(`line ${lineNum}: ${DELETE_TAKES_NO_BODY}`);
+			if (this.#pending.target.kind === "delete_block")
+				throw new Error(`line ${lineNum}: ${DELETE_BLOCK_TAKES_NO_BODY}`);
 			if (text.trimStart().charCodeAt(0) === 45 /* - */) throw new Error(`line ${lineNum}: ${MINUS_ROW_REJECTED}`);
 			if (!this.#warnings.includes(BARE_BODY_AUTO_PIPED_WARNING)) this.#warnings.push(BARE_BODY_AUTO_PIPED_WARNING);
 			this.#pending.payloads.push({ kind: "literal", text, lineNum });
@@ -240,6 +246,16 @@ export class Executor {
 		this.#edits.push({ kind: "delete", anchor: { ...anchor }, lineNum, index: this.#editIndex++ });
 	}
 
+	#pushBlock(anchor: Anchor, payloads: readonly PayloadRow[], lineNum: number): void {
+		this.#edits.push({
+			kind: "block",
+			anchor: { ...anchor },
+			payloads: payloads.map(payload => payload.text),
+			lineNum,
+			index: this.#editIndex++,
+		});
+	}
+
 	#emitPayloadRows(cursor: Cursor, payloads: readonly PayloadRow[], lineNum: number, mode?: "replacement"): void {
 		for (const payload of payloads) this.#pushInsert(cursor, payload.text, lineNum, mode);
 	}
@@ -253,6 +269,16 @@ export class Executor {
 			for (const anchor of expandRange(target.range)) this.#pushDelete(anchor, lineNum);
 			return;
 		}
+		if (target.kind === "delete_block") {
+			// A block edit with no payloads resolves to a pure block deletion.
+			this.#pushBlock(target.anchor, [], lineNum);
+			return;
+		}
+		if (target.kind === "block") {
+			if (payloads.length === 0) throw new Error(`line ${lineNum}: ${EMPTY_BLOCK}`);
+			this.#pushBlock(target.anchor, payloads, lineNum);
+			return;
+		}
 		if (payloads.length === 0) {
 			if (target.kind === "replace") throw new Error(`line ${lineNum}: ${EMPTY_REPLACE}`);
 			throw new Error(`line ${lineNum}: ${EMPTY_INSERT}`);

package/src/patcher.ts

@@ -23,21 +23,29 @@
  * filesystem configuration.
  */
 import { applyEdits } from "./apply";
-import { computeFileHash, formatHashlineHeader, HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+import { hasBlockEdit, resolveBlockEdits } from "./block";
+import { computeFileHash, formatHashlineHeader } from "./format";
 import type { Filesystem, WriteResult } from "./fs";
 import { isNotFound } from "./fs";
 import type { Patch, PatchSection } from "./input";
+import { HEADTAIL_DRIFT_WARNING, missingSnapshotTagMessage } from "./messages";
 import { MismatchError } from "./mismatch";
 import { detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
 import { Recovery, type RecoveryResult } from "./recovery";
 import type { SnapshotStore } from "./snapshots";
-import type { ApplyResult, Edit } from "./types";
+import type { ApplyResult, BlockResolver, Edit } from "./types";
 
 export interface PatcherOptions {
 	/** Storage backend used for all reads and writes. */
 	fs: Filesystem;
 	/** Snapshot store that minted and resolves hashline section tags. Required. */
 	snapshots: SnapshotStore;
+	/**
+	 * Resolves `replace block N:` anchors to concrete line spans via tree-sitter.
+	 * Optional: when omitted, any `replace block N:` edit throws on apply (the
+	 * host did not wire a resolver). Plain line-range ops never need it.
+	 */
+	blockResolver?: BlockResolver;
 }
 
 /** Per-section result returned by {@link Patcher.apply} / {@link Patcher.commit}. */
@@ -98,15 +106,15 @@ export class PreparedSection {
 function hasAnchorScopedEdit(edits: readonly Edit[]): boolean {
 	return edits.some(edit => {
 		if (edit.kind === "delete") return true;
+		// A `replace block N:` edit anchors to concrete content on line N.
+		if (edit.kind === "block") return true;
 		return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor";
 	});
 }
 
-function assertSectionHashAllowed(sectionPath: string, fileHash: string | undefined, edits: readonly Edit[]): void {
-	if (fileHash !== undefined || !hasAnchorScopedEdit(edits)) return;
-	throw new Error(
-		`Missing hashline snapshot tag for anchored edit to ${sectionPath}; use \`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}tag\` from your latest read/search output.`,
-	);
+function assertSectionHashPresent(sectionPath: string, fileHash: string | undefined): void {
+	if (fileHash !== undefined) return;
+	throw new Error(missingSnapshotTagMessage(sectionPath));
 }
 
 function recoveryToApplyResult(result: RecoveryResult): ApplyResult {
@@ -148,6 +156,7 @@ export class Patcher {
 	readonly fs: Filesystem;
 	readonly snapshots: SnapshotStore;
 	readonly recovery: Recovery;
+	readonly blockResolver: BlockResolver | undefined;
 
 	constructor(options: PatcherOptions) {
 		if (!options.snapshots) {
@@ -156,6 +165,7 @@ export class Patcher {
 		this.fs = options.fs;
 		this.snapshots = options.snapshots;
 		this.recovery = new Recovery(options.snapshots);
+		this.blockResolver = options.blockResolver;
 	}
 
 	/**
@@ -213,13 +223,13 @@ export class Patcher {
 	 */
 	async prepare(section: PatchSection): Promise<PreparedSection> {
 		const { edits, warnings: parseWarnings } = section.parse();
-		assertSectionHashAllowed(section.path, section.fileHash, edits);
+		assertSectionHashPresent(section.path, section.fileHash);
 
 		const canonicalPath = this.fs.canonicalPath(section.path);
 		await this.fs.preflightWrite(section.path);
 		const { exists, rawContent } = await this.#tryRead(section.path);
-		if (!exists && hasAnchorScopedEdit(edits)) {
-			throw new Error(`File not found: ${section.path}`);
+		if (!exists) {
+			throw new Error(`File not found: ${section.path}. Use the write tool to create new files.`);
 		}
 
 		const { bom, text } = stripBom(rawContent);
@@ -307,6 +317,24 @@ export class Patcher {
 	#recordFullSnapshot(canonicalPath: string, normalized: string): string {
 		return this.snapshots.record(canonicalPath, normalized);
 	}
+	#mismatchError(
+		section: PatchSection,
+		canonicalPath: string,
+		normalized: string,
+		expected: string,
+		hashRecognized: boolean,
+	): MismatchError {
+		const actualFileHash = this.#recordFullSnapshot(canonicalPath, normalized);
+		return new MismatchError({
+			path: section.path,
+			expectedFileHash: expected,
+			actualFileHash,
+			fileLines: normalized.split("\n"),
+			anchorLines: section.collectAnchorLines(),
+			hashRecognized,
+		});
+	}
+
 	#applyWithRecovery(args: {
 		section: PatchSection;
 		canonicalPath: string;
@@ -316,28 +344,49 @@ export class Patcher {
 	}): ApplyResult {
 		const { section, canonicalPath, exists, normalized, edits } = args;
 		const expected = exists ? section.fileHash : undefined;
-		if (expected === undefined) return applyEdits(normalized, [...edits]);
+		const liveMatches = expected !== undefined && computeFileHash(normalized) === expected;
+
+		// Resolve `replace block N:` edits to concrete ranges before recovery
+		// runs. Block anchors are expressed against the snapshot the section tag
+		// names, so resolve against that exact text:
+		//   - live content matches the tag (or there is no tag) → resolve against
+		//     the live, normalized content;
+		//   - the file drifted → resolve against the tagged snapshot's text so the
+		//     resulting ranges flow through the 3-way-merge recovery below.
+		// When a block edit needs the tagged snapshot but it is unavailable, the
+		// range cannot be placed safely — reject with a MismatchError (re-read).
+		let resolved: readonly Edit[] = edits;
+		if (hasBlockEdit(edits)) {
+			const baseText =
+				expected === undefined || liveMatches ? normalized : this.snapshots.byHash(canonicalPath, expected)?.text;
+			if (baseText === undefined) {
+				throw this.#mismatchError(section, canonicalPath, normalized, expected ?? "", false);
+			}
+			resolved = resolveBlockEdits(edits, baseText, section.path, this.blockResolver, { onUnresolved: "throw" });
+		}
+
+		if (expected === undefined) return applyEdits(normalized, resolved);
 		// Whole-file unchanged → the tag still names the live content, so an
 		// edit anchored at ANY line (displayed or not) is safe to apply.
-		if (computeFileHash(normalized) === expected) return applyEdits(normalized, [...edits]);
+		if (liveMatches) return applyEdits(normalized, resolved);
+		// Head/tail-only inserts are position-stable: "start"/"end" cannot move
+		// with content drift, so a stale tag is non-fatal. Apply onto the live
+		// content and warn instead of hard-failing — unlike an anchored
+		// mismatch, which cannot be safely relocated and must reject.
+		if (!hasAnchorScopedEdit(resolved)) {
+			const result = applyEdits(normalized, resolved);
+			return { ...result, warnings: [HEADTAIL_DRIFT_WARNING, ...(result.warnings ?? [])] };
+		}
 		// File drifted: try to replay the edit against the version the tag
 		// names and 3-way-merge it onto the live content.
 		const recovered = this.recovery.tryRecover({
 			path: canonicalPath,
 			currentText: normalized,
 			fileHash: expected,
-			edits,
+			edits: resolved,
 		});
 		if (recovered) return recoveryToApplyResult(recovered);
 		const hashRecognized = this.snapshots.byHash(canonicalPath, expected) !== null;
-		const actualFileHash = this.#recordFullSnapshot(canonicalPath, normalized);
-		throw new MismatchError({
-			path: section.path,
-			expectedFileHash: expected,
-			actualFileHash,
-			fileLines: normalized.split("\n"),
-			anchorLines: section.collectAnchorLines(),
-			hashRecognized,
-		});
+		throw this.#mismatchError(section, canonicalPath, normalized, expected, hashRecognized);
 	}
 }

package/src/prompt.md

@@ -1,12 +1,14 @@
 Your patch language names lines to replace, delete, or insert at, then lists the new content. Rule of thumb: a header ending in `:` is followed by `+` body rows; `delete` has no body.
 
 <headers>
-Every file section starts with `¶PATH#TAG`. `TAG` is the 3-char snapshot tag from your latest `read`/`search`. REQUIRED for any hunk that names line numbers. Hashless `¶PATH` is allowed only for new-file creation or a patch that is purely `insert head:` / `insert tail:`.
+Every file section starts with `¶PATH#TAG`. `TAG` is the 4-hex snapshot tag from your latest `read`/`search`, and is REQUIRED on every section — there is no hashless form. To create a new file, use the `write` tool; hashline only edits files that already exist.
 </headers>
 
 <ops>
 replace N..M:      replace original lines N..M with the body rows below.
+replace block N:   replace the whole syntactic block that BEGINS on line N — its header line through its closing line — resolved with tree-sitter. Body rows below. Point N at the line that OPENS the construct (the `if`/`function`/`def`/`{`-bearing line), not a closing `}` or a blank line.
 delete N..M        delete original lines N..M. No body.
+delete block N     delete the whole syntactic block that BEGINS on line N.
 insert before N:   insert the body rows immediately before line N.
 insert after N:    insert the body rows immediately after line N.
 insert head:       insert the body rows at the very start of the file.
@@ -23,14 +25,18 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 <rules>
 - Line numbers come from `read`/`search` (`LINE:TEXT`). Copy the `¶PATH#TAG` header; use the bare LINE numbers.
 - Numbers refer to the ORIGINAL file and stay valid for the whole patch — they do not shift as hunks apply.
+- Across calls they do NOT survive: each applied edit mints a fresh `#TAG` and renumbers the file, so the tag and line numbers you just used are dead. Anchor the next edit on the `¶PATH#TAG` and lines from the edit response (or re-`read`), never on pre-edit numbers.
+- A line number is an offset, not a structural boundary: never `insert after N` into a construct you have not read, and never start or end a `replace`/`delete` range mid-expression or mid-block. If unsure what is on those lines, `read` them first.
+- On a stale-tag rejection — or any result you cannot fully account for — STOP and re-`read`. Never stack more line-numbered edits onto output you have not re-grounded; that compounds corruption.
 - One hunk per range; the body is the final content, never an old/new pair.
+- Keep every range as tight as the change: a range must cover ONLY lines whose content actually changes. Never widen it to swallow an unchanged signature, brace, or neighboring statement just to rewrite a few lines inside — change one line with `replace N..N`, not the whole block around it. (A range where every line genuinely changes is correctly long; tightness is about excluding unchanged lines, not about being short.) This bounds the blast radius if a number is off: a stale single-line replace corrupts one line, while a stale block replace shreds the whole block and its structure.
 - To change lines 2 and 5 while keeping 3–4, issue two hunks (`replace 2..2:` and `replace 5..5:`). Untouched lines are simply absent from every range.
 </rules>
 
 <example>
 Original (the exact shape `read` returns):
 ```
-¶greet.py#A1
+¶greet.py#A1B2
 1:def greet(name):
 2:    msg = "Hello, " + name
 3:    print(msg)
@@ -39,14 +45,14 @@ Original (the exact shape `read` returns):
 
 Insert a guard after line 1:
 ```
-¶greet.py#A1
+¶greet.py#A1B2
 insert after 1:
 +    if not name: name = "stranger"
 ```
 
 Replace line 2 with two lines:
 ```
-¶greet.py#A1
+¶greet.py#A1B2
 replace 2..2:
 +    greeting = "Hi"
 +    msg = f"{greeting}, {name}"
@@ -54,18 +60,26 @@ replace 2..2:
 
 Delete line 3:
 ```
-¶greet.py#A1
+¶greet.py#A1B2
 delete 3
 ```
 
 Add a header and trailer:
 ```
-¶greet.py#A1
+¶greet.py#A1B2
 insert head:
 +# generated header
 insert tail:
 +greet("everyone")
 ```
+
+Replace the whole `greet` function block — `replace block 1:` resolves lines 1–3 (the `def` header through `print(msg)`); line 4 is a separate statement and stays:
+```
+¶greet.py#A1B2
+replace block 1:
++def greet(name):
++    print(f"Hello, {name}")
+```
 </example>
 
 <anti-patterns>
@@ -85,3 +99,10 @@ replace 3..3:
 replace 3..3:
 +   return msg
 </anti-patterns>
+
+<critical>
+If you remember nothing else:
+1. RE-GROUND AFTER EVERY EDIT. Each applied edit mints a fresh `#TAG` and renumbers the file — the tag and line numbers you just used are now dead. Take the next edit's numbers from the edit response or a fresh `read`, never from pre-edit memory. On a stale-tag rejection or any unexpected result, STOP and re-`read`.
+2. RANGES ARE TIGHT AND IN-BOUNDS. Cover only lines whose content actually changes; never widen a range to swallow an unchanged signature, brace, or statement, and never start or end a range mid-expression or mid-block. A stale single-line replace corrupts one line; a stale block replace shreds the whole block.
+3. THE BODY IS THE FINAL CONTENT. Only `+TEXT` rows under a `:` header — never `-old`/bare context lines, never an old/new pair. The range does the deleting.
+</critical>

package/src/recovery.ts

@@ -70,6 +70,9 @@ function collectAnchorLines(edits: readonly Edit[]): number[] {
 
 function getEditAnchors(edit: Edit): Anchor[] {
 	if (edit.kind === "delete") return [edit.anchor];
+	// Recovery only ever receives already-resolved edits (no `block`); this arm
+	// exists for type-exhaustiveness over the full `Edit` union.
+	if (edit.kind === "block") return [edit.anchor];
 	return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor" ? [edit.cursor.anchor] : [];
 }
 

package/src/tokenizer.ts

@@ -10,6 +10,7 @@
  */
 import {
 	describeAnchorExamples,
+	HL_BLOCK_KEYWORD,
 	HL_DELETE_KEYWORD,
 	HL_FILE_HASH_LENGTH,
 	HL_FILE_HASH_SEP,
@@ -196,7 +197,9 @@ function scanHeaderRange(line: string, index = 0, end = trimEndIndex(line), allo
 
 export type BlockTarget =
 	| { kind: "replace"; range: ParsedRange }
+	| { kind: "block"; anchor: Anchor }
 	| { kind: "delete"; range: ParsedRange }
+	| { kind: "delete_block"; anchor: Anchor }
 	| { kind: "insert_before"; anchor: Anchor }
 	| { kind: "insert_after"; anchor: Anchor }
 	| { kind: "bof" }
@@ -249,6 +252,18 @@ function scanHunkAnchor(line: string, start: number, end: number): TargetScan |
 	const cursor = skipWhitespace(line, start, end);
 	const replaceEnd = scanKeyword(line, cursor, end, HL_REPLACE_KEYWORD);
 	if (replaceEnd !== null) {
+		// `replace block N:` — resolve N to a tree-sitter block range at apply
+		// time. Try the `block` sub-keyword before falling back to a literal
+		// `replace N..M:` range.
+		const blockEnd = scanKeyword(line, skipWhitespace(line, replaceEnd, end), end, HL_BLOCK_KEYWORD);
+		if (blockEnd !== null) {
+			const anchor = scanLineNumber(line, skipWhitespace(line, blockEnd, end), end);
+			if (anchor === null) return null;
+			return {
+				target: { kind: "block", anchor: { line: anchor.line } },
+				nextIndex: consumeOptionalColon(line, anchor.nextIndex, end),
+			};
+		}
 		const range = scanHeaderRange(line, replaceEnd, end, true);
 		if (range === null) return null;
 		return {
@@ -258,6 +273,17 @@ function scanHunkAnchor(line: string, start: number, end: number): TargetScan |
 	}
 	const deleteEnd = scanKeyword(line, cursor, end, HL_DELETE_KEYWORD);
 	if (deleteEnd !== null) {
+		// `delete block N` — resolve N to a tree-sitter block range at apply
+		// time and delete its whole span. Like `delete N..M`, it takes no body
+		// and no trailing colon.
+		const blockEnd = scanKeyword(line, skipWhitespace(line, deleteEnd, end), end, HL_BLOCK_KEYWORD);
+		if (blockEnd !== null) {
+			const anchor = scanLineNumber(line, skipWhitespace(line, blockEnd, end), end);
+			if (anchor === null) return null;
+			const next = skipWhitespace(line, anchor.nextIndex, end);
+			if (next < end && line.charCodeAt(next) === CHAR_COLON) return null;
+			return { target: { kind: "delete_block", anchor: { line: anchor.line } }, nextIndex: next };
+		}
 		const range = scanHeaderRange(line, deleteEnd, end, true);
 		if (range === null) return null;
 		const next = skipWhitespace(line, range.nextIndex, end);

package/src/types.ts

@@ -32,7 +32,24 @@ export type Edit =
 			index: number;
 			mode?: "replacement";
 	  }
-	| { kind: "delete"; anchor: Anchor; lineNum: number; index: number; oldAssertion?: string };
+	| { kind: "delete"; anchor: Anchor; lineNum: number; index: number; oldAssertion?: string }
+	| {
+			/**
+			 * Deferred block edit (`replace block N:` / `delete block N`). The exact
+			 * line span is unknown at parse time — it is computed by
+			 * {@link resolveBlockEdits} once file text + path (→ language) are
+			 * available, then expanded into concrete edits: a non-empty `payloads`
+			 * (from `replace block`) becomes the same `replacement` inserts + deletes
+			 * that `replace start..end:` produces; an empty `payloads` (from `delete
+			 * block`) becomes a pure range deletion. `applyEdits` never sees this
+			 * variant.
+			 */
+			kind: "block";
+			anchor: Anchor;
+			payloads: string[];
+			lineNum: number;
+			index: number;
+	  };
 
 /** Result of applying a parsed set of edits to a text body. */
 export interface ApplyResult {
@@ -84,3 +101,32 @@ export interface CompactDiffOptions {
 	/** Maximum entries kept on each side of an unchanged-context truncation (default 2). */
 	maxUnchangedRun?: number;
 }
+
+/**
+ * Resolved 1-indexed inclusive line span of a `replace block N:` target.
+ */
+export interface BlockSpan {
+	/** First line of the block (1-indexed, inclusive). */
+	start: number;
+	/** Last line of the block (1-indexed, inclusive). */
+	end: number;
+}
+
+/** Request handed to a {@link BlockResolver} to resolve one `replace block N:` anchor. */
+export interface BlockResolverRequest {
+	/** Target file path (used to infer language by extension). */
+	path: string;
+	/** Full text the block must be resolved against (the snapshot the tag names). */
+	text: string;
+	/** 1-indexed line the block must begin on. */
+	line: number;
+}
+
+/**
+ * Resolves a `replace block N:` anchor to the line span of the syntactic block
+ * that begins on line N. Returns `null` when no block can be resolved
+ * (unrecognized language, blank/out-of-range line, no node begins there, or the
+ * resolved subtree has a syntax error). Pure seam: the hashline core declares
+ * the contract; the host injects a tree-sitter-backed implementation.
+ */
+export type BlockResolver = (request: BlockResolverRequest) => BlockSpan | null;