@oh-my-pi/hashline 17.2.0 → 17.2.2

package/src/tokenizer.ts

@@ -10,26 +10,16 @@
  */
 import {
 	describeAnchorExamples,
-	HL_CUT_BLOCK_KEYWORD,
 	HL_CUT_KEYWORD,
 	HL_FILE_HASH_LENGTH,
 	HL_FILE_HASH_SEP,
 	HL_FILE_PREFIX,
 	HL_FILE_SUFFIX,
 	HL_HEADER_COLON,
-	HL_INSERT_AFTER,
-	HL_INSERT_AFTER_BLOCK_KEYWORD,
-	HL_INSERT_BEFORE,
-	HL_INSERT_HEAD,
-	HL_INSERT_KEYWORD,
-	HL_INSERT_TAIL,
 	HL_MOVE_KEYWORD,
-	HL_PASTE_AFTER_BLOCK_KEYWORD,
-	HL_PASTE_KEYWORD,
 	HL_PAYLOAD_REPLACE,
+	HL_PUT_KEYWORD,
 	HL_REM_KEYWORD,
-	HL_REPLACE_BLOCK_KEYWORD,
-	HL_REPLACE_KEYWORD,
 } from "./format";
 import { ABORT_MARKER, BEGIN_PATCH_MARKER, END_PATCH_MARKER } from "./messages";
 import type { Anchor, Cursor, ParsedRange } from "./types";
@@ -41,11 +31,16 @@ const CHAR_NINE = 57;
 const CHAR_HASH = 35;
 const CHAR_TAB = 9;
 const CHAR_SPACE = 32;
-const CHAR_DOT = 46;
-const CHAR_COMMA = 44;
 const CHAR_HYPHEN = 45;
-const CHAR_ELLIPSIS = 0x2026;
+const CHAR_DOT = 46;
 const CHAR_EQUALS = 61;
+const CHAR_ELLIPSIS = 0x2026;
+const CHAR_LESS_THAN = 60;
+const CHAR_GREATER_THAN = 62;
+const CHAR_STAR = 42;
+const CHAR_DOLLAR = 36;
+const CHAR_AT = 64;
+const CHAR_UNDERSCORE = 95;
 
 const CHAR_UPPER_A = 65;
 const CHAR_UPPER_F = 70;
@@ -157,40 +152,33 @@ export function parseLid(raw: string, lineNum: number): Anchor {
 interface RangeScan {
 	range: ParsedRange;
 	nextIndex: number;
+	hadSeparator: boolean;
 }
 
+/**
+ * Range separator scanner. Canonical input is `.=`, while parsing remains
+ * deliberately lenient for model output: `-`, `=`, `.`, `..`, `…`, mixed
+ * runs, and whitespace-only separators all recover to the same range.
+ */
 function scanRangeSeparator(line: string, index: number, end: number): number | null {
 	let cursor = index;
 	let consumedSeparator = false;
 	while (cursor < end) {
 		const code = line.charCodeAt(cursor);
-		if (isWhitespaceCode(code)) {
-			cursor++;
-			consumedSeparator = true;
-			continue;
-		}
-		if (code === CHAR_COMMA || code === CHAR_HYPHEN || code === CHAR_ELLIPSIS) {
+		if (
+			isWhitespaceCode(code) ||
+			code === CHAR_HYPHEN ||
+			code === CHAR_DOT ||
+			code === CHAR_EQUALS ||
+			code === CHAR_ELLIPSIS
+		) {
 			cursor++;
 			consumedSeparator = true;
 			continue;
 		}
-		if (code === CHAR_DOT && cursor + 1 < end) {
-			const next = line.charCodeAt(cursor + 1);
-			if (next === CHAR_DOT || next === CHAR_EQUALS) {
-				cursor += 2;
-				consumedSeparator = true;
-				continue;
-			}
-			if (isNonZeroDigitCode(next)) {
-				cursor++;
-				consumedSeparator = true;
-				continue;
-			}
-		}
 		break;
 	}
-	if (!consumedSeparator) return null;
-	if (cursor >= end || !isNonZeroDigitCode(line.charCodeAt(cursor))) return null;
+	if (!consumedSeparator || cursor >= end || !isNonZeroDigitCode(line.charCodeAt(cursor))) return null;
 	return cursor;
 }
 
@@ -204,6 +192,7 @@ function scanHeaderRange(line: string, index = 0, end = trimEndIndex(line), allo
 		return {
 			range: { start: { line: start.line }, end: { line: start.line } },
 			nextIndex: skipWhitespace(line, start.nextIndex, end),
+			hadSeparator: false,
 		};
 	}
 	const endNumber = scanLineNumber(line, afterFirst, end);
@@ -211,27 +200,35 @@ function scanHeaderRange(line: string, index = 0, end = trimEndIndex(line), allo
 	return {
 		range: { start: { line: start.line }, end: { line: endNumber.line } },
 		nextIndex: skipWhitespace(line, endNumber.nextIndex, end),
+		hadSeparator: true,
 	};
 }
 
 export type BlockTarget =
-	| { kind: "replace"; range: ParsedRange }
-	| { kind: "block"; anchor: Anchor }
-	| { kind: "insert_before"; anchor: Anchor }
-	| { kind: "insert_after"; anchor: Anchor }
-	| { kind: "insert_after_block"; anchor: Anchor }
-	| { kind: "cut"; range: ParsedRange }
-	| { kind: "cut_block"; anchor: Anchor }
-	| { kind: "paste"; cursor: Cursor }
-	| { kind: "paste_after_block"; anchor: Anchor }
+	| { kind: "replace"; range: ParsedRange; register?: string }
+	| { kind: "block"; anchor: Anchor; register?: string }
+	| { kind: "insert_before"; anchor: Anchor; register?: string }
+	| { kind: "insert_after"; anchor: Anchor; register?: string }
+	| { kind: "insert_after_block"; anchor: Anchor; register?: string }
+	| { kind: "cut"; range: ParsedRange; register?: string }
+	| { kind: "cut_block"; anchor: Anchor; register?: string }
+	| { kind: "bof"; register?: string }
+	| { kind: "eof"; register?: string }
 	| { kind: "rem" }
-	| { kind: "move"; dest: string }
-	| { kind: "bof" }
-	| { kind: "eof" };
+	| { kind: "move"; dest: string };
+
+/** Targets that may carry a `@register` suffix (everything but the file-level ops). */
+type RegisterableTarget = Exclude<BlockTarget, { kind: "rem" } | { kind: "move" }>;
 
 interface TargetScan {
 	target: BlockTarget;
 	nextIndex: number;
+	/**
+	 * Whether the header carried a trailing `:`. The parser uses it to tell a
+	 * literal insertion awaiting body rows (`PUT >40:`) from a bodyless
+	 * anonymous paste (`PUT >40`).
+	 */
+	hadColon: boolean;
 }
 
 function scanKeyword(line: string, index: number, end: number, keyword: string): number | null {
@@ -239,85 +236,128 @@ function scanKeyword(line: string, index: number, end: number, keyword: string):
 	const next = index + keyword.length;
 	if (next < end) {
 		const code = line.charCodeAt(next);
-		if (!isWhitespaceCode(code) && code !== CHAR_COLON && code !== CHAR_DOT) return null;
+		if (!isWhitespaceCode(code) && code !== CHAR_COLON) return null;
 	}
 	return next;
 }
 
-/**
- * GLM 5.2 inserts a stray `.` between the line number/range and the trailing
- * `:` (e.g. `SWAP 2.=3.:`, `INS.POST 2.:`). A `.` is never valid syntax at
- * this position, so skip it when it precedes an optional `:` or end-of-line.
- */
-function skipStrayDot(line: string, index: number, end: number): number {
-	if (index < end && line.charCodeAt(index) === CHAR_DOT) {
-		const after = skipWhitespace(line, index + 1, end);
-		if (after === end || line.charCodeAt(after) === CHAR_COLON) return after;
+interface ColonScan {
+	nextIndex: number;
+	hadColon: boolean;
+}
+
+function consumeOptionalColon(line: string, index: number, end: number): ColonScan {
+	const cursor = skipWhitespace(line, index, end);
+	if (cursor < end && line.charCodeAt(cursor) === CHAR_COLON) {
+		return { nextIndex: skipWhitespace(line, cursor + 1, end), hadColon: true };
 	}
-	return index;
+	return { nextIndex: cursor, hadColon: false };
 }
 
-function consumeOptionalColon(line: string, index: number, end: number): number {
-	let cursor = skipWhitespace(line, index, end);
-	cursor = skipStrayDot(line, cursor, end);
-	return cursor < end && line.charCodeAt(cursor) === CHAR_COLON ? skipWhitespace(line, cursor + 1, end) : cursor;
+/** Maximum accepted register-name length; anything longer fails the header parse. */
+const REGISTER_NAME_MAX = 64;
+
+function isRegisterNameCode(code: number): boolean {
+	return (
+		isDigitCode(code) ||
+		(code >= CHAR_UPPER_A && code <= 90) ||
+		(code >= CHAR_LOWER_A && code <= 122) ||
+		code === CHAR_UNDERSCORE ||
+		code === CHAR_HYPHEN
+	);
 }
-/**
- * Recover local-model replace trailers that permute `:` and `=` as `:=:` or
- * `=:`. The range has already been parsed, so these suffixes are unambiguous.
- */
-function consumeReplaceColon(line: string, index: number, end: number): number {
-	const canonical = consumeOptionalColon(line, index, end);
-	if (canonical >= end || line.charCodeAt(canonical) !== CHAR_EQUALS) return canonical;
-	const afterEquals = skipWhitespace(line, canonical + 1, end);
-	if (afterEquals >= end || line.charCodeAt(afterEquals) !== CHAR_COLON) return canonical;
-	return skipWhitespace(line, afterEquals + 1, end);
+
+/** Scan a `@name` register reference. */
+function scanRegister(line: string, index: number, end: number): { name: string; nextIndex: number } | null {
+	if (index >= end || line.charCodeAt(index) !== CHAR_AT) return null;
+	const start = index + 1;
+	let cursor = start;
+	while (cursor < end && isRegisterNameCode(line.charCodeAt(cursor))) cursor++;
+	if (cursor === start || cursor - start > REGISTER_NAME_MAX) return null;
+	return { name: line.slice(start, cursor), nextIndex: cursor };
 }
 
-interface PositionScan {
-	cursor: Cursor;
-	nextIndex: number;
+/**
+ * Finish a `PUT`/`CUT` header: optional `@register`, optional trailing `:`.
+ * The parser decides whether a body is required; the tokenizer only records
+ * the shape.
+ */
+function finishTargetScan(line: string, index: number, end: number, target: RegisterableTarget): TargetScan {
+	let cursor = skipWhitespace(line, index, end);
+	const register = scanRegister(line, cursor, end);
+	if (register !== null) {
+		target = { ...target, register: register.name };
+		cursor = register.nextIndex;
+	}
+	const colon = consumeOptionalColon(line, cursor, end);
+	return { target, nextIndex: colon.nextIndex, hadColon: colon.hadColon };
 }
 
-/** Scan the `.PRE N` / `.POST N` / `.HEAD` / `.TAIL` positional suffix shared by `INS` and `PASTE`. */
-function scanPositionalSuffix(line: string, index: number, end: number): PositionScan | null {
-	if (index >= end || line.charCodeAt(index) !== CHAR_DOT) return null;
-	const probe = skipWhitespace(line, index + 1, end);
-	const beforeEnd = scanKeyword(line, probe, end, HL_INSERT_BEFORE);
-	if (beforeEnd !== null) {
-		const anchor = scanLineNumber(line, skipWhitespace(line, beforeEnd, end), end);
+/**
+ * Scan the locator of a `PUT` header:
+ *   span — `5` / `5-9` (replace lines), `5*` (replace the block opening at 5)
+ *   gap  — `<5` / `>5` (insert), `>5*` (after the block's end), `<1` (head), `>$` (tail)
+ */
+function scanPutTarget(line: string, index: number, end: number): TargetScan | null {
+	const cursor = skipWhitespace(line, index, end);
+	if (cursor >= end) return null;
+	const sigil = line.charCodeAt(cursor);
+	if (sigil === CHAR_LESS_THAN || sigil === CHAR_GREATER_THAN) {
+		const isAfter = sigil === CHAR_GREATER_THAN;
+		const probe = skipWhitespace(line, cursor + 1, end);
+		if (isAfter && probe < end && line.charCodeAt(probe) === CHAR_DOLLAR) {
+			return finishTargetScan(line, probe + 1, end, { kind: "eof" });
+		}
+		const anchor = scanLineNumber(line, probe, end);
 		if (anchor === null) return null;
-		const nextIndex = consumeOptionalColon(line, anchor.nextIndex, end);
-		return { cursor: { kind: "before_anchor", anchor: { line: anchor.line } }, nextIndex };
+		let next = anchor.nextIndex;
+		let block = false;
+		if (next < end && line.charCodeAt(next) === CHAR_STAR) {
+			block = true;
+			next++;
+		}
+		if (isAfter) {
+			return finishTargetScan(
+				line,
+				next,
+				end,
+				block
+					? { kind: "insert_after_block", anchor: { line: anchor.line } }
+					: { kind: "insert_after", anchor: { line: anchor.line } },
+			);
+		}
+		// `<N*` is the same gap as `<N`: a block anchored at N begins on line N,
+		// so "before the block" is "before line N". The star is dropped.
+		// `<1` is head — mapped to `bof` so it stays position-stable (never
+		// anchor-scoped) and works when creating empty files.
+		return finishTargetScan(
+			line,
+			next,
+			end,
+			anchor.line === 1 ? { kind: "bof" } : { kind: "insert_before", anchor: { line: anchor.line } },
+		);
 	}
-	const afterEnd = scanKeyword(line, probe, end, HL_INSERT_AFTER);
-	if (afterEnd !== null) {
-		const anchor = scanLineNumber(line, skipWhitespace(line, afterEnd, end), end);
-		if (anchor === null) return null;
-		const nextIndex = consumeOptionalColon(line, anchor.nextIndex, end);
-		return { cursor: { kind: "after_anchor", anchor: { line: anchor.line } }, nextIndex };
+	const range = scanHeaderRange(line, cursor, end, true);
+	if (range === null) return null;
+	const next = range.nextIndex;
+	if (next < end && line.charCodeAt(next) === CHAR_STAR) {
+		// Block locators are single opening lines (`N*`), never ranges.
+		if (range.hadSeparator) return null;
+		return finishTargetScan(line, next + 1, end, { kind: "block", anchor: { line: range.range.start.line } });
 	}
-	const headEnd = scanKeyword(line, probe, end, HL_INSERT_HEAD);
-	if (headEnd !== null) return { cursor: { kind: "bof" }, nextIndex: consumeOptionalColon(line, headEnd, end) };
-	const tailEnd = scanKeyword(line, probe, end, HL_INSERT_TAIL);
-	if (tailEnd !== null) return { cursor: { kind: "eof" }, nextIndex: consumeOptionalColon(line, tailEnd, end) };
-	return null;
+	return finishTargetScan(line, next, end, { kind: "replace", range: range.range });
 }
 
-function scanInsertTarget(line: string, index: number, end: number): TargetScan | null {
-	const scan = scanPositionalSuffix(line, index, end);
-	if (scan === null) return null;
-	const { cursor, nextIndex } = scan;
-	switch (cursor.kind) {
-		case "before_anchor":
-			return { target: { kind: "insert_before", anchor: cursor.anchor }, nextIndex };
-		case "after_anchor":
-			return { target: { kind: "insert_after", anchor: cursor.anchor }, nextIndex };
-		case "bof":
-			return { target: { kind: "bof" }, nextIndex };
-		case "eof":
-			return { target: { kind: "eof" }, nextIndex };
+/** Scan the locator of a `CUT` header: `N.=M` or `N*` (block). */
+function scanCutTarget(line: string, index: number, end: number): TargetScan | null {
+	const range = scanHeaderRange(line, index, end, true);
+	if (range === null) return null;
+	const next = range.nextIndex;
+	if (next < end && line.charCodeAt(next) === CHAR_STAR) {
+		if (range.hadSeparator) return null;
+		return finishTargetScan(line, next + 1, end, { kind: "cut_block", anchor: { line: range.range.start.line } });
 	}
+	return finishTargetScan(line, next, end, { kind: "cut", range: range.range });
 }
 
 function unquotePath(pathText: string): string {
@@ -359,93 +399,24 @@ function scanHunkAnchor(line: string, start: number, end: number): TargetScan |
 	if (remEnd !== null) {
 		const next = skipWhitespace(line, remEnd, end);
 		if (next !== end) return null;
-		return { target: { kind: "rem" }, nextIndex: next };
+		return { target: { kind: "rem" }, nextIndex: next, hadColon: false };
 	}
 	const moveEnd = scanKeyword(line, cursor, end, HL_MOVE_KEYWORD);
 	if (moveEnd !== null) {
 		const dest = scanMoveDest(line, moveEnd, end);
 		if (dest === null || dest.length === 0) return null;
-		return { target: { kind: "move", dest }, nextIndex: end };
-	}
-
-	// `replace_block N:` — resolve N to a tree-sitter block range at apply time.
-	const replaceBlockEnd = scanKeyword(line, cursor, end, HL_REPLACE_BLOCK_KEYWORD);
-	if (replaceBlockEnd !== null) {
-		const anchor = scanLineNumber(line, skipWhitespace(line, replaceBlockEnd, end), end);
-		if (anchor === null) return null;
-		return {
-			target: { kind: "block", anchor: { line: anchor.line } },
-			nextIndex: consumeOptionalColon(line, anchor.nextIndex, end),
-		};
-	}
-	const replaceEnd = scanKeyword(line, cursor, end, HL_REPLACE_KEYWORD);
-	if (replaceEnd !== null) {
-		const range = scanHeaderRange(line, replaceEnd, end, true);
-		if (range === null) return null;
-		return {
-			target: { kind: "replace", range: range.range },
-			nextIndex: consumeReplaceColon(line, range.nextIndex, end),
-		};
+		return { target: { kind: "move", dest }, nextIndex: end, hadColon: false };
 	}
-	// `insert_after_block N:` — insert after the last line of the tree-sitter
-	// block at N.
-	const insertAfterBlockEnd = scanKeyword(line, cursor, end, HL_INSERT_AFTER_BLOCK_KEYWORD);
-	if (insertAfterBlockEnd !== null) {
-		const anchor = scanLineNumber(line, skipWhitespace(line, insertAfterBlockEnd, end), end);
-		if (anchor === null) return null;
-		return {
-			target: { kind: "insert_after_block", anchor: { line: anchor.line } },
-			nextIndex: consumeOptionalColon(line, anchor.nextIndex, end),
-		};
-	}
-	// `PASTE.BLK.POST N` — insert the clipboard after the tree-sitter block
-	// at N. Like all clipboard ops, takes no body rows.
-	const pasteAfterBlockEnd = scanKeyword(line, cursor, end, HL_PASTE_AFTER_BLOCK_KEYWORD);
-	if (pasteAfterBlockEnd !== null) {
-		const anchor = scanLineNumber(line, skipWhitespace(line, pasteAfterBlockEnd, end), end);
-		if (anchor === null) return null;
-		return {
-			target: { kind: "paste_after_block", anchor: { line: anchor.line } },
-			nextIndex: consumeOptionalColon(line, anchor.nextIndex, end),
-		};
-	}
-	// `PASTE.PRE|POST N` / `PASTE.HEAD|TAIL` — insert the clipboard at the position.
-	const pasteEnd = scanKeyword(line, cursor, end, HL_PASTE_KEYWORD);
-	if (pasteEnd !== null) {
-		const scan = scanPositionalSuffix(line, pasteEnd, end);
-		if (scan === null) return null;
-		return { target: { kind: "paste", cursor: scan.cursor }, nextIndex: scan.nextIndex };
-	}
-	// `CUT.BLK N` captures and deletes the tree-sitter block beginning at N.
-	// Scan it before the plain form so `.BLK` is not parsed as a range.
-	const cutBlockEnd = scanKeyword(line, cursor, end, HL_CUT_BLOCK_KEYWORD);
-	if (cutBlockEnd !== null) {
-		const anchor = scanLineNumber(line, skipWhitespace(line, cutBlockEnd, end), end);
-		if (anchor === null) return null;
-		return {
-			target: { kind: "cut_block", anchor: { line: anchor.line } },
-			nextIndex: consumeOptionalColon(line, anchor.nextIndex, end),
-		};
-	}
-	// `CUT N.=M` captures and deletes concrete lines. A trailing colon is
-	// tolerated and ignored; body rows are rejected by the parser.
+	const putEnd = scanKeyword(line, cursor, end, HL_PUT_KEYWORD);
+	if (putEnd !== null) return scanPutTarget(line, putEnd, end);
 	const cutEnd = scanKeyword(line, cursor, end, HL_CUT_KEYWORD);
-	if (cutEnd !== null) {
-		const range = scanHeaderRange(line, cutEnd, end, true);
-		if (range === null) return null;
-		const next = skipStrayDot(line, range.nextIndex, end);
-		return {
-			target: { kind: "cut", range: range.range },
-			nextIndex: consumeOptionalColon(line, next, end),
-		};
-	}
-	const insertEnd = scanKeyword(line, cursor, end, HL_INSERT_KEYWORD);
-	if (insertEnd !== null) return scanInsertTarget(line, insertEnd, end);
+	if (cutEnd !== null) return scanCutTarget(line, cutEnd, end);
 	return null;
 }
 
 interface ParsedHunkHeader {
 	target: BlockTarget;
+	hadColon: boolean;
 }
 
 function tryParseHunkHeader(line: string): ParsedHunkHeader | null {
@@ -455,7 +426,7 @@ function tryParseHunkHeader(line: string): ParsedHunkHeader | null {
 	const scan = scanHunkAnchor(line, start, end);
 	if (scan === null) return null;
 	if (scan.nextIndex !== end) return null;
-	return { target: scan.target };
+	return { target: scan.target, hadColon: scan.hadColon };
 }
 
 function tryParseHeader(line: string): { path: string; fileHash?: string } | null {
@@ -512,7 +483,7 @@ export type Token =
 	| (TokenBase & { kind: "envelope-end" })
 	| (TokenBase & { kind: "abort" })
 	| (TokenBase & { kind: "header"; path: string; fileHash?: string })
-	| (TokenBase & { kind: "op-block"; target: BlockTarget })
+	| (TokenBase & { kind: "op-block"; target: BlockTarget; hadColon: boolean })
 	| (TokenBase & { kind: "payload-literal"; text: string })
 	| (TokenBase & { kind: "raw"; text: string });
 
@@ -532,15 +503,13 @@ function classifyLine(line: string, lineNum: number): Token {
 	}
 	const lead = skipWhitespace(line, 0);
 	const isHunkLead =
-		line.startsWith(HL_REPLACE_KEYWORD, lead) ||
-		line.startsWith(HL_INSERT_KEYWORD, lead) ||
-		line.startsWith(HL_REM_KEYWORD, lead) ||
-		line.startsWith(HL_MOVE_KEYWORD, lead) ||
+		line.startsWith(HL_PUT_KEYWORD, lead) ||
 		line.startsWith(HL_CUT_KEYWORD, lead) ||
-		line.startsWith(HL_PASTE_KEYWORD, lead);
+		line.startsWith(HL_REM_KEYWORD, lead) ||
+		line.startsWith(HL_MOVE_KEYWORD, lead);
 	if (isHunkLead) {
 		const hunk = tryParseHunkHeader(line);
-		if (hunk !== null) return { kind: "op-block", lineNum, target: hunk.target };
+		if (hunk !== null) return { kind: "op-block", lineNum, target: hunk.target, hadColon: hunk.hadColon };
 	}
 	if (firstCode === CHAR_PAYLOAD_REPLACE) return { kind: "payload-literal", lineNum, text: line.slice(1) };
 	return { kind: "raw", lineNum, text: line };

package/src/types.ts

@@ -42,50 +42,61 @@ export type Edit =
 	| { kind: "delete"; anchor: Anchor; lineNum: number; index: number; oldAssertion?: string }
 	| {
 			/**
-			 * Clipboard cut (`CUT N.=M`, or the resolved form of `CUT.BLK N`).
-			 * Captures the range's current lines into the {@link Clipboard}
+			 * Clipboard cut (`CUT N-M @r`, or the resolved form of `CUT N* @r`).
+			 * Captures the range's current lines into a {@link Clipboard}
 			 * register during the applier's clipboard pre-pass and lowers to one
-			 * `delete` per range line at parse/resolve time.
+			 * `delete` per range line at parse/resolve time. `register` names the
+			 * target slot; absent means the batch-local anonymous register.
 			 */
 			kind: "cut";
 			range: ParsedRange;
+			register?: string;
 			lineNum: number;
 			index: number;
 	  }
 	| {
 			/**
-			 * Clipboard insertion (`PASTE.PRE N` / `PASTE.POST N` / `PASTE.HEAD` /
-			 * `PASTE.TAIL`, or the resolved form of `PASTE.BLK.POST N`). Expanded
-			 * by the clipboard pre-pass into one plain insert per captured line.
-			 * `blockStart` mirrors the insert variant's field for block-lowered
-			 * pastes so landing correction can slide the body across trailing
-			 * closer lines.
+			 * Clipboard insertion or replacement (`PUT <N @r` / `PUT >N @r` /
+			 * `PUT N-M @r`, their `>N*` block-resolved forms, or the register-less
+			 * anonymous equivalents). Expanded by the clipboard pre-pass into one
+			 * plain insert per captured line; `span` targets additionally expand
+			 * into per-line deletes there — only after the register read
+			 * succeeds, so a dropped paste (streaming preview with an empty
+			 * register) never leaves destructive orphan deletes. `blockStart`
+			 * mirrors the insert variant's field for block-lowered gap pastes so
+			 * landing correction can slide the body across trailing closer lines.
 			 */
 			kind: "paste";
-			cursor: Cursor;
+			at: PasteTarget;
+			register?: string;
 			lineNum: number;
 			index: number;
 			blockStart?: number;
 	  }
 	| {
 			/**
-			 * Deferred block edit (`SWAP.BLK N:`, `INS.BLK.POST N:`,
-			 * `CUT.BLK N`, or `PASTE.BLK.POST N`). The exact line span is
-			 * unknown at parse time; {@link resolveBlockEdits} computes it once
-			 * file text and language are available, then expands it into
-			 * concrete edits. `mode: "insert_after"` becomes plain
-			 * `after_anchor` inserts, `"cut"` becomes a clipboard cut plus
-			 * per-line deletes, and `"paste_after"` becomes a paste after the
-			 * resolved block. No mode denotes a block replacement.
+			 * Deferred block edit (`PUT N*:`, `PUT >N*:`, `CUT N*`, or their
+			 * `@register` forms). The exact line span is unknown at parse time;
+			 * {@link resolveBlockEdits} computes it once file text and language
+			 * are available, then expands it into concrete edits.
+			 * `mode: "insert_after"` becomes plain `after_anchor` inserts,
+			 * `"cut"` becomes a clipboard cut plus per-line deletes, and
+			 * `"paste_after"` becomes a gap paste after the resolved block. No
+			 * mode denotes a block replacement — from body payloads, or from
+			 * `register` when one is named (a span paste over the resolved block).
 			 */
 			kind: "block";
 			anchor: Anchor;
 			payloads: string[];
 			mode?: "insert_after" | "cut" | "paste_after";
+			register?: string;
 			lineNum: number;
 			index: number;
 	  };
 
+/** Where a `paste` edit lands: an insertion gap, or a span it replaces. */
+export type PasteTarget = { kind: "gap"; cursor: Cursor } | { kind: "span"; range: ParsedRange };
+
 /** File-level operation parsed from a section body (`REM` / `MV`). */
 export type FileOp = { kind: "rem" } | { kind: "move"; dest: string };
 
@@ -105,7 +116,7 @@ export interface ApplyResult {
 	blockResolutions?: BlockResolution[];
 }
 
-/** A parsed `[A.=B]` line range. */
+/** A parsed `A-B` inclusive line range. */
 export interface ParsedRange {
 	start: Anchor;
 	end: Anchor;
@@ -190,13 +201,25 @@ export interface BlockResolverRequest {
 export type BlockResolver = (request: BlockResolverRequest) => BlockSpan | null;
 
 /**
- * Mutable clipboard register threaded through one patch application. Filled
- * by `CUT` edits and read by `PASTE` edits in patch source order, across
- * sections, so content can move between files. Create one per batch (`{}`)
- * and hand it to every {@link Patcher.prepare} / `applyTo` call in that batch;
- * callers that omit it get a private per-call register.
+ * Mutable clipboard registers threaded through one patch application. Filled
+ * by `CUT` edits and read by register `PUT`s in patch source order, across
+ * sections, so content can move between files.
+ *
+ * The anonymous register (`lines`) is batch-local: {@link forkClipboard}
+ * never copies it in, so it exists only between a `CUT` and a paste inside
+ * one patch. Named registers (`named`) persist across batches when the host
+ * owns the Clipboard (`PatcherOptions.clipboard`) — the sanctioned way to
+ * move content across separate edit calls.
  */
 export interface Clipboard {
-	/** Lines captured by the most recent `CUT`, or unset. */
+	/** Anonymous register: lines captured by the latest unlabeled `CUT` in this batch. */
 	lines?: readonly string[];
+	/** Named registers captured by `CUT … @name`. */
+	named?: Map<string, readonly string[]>;
+	/**
+	 * Headers of unlabeled `CUT`s seen since the last unlabeled paste in this
+	 * batch. Two or more make the next unlabeled paste ambiguous (which cut
+	 * did the author mean?) and fail it with a labeling hint.
+	 */
+	pendingAnonCuts?: string[];
 }