@oh-my-pi/hashline 17.2.0 → 17.2.2

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [17.2.2] - 2026-07-31
+
+### Breaking Changes
+
+- Replaced legacy SWAP, INS, and PASTE syntax with unified PUT and CUT hunks
+
+### Added
+
+- Added named register support (@reg) and span paste capabilities to clipboard operations
+- Added conservative recovery for uniformly omitted replacement indents near brace openers, preserving intentional indentation-only edits
+
+### Changed
+
+- Made .= the canonical inclusive range separator while retaining legacy separator variants as lenient input
+- Unified replacement, insertion, register paste, block, head/tail, move, and removal headers under a composable PUT, CUT, MV, and REM grammar
+
+### Fixed
+
+- Improved resilience against common model output formatting errors, including numbered read rows, summarized ranges, diff-style old/new rows, empty PUT deletes, harmless CUT colons, and single-line span shorthand
+
 ## [17.2.0] - 2026-07-30
 
 ### Breaking Changes

package/README.md

@@ -26,7 +26,7 @@ await fs.writeText("hello.ts", before);
 const tag = snapshots.record("hello.ts", before);
 const patcher = new Patcher({ fs, snapshots });
 const patch = Patch.parse(String.raw`[hello.ts#${tag}]
-SWAP 1.=1:
+PUT 1.=1:
 +const greeting = "hello";`);
 const result = await patcher.apply(patch);
 
@@ -47,12 +47,12 @@ still matches the recorded content hash, and refusing or attempting
 session-aware recovery on mismatch.
 
 Inside a section:
-- `SWAP A.=B:` — replace lines A.=B with following `+TEXT` body rows.
-- `SWAP.BLK A:` — replace the syntactic block beginning on line A.
-- `CUT A.=B` / `CUT.BLK A` — delete concrete lines or a resolved block and capture them for `PASTE`.
-- `INS.PRE A:` / `INS.POST A:` / `INS.HEAD:` / `INS.TAIL:` — insert following body rows.
-- `INS.BLK.POST A:` — insert following body rows after the resolved block's last line.
-- `PASTE.PRE A` / `PASTE.POST A` / `PASTE.HEAD` / `PASTE.TAIL` / `PASTE.BLK.POST A` — insert the clipboard; no body rows. The register flows top-to-bottom across sections (cross-file moves) and can be host-persisted across batches via `PatcherOptions.clipboard`.
+- `PUT A.=B:` — replace lines A through B (inclusive) with following `+TEXT` body rows.
+- `PUT A*:` — replace the syntactic block beginning on line A.
+- `PUT <A:` / `PUT >A:` — insert following body rows before/after line A (`<1` = head, `>$` = tail).
+- `PUT >A*:` — insert following body rows after the resolved block's last line.
+- `PUT <A` / `PUT >A` / `PUT A.=B @name` / `PUT A* @name` — paste a captured register at a gap, over a range, or over a resolved block (no `:` header or body rows; `@name` is optional only at gaps).
+- `CUT A.=B` / `CUT A*` — delete concrete lines or a resolved block and capture them (anonymous, or `@name` when given).
 - `REM` — delete the whole file named by the section header.
 - `MV DEST` — move/rename the section file to `DEST` (optionally after line edits).
 - `+TEXT` — literal body row (use `+` alone for a blank line).

package/dist/types/clipboard.d.ts

@@ -1,19 +1,21 @@
 import type { Clipboard, Edit } from "./types.js";
-/** True when at least one edit reads or writes the clipboard register. */
+/** True when at least one edit reads or writes a clipboard register. */
 export declare function hasClipboardEdit(edits: readonly Edit[]): boolean;
 /** Optional knobs for {@link resolveClipboardEdits}. */
 export interface ResolveClipboardEditsOptions {
-    /** `PASTE` with an empty register: `throw` (default) or `drop` (streaming previews). */
+    /** `PUT` with an empty register: `throw` (default) or `drop` (streaming previews). */
     onEmptyPaste?: "throw" | "drop";
 }
 /**
  * Resolve clipboard edits against the original file lines in authored order.
- * Cuts fill the register and emit nothing; pastes become plain inserts.
+ * Cuts fill the register and emit nothing; pastes expand to inserts (+ deletes for span targets).
  */
 export declare function resolveClipboardEdits(edits: readonly Edit[], fileLines: readonly string[], clipboard: Clipboard, options?: ResolveClipboardEditsOptions): readonly Edit[];
+/** Start a batch with persisted named registers but no anonymous state. */
+export declare function startClipboardBatch(source?: Clipboard): Clipboard;
 /** Create a transactional working copy of a clipboard register. */
 export declare function forkClipboard(source?: Clipboard): Clipboard;
-/** Publish a clipboard fork back to its source register. */
+/** Publish a clipboard fork back to its source register (only named registers persist across batches). */
 export declare function commitClipboard(fork: Clipboard, target: Clipboard): void;
 /**
  * Validate that every paste has a preceding or persisted capture without

package/dist/types/format.d.ts

@@ -9,38 +9,28 @@ export declare const HL_FILE_PREFIX = "[";
 export declare const HL_FILE_SUFFIX = "]";
 /** Payload sigil for literal body rows. */
 export declare const HL_PAYLOAD_REPLACE = "+";
-/** Hunk-header keyword for concrete line replacement. */
-export declare const HL_REPLACE_KEYWORD = "SWAP";
-/** Hunk-header keyword for insertion operations. */
-export declare const HL_INSERT_KEYWORD = "INS";
-/** Insert position keyword for inserting before a concrete line. */
-export declare const HL_INSERT_BEFORE = "PRE";
-/** Insert position keyword for inserting after a concrete line. */
-export declare const HL_INSERT_AFTER = "POST";
-/** Insert position keyword for inserting at the start of the file. */
-export declare const HL_INSERT_HEAD = "HEAD";
-/** Insert position keyword for inserting at the end of the file. */
-export declare const HL_INSERT_TAIL = "TAIL";
-/** Hunk-header keyword: `SWAP.BLK N:` resolves N to a tree-sitter block range and replaces its span. */
-export declare const HL_REPLACE_BLOCK_KEYWORD = "SWAP.BLK";
-/** Hunk-header keyword: `INS.BLK.POST N:` inserts after the last line of the tree-sitter block at N. */
-export declare const HL_INSERT_AFTER_BLOCK_KEYWORD = "INS.BLK.POST";
-/** Hunk-header keyword: `CUT N.=M` captures lines into the clipboard register and deletes them. */
+/** Hunk-header keyword: `PUT` writes content (body rows) or a register at a span or gap. */
+export declare const HL_PUT_KEYWORD = "PUT";
+/** Hunk-header keyword: `CUT N.=M` / `CUT N*` deletes lines and captures them (anonymous register, or `@name` when given). */
 export declare const HL_CUT_KEYWORD = "CUT";
-/** Hunk-header keyword: `CUT.BLK N` captures the tree-sitter block at N and deletes its span. */
-export declare const HL_CUT_BLOCK_KEYWORD = "CUT.BLK";
-/** Hunk-header keyword prefix: `PASTE.PRE|POST N` / `PASTE.HEAD|TAIL` inserts the clipboard. */
-export declare const HL_PASTE_KEYWORD = "PASTE";
-/** Hunk-header keyword: `PASTE.BLK.POST N` inserts the clipboard after the tree-sitter block at N. */
-export declare const HL_PASTE_AFTER_BLOCK_KEYWORD = "PASTE.BLK.POST";
 /** File-level keyword: `REM` deletes the whole file named by the section header. */
 export declare const HL_REM_KEYWORD = "REM";
 /** File-level keyword: `MV DEST` renames/moves the section file to `DEST`. */
 export declare const HL_MOVE_KEYWORD = "MV";
 export declare const HL_HEADER_COLON = ":";
+/** Gap sigil: `<N` targets the gap before line N (`<1` = head). */
+export declare const HL_GAP_BEFORE = "<";
+/** Gap sigil: `>N` targets the gap after line N (`>$` = tail). */
+export declare const HL_GAP_AFTER = ">";
+/** Locator suffix: `N*` extends the anchor to the syntactic block opening at N. */
+export declare const HL_BLOCK_SUFFIX = "*";
+/** Gap anchor: `$` names the last line, so `>$` is end-of-file. */
+export declare const HL_EOF_ANCHOR = "$";
+/** Register sigil: `@name` selects a named clipboard register on `PUT`/`CUT`. */
+export declare const HL_REGISTER_SIGIL = "@";
 /** Separator between a hashline file path and its opaque snapshot tag. */
 export declare const HL_FILE_HASH_SEP = "#";
-/** Separator between two line numbers in a range, e.g. `5.=10`. */
+/** Canonical separator between inclusive range endpoints, e.g. `5.=10`. */
 export declare const HL_RANGE_SEP = ".=";
 /** Separator between a line number and displayed line content in hashline mode. */
 export declare const HL_LINE_BODY_SEP = ":";
@@ -48,12 +38,16 @@ export declare const HL_LINE_BODY_SEP = ":";
 export declare const HL_LINE_RE_RAW = "[1-9]\\d*";
 /** Capture-group form of {@link HL_LINE_RE_RAW}. */
 export declare const HL_LINE_CAPTURE_RE_RAW = "([1-9]\\d*)";
-/** Format a concrete replacement hunk header. */
+/** Format a concrete replacement hunk header (`PUT 5.=9:`). */
 export declare function formatReplaceHeader(start: number, end: number): string;
-/** Format a concrete cut hunk header. */
+/** Format a concrete cut hunk header (`CUT 5.=9`). */
 export declare function formatCutHeader(start: number, end?: number): string;
-/** Format an insertion hunk header for a cursor position. */
+/** Format a gap locator for a cursor position (`<5`, `>5`, `<1`, `>$`). */
+export declare function formatGapLocator(cursor: Cursor): string;
+/** Format an insertion hunk header for a cursor position (`PUT <5:`, `PUT >$:`). */
 export declare function formatInsertHeader(cursor: Cursor): string;
+/** Format a register reference (`@name`). */
+export declare function formatRegister(name: string): string;
 /** Number of hex characters in a content-derived file-hash tag. */
 export declare const HL_FILE_HASH_LENGTH = 4;
 /** Canonical uppercase hexadecimal content-hash tag carried by a hashline section header. */

package/dist/types/messages.d.ts

@@ -11,7 +11,7 @@ export declare function formatAnchoredContext(anchorLines: readonly number[], fi
 /** Concrete range operation rejected because its absolute end precedes its start. */
 export type AbsoluteRangeOp = "replace" | "cut";
 /** Explain absolute range endpoints and provide safe, non-applying retry forms. */
-export declare function invalidAbsoluteRangeMessage(patchLine: number, start: number, end: number, op: AbsoluteRangeOp, block?: BlockSpan): string;
+export declare function invalidAbsoluteRangeMessage(patchLine: number, start: number, end: number, op: AbsoluteRangeOp, block?: BlockSpan, register?: string): string;
 /** Optional patch envelope start marker; silently consumed. */
 export declare const BEGIN_PATCH_MARKER = "*** Begin Patch";
 /** Optional patch envelope end marker; terminates parsing. */
@@ -21,22 +21,33 @@ export declare const END_PATCH_MARKER = "*** End Patch";
  * {@link END_PATCH_MARKER}, without a warning.
  */
 export declare const ABORT_MARKER = "*** Abort";
-/** Two consecutive hunks targeted the exact same concrete range. */
-export declare const REPLACE_PAIR_COALESCED_WARNING = "Two hunks targeted the same range; kept only the second. One `SWAP N.=M:` hunk per range \u2014 the body is the final content, never old+new.";
+/** Exact-range duplicate hunks were normalized to the final hunk. */
+export declare const REPLACE_PAIR_COALESCED_WARNING = "Multiple hunks targeted the same exact range; kept only the last. Issue one `PUT` or `CUT` hunk per range.";
+/** Replacement body indentation was aligned from unchanged structural rows. */
+export declare const REPLACEMENT_INDENT_AUTO_SHIFT_WARNING = "Auto-indented a replacement body to match unchanged structural rows in its source range.";
 /** Bare body rows auto-converted to literal `+` rows. */
 export declare const BARE_BODY_AUTO_PIPED_WARNING = "Auto-prefixed bare body row(s) with `+`. Body rows must be `+TEXT` literal lines.";
+/** Top-level read-output rows recovered as single-line replacements. */
+export declare const SNAPSHOT_ROWS_AUTO_PUT_WARNING = "Recovered top-level `N:TEXT` snapshot row(s) as single-line `PUT N.=N:` replacements. Use explicit `PUT` headers for reliable edits.";
+/** Bare range header recovered as an implicit replacement hunk. */
+export declare const BARE_RANGE_AUTO_PUT_WARNING = "Recovered a bare `N.=M:` header as `PUT N.=M:`. Prefix replacement ranges with `PUT`.";
+/** Copied read-output elision rows were ignored rather than written as source. */
+export declare const READ_METADATA_IGNORED_WARNING = "Ignored copied read-output elision row(s). Re-read elided ranges before editing them.";
+/** Empty span/block PUT recovered as a delete-only edit. */
+export declare const EMPTY_PUT_AUTO_CUT_WARNING = "Interpreted an empty `PUT` body as deletion. Use `CUT N.=M` or `CUT N*` for bodyless deletes.";
+/** A bodyless CUT carried a harmless trailing colon. */
+export declare const CUT_COLON_IGNORED_WARNING = "Ignored a trailing `:` on bodyless `CUT`. Prefer `CUT N.=M` / `CUT N*` without a colon.";
 /**
  * Bare `-` body rows accepted as literal Markdown bullets. Only emitted when
  * the hunk is unambiguously a bullet list: every `-` row is bullet-shaped
+
  * (`- item`) and the body has no unified-diff `+new` counterpart rows.
  */
 export declare const MINUS_BULLET_AUTO_PIPED_WARNING = "Auto-prefixed bare `- ` bullet row(s) as literal content. `-` rows never remove lines \u2014 the range does that; always prefix literal body rows with `+`: `+- item`.";
+/** Unified-diff old rows were discarded; explicit `+` rows are final content. */
+export declare const DIFF_OLD_ROWS_IGNORED_WARNING = "Ignored unified-diff `-old` row(s); the range already removes old content, so only `+new` rows were kept.";
 /** Unified-diff-style `-` row in a hunk body. */
 export declare const MINUS_ROW_REJECTED = "`-` rows are not valid; the range already names the lines being changed. For Markdown bullets or other literal `-` lines, prefix the literal row with `+`: `+- item`.";
-/** Replace hunk with no body. */
-export declare const EMPTY_REPLACE = "`SWAP N.=M:` needs at least one `+TEXT` body row. To delete lines, use `CUT N.=M`.";
-/** `SWAP.BLK N:` hunk with no body. */
-export declare const EMPTY_BLOCK = "`SWAP.BLK N:` needs at least one `+TEXT` body row. To delete a block, use `CUT.BLK N`.";
 /** Optional source-aware suggestions appended to block-anchor diagnostics. */
 export interface BlockDiagnosticSuggestions {
     /** Closest following multi-line block that begins after the authored anchor. */
@@ -47,18 +58,18 @@ export interface BlockDiagnosticSuggestions {
 /**
  * A block-anchored replace/cut could not resolve to a syntactic block.
  * Appends a {@link formatAnchoredContext} preview when `fileLines` is given.
- * `INS.BLK.POST N:` never reaches this path; it lowers to `INS.POST N:`.
+ * `PUT >N*` never reaches this path; it lowers to `PUT >N`.
  */
-export declare function blockUnresolvedMessage(line: number, op?: AbsoluteRangeOp, fileLines?: readonly string[], suggestions?: BlockDiagnosticSuggestions): string;
+export declare function blockUnresolvedMessage(line: number, op?: AbsoluteRangeOp, fileLines?: readonly string[], suggestions?: BlockDiagnosticSuggestions, register?: string): string;
 /** Block-anchored edit reached a path with no {@link BlockResolver} wired in. */
-export declare const BLOCK_RESOLVER_UNAVAILABLE = "Block ops (`SWAP.BLK`, `INS.BLK.POST`, `CUT.BLK`, `PASTE.BLK.POST`) are not available here (no block resolver configured). Use a concrete line range.";
-/** `INS.BLK.POST N:` anchored on a closing-delimiter line; applied as `INS.POST N:`. */
+export declare const BLOCK_RESOLVER_UNAVAILABLE = "Block locators (`N*` in `PUT N*:`, `PUT >N*`, `CUT N*`) are not available here (no block resolver configured). Use a concrete line range.";
+/** `PUT >N*:` anchored on a closing-delimiter line; applied as `PUT >N:`. */
 export declare function insertAfterBlockCloserLoweredWarning(line: number): string;
-/** `INS.BLK.POST N:` anchor unresolvable; applied as `INS.POST N:`. */
+/** `PUT >N*:` anchor unresolvable; applied as `PUT >N:`. */
 export declare function insertAfterBlockUnresolvedLoweredWarning(line: number): string;
-/** `PASTE.BLK.POST N` anchored on a closing-delimiter line; applied as `PASTE.POST N`. */
+/** Register `PUT >N*` anchored on a closing-delimiter line; applied as `PUT >N`. */
 export declare function pasteAfterBlockCloserLoweredWarning(line: number): string;
-/** `PASTE.BLK.POST N` anchor unresolvable; applied as `PASTE.POST N`. */
+/** Register `PUT >N*` anchor unresolvable; applied as `PUT >N`. */
 export declare function pasteAfterBlockUnresolvedLoweredWarning(line: number): string;
 /**
  * A one-sided boundary echo whose payload is too short to be the widened
@@ -86,20 +97,30 @@ export declare const UNRESOLVED_BLOCK_INTERNAL = "internal error: unresolved blo
 export declare const REM_TAKES_NO_BODY = "`REM` deletes the whole file and takes no body rows or line ops. Issue it alone under the header.";
 /** `MV` received a body row. */
 export declare const MOVE_TAKES_NO_BODY = "`MV DEST` does not take body rows. Put line edits above the `MV` row; the destination path follows `MV` on the same line.";
-/** `CUT N.=M` hunk received a body row. */
-export declare const CUT_TAKES_NO_BODY = "`CUT N.=M` captures + deletes lines and takes no body rows. To replace lines with new content, use `SWAP N.=M:`.";
-/** `PASTE` hunk received a body row. */
-export declare const PASTE_TAKES_NO_BODY = "`PASTE` inserts the clipboard content and takes no `+` body rows. To insert literal text, use `INS`.";
-/** `PASTE` ran with an empty clipboard register. */
-export declare const EMPTY_PASTE = "`PASTE` found nothing in the clipboard. Ops run top-to-bottom across the whole patch (sections included): put `CUT N.=M` or `CUT.BLK N` above the `PASTE`.";
+/** `CUT` hunk received a body row. */
+export declare const CUT_TAKES_NO_BODY = "`CUT` deletes (and captures) the named lines and takes no body rows. To write new content, use `PUT N.=M:` with `+TEXT` rows.";
+/** Register `PUT` header carried a `:`. */
+export declare const COLON_ON_REGISTER_PUT = "`PUT \u2026 @name` pastes the register and never takes `:` \u2014 the colon promises body rows. Drop the colon (`PUT >40 @name`), or drop `@name` and write `+TEXT` body rows.";
+/** Register `PUT` hunk received a body row. */
+export declare const REGISTER_PUT_TAKES_NO_BODY = "A register `PUT` pastes captured lines and takes no `+` body rows. To write literal text, drop the `@name` and use `PUT \u2026:` with body rows.";
+/** Colonless `PUT` hunk received a body row. */
+export declare const COLONLESS_PUT_TAKES_NO_BODY = "`PUT` without `:` is clipboard-backed and takes no body rows. Add `:` after the locator to write literal content (`PUT >40:` then `+TEXT` rows).";
+/** Colonless anonymous `PUT` on a span target. */
+export declare const COLONLESS_SPAN_PUT = "Colonless `PUT` is clipboard-backed, and span targets need a named register (`PUT 5.=9 @name`); the anonymous register pastes only at gaps (`PUT >40`). To write literal content, add `:` and `+TEXT` body rows.";
+/** Anonymous paste ran with an empty anonymous register. */
+export declare const EMPTY_PASTE = "Nothing to paste: no unlabeled `CUT` precedes this `PUT` in this call, and the anonymous register never carries across calls. Put `CUT N.=M` / `CUT N*` above it, or use named registers (`CUT \u2026 @name` \u2192 `PUT \u2026 @name`) for cross-call moves.";
+/** Named paste read a register that holds nothing. */
+export declare function unknownRegisterMessage(name: string, known: readonly string[]): string;
+/** Unlabeled paste with two or more unlabeled cuts pending. */
+export declare function ambiguousAnonymousPasteMessage(pending: readonly string[]): string;
 /**
  * Clipboard ops inside a same-path section that was merged across another
  * file's section. Same-path sections coalesce into their first occurrence, so
  * an interleaved layout would silently reorder the register sequence.
  */
-export declare const CLIPBOARD_INTERLEAVED_SECTIONS = "`CUT`/`PASTE` cannot be used in a file whose sections are interleaved with another file's: same-path sections merge into the first occurrence, which would reorder the clipboard sequence. Keep each file's ops under ONE `[path#TAG]` header.";
-/** Insert hunk with no body. */
-export declare const EMPTY_INSERT = "`INS` needs at least one `+TEXT` body row.";
+export declare const CLIPBOARD_INTERLEAVED_SECTIONS = "`CUT`/register-`PUT` ops cannot be used in a file whose sections are interleaved with another file's: same-path sections merge into the first occurrence, which would reorder the register sequence. Keep each file's ops under ONE `[path#TAG]` header.";
+/** Gap `PUT` with `:` but no body. */
+export declare const EMPTY_INSERT = "`PUT <N:` / `PUT >N:` promises body rows and got none. Write `+TEXT` rows, or drop the `:` to paste a register (`PUT >N` = anonymous, `PUT >N @name` = named).";
 /**
  * `insert after` body indented shallower than the anchor: the landing slid
  * forward past trailing closer lines — the common "anchored on the last line
@@ -107,9 +128,9 @@ export declare const EMPTY_INSERT = "`INS` needs at least one `+TEXT` body row."
  */
 export declare function afterInsertLandingShiftWarning(anchorLine: number, landingLine: number, crossed: number): string;
 /**
- * `insert_after_block N:` body indented deeper than the block's closer: the
- * landing was pulled inside the block — a deeper body almost always means
- * "append inside the block's body".
+ * `PUT >N*:` body indented deeper than the block's closer: the landing was
+ * pulled inside the block — a deeper body almost always means "append inside
+ * the block's body".
  */
 export declare function blockInsertLandingShiftWarning(blockStart: number, closerLine: number, landingLine: number): string;
 /** `Recovery`: an external write matched a cached snapshot. */
@@ -123,7 +144,7 @@ export declare const RECOVERY_LINE_REMAP_WARNING = "Recovered by remapping stale
  * Head/tail position is content-independent, so drift is non-fatal: apply
  * onto live content and warn instead of hard-failing.
  */
-export declare const HEADTAIL_DRIFT_WARNING = "Applied the `INS.HEAD:`/`INS.TAIL:` edit despite a stale snapshot tag (file changed since your read) \u2014 head/tail position is content-independent. Re-read if the drift was unexpected.";
+export declare const HEADTAIL_DRIFT_WARNING = "Applied the `PUT <1:`/`PUT >$:` edit despite a stale snapshot tag (file changed since your read) \u2014 head/tail position is content-independent. Re-read if the drift was unexpected.";
 /**
  * The `Filesystem` reported that what actually landed on disk differs from
  * what was written (see `WriteResult.text`) — most commonly an ACP-connected

package/dist/types/parser.d.ts

@@ -11,7 +11,8 @@ export declare class InvalidAbsoluteRangeError extends Error {
     readonly endLine: number;
     /** Operation whose range was invalid. */
     readonly op: AbsoluteRangeOp;
-    constructor(patchLine: number, startLine: number, endLine: number, op: AbsoluteRangeOp, block?: BlockSpan);
+    readonly register?: string;
+    constructor(patchLine: number, startLine: number, endLine: number, op: AbsoluteRangeOp, block?: BlockSpan, register?: string);
     /** Rebuild this error with a proven syntactic-block endpoint suggestion. */
     withBlock(block: BlockSpan): InvalidAbsoluteRangeError;
 }

package/dist/types/prefixes.d.ts

@@ -13,6 +13,8 @@
  * common case for echoed file content, and erroneously echoed prefixes will
  * otherwise turn every content line into a (malformed) op.
  */
+/** Whether a row is display-only metadata emitted by `read`, never source. */
+export declare function isReadMetadataLine(line: string): boolean;
 /**
  * Single-pass variant of {@link stripLeadingHashlinePrefixes} that strips at
  * most one leading hashline prefix (`N:`, `>>>N:`, `+N:` etc.) and does NOT

package/dist/types/tokenizer.d.ts

@@ -6,39 +6,42 @@ export declare function parseLid(raw: string, lineNum: number): Anchor;
 export type BlockTarget = {
     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: "paste";
-    cursor: Cursor;
+    kind: "bof";
+    register?: string;
 } | {
-    kind: "paste_after_block";
-    anchor: Anchor;
+    kind: "eof";
+    register?: string;
 } | {
     kind: "rem";
 } | {
     kind: "move";
     dest: string;
-} | {
-    kind: "bof";
-} | {
-    kind: "eof";
 };
 interface TokenBase {
     lineNum: number;
@@ -58,6 +61,7 @@ export type Token = (TokenBase & {
 }) | (TokenBase & {
     kind: "op-block";
     target: BlockTarget;
+    hadColon: boolean;
 }) | (TokenBase & {
     kind: "payload-literal";
     text: string;

package/dist/types/types.d.ts

@@ -48,47 +48,63 @@ export type Edit = {
     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";
@@ -111,7 +127,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;
@@ -187,13 +203,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[];
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "17.2.0",
+	"version": "17.2.2",
 	"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",
@@ -33,7 +33,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "17.2.0",
+		"@oh-my-pi/pi-natives": "17.2.2",
 		"lru-cache": "11.5.2"
 	},
 	"devDependencies": {

package/src/apply.ts

@@ -14,6 +14,7 @@ import {
 	ambiguousBoundaryEchoMessage,
 	ambiguousCloserSpareMessage,
 	blockInsertLandingShiftWarning,
+	REPLACEMENT_INDENT_AUTO_SHIFT_WARNING,
 	UNRESOLVED_BLOCK_INTERNAL,
 } from "./messages";
 import { cloneCursor } from "./tokenizer";
@@ -390,6 +391,66 @@ function findReplacementGroup(edits: readonly AppliedEdit[], start: number): Rep
 	};
 }
 
+/**
+ * Restore a uniformly omitted base indent only when the payload would escape
+ * a surviving `{` opener immediately above the replacement. Matching unchanged
+ * rows then prove the uniform shift; ordinary indentation-only edits stay exact.
+ */
+function repairReplacementIndentation(edits: AppliedEdit[], fileLines: readonly string[]): string[] {
+	let repaired = false;
+	for (let start = 0; start < edits.length; ) {
+		const group = findReplacementGroup(edits, start);
+		if (group === undefined) {
+			start++;
+			continue;
+		}
+		const lastDeleteIndex = group.deleteIndices.at(-1);
+		if (lastDeleteIndex === undefined) continue;
+		start = lastDeleteIndex + 1;
+		if (group.payload.length !== group.deleteIndices.length) continue;
+		const preceding = fileLines[group.startLine - 2] ?? "";
+		const sourceFirst = fileLines[group.startLine - 1] ?? "";
+		const payloadFirst = group.payload[0] ?? "";
+		if (
+			!preceding.trimEnd().endsWith("{") ||
+			!isIndentDeeper(leadingIndent(sourceFirst), leadingIndent(preceding)) ||
+			isIndentDeeper(leadingIndent(payloadFirst), leadingIndent(preceding))
+		) {
+			continue;
+		}
+
+		let shift: string | undefined;
+		let matches = 0;
+		let consistent = true;
+		for (let offset = 0; offset < group.payload.length; offset++) {
+			const source = fileLines[group.startLine - 1 + offset] ?? "";
+			const payload = group.payload[offset];
+			if (source.trim().length === 0 || source.trimStart() !== payload.trimStart()) continue;
+			const sourceIndent = leadingIndent(source);
+			const payloadIndent = leadingIndent(payload);
+			if (!sourceIndent.endsWith(payloadIndent)) {
+				consistent = false;
+				break;
+			}
+			const candidate = sourceIndent.slice(0, sourceIndent.length - payloadIndent.length);
+			if (shift === undefined) shift = candidate;
+			else if (shift !== candidate) {
+				consistent = false;
+				break;
+			}
+			matches++;
+		}
+		if (!consistent || !shift || matches < 2 || matches * 2 <= group.payload.length) continue;
+		for (const index of group.insertIndices) {
+			const edit = edits[index];
+			if (edit.kind !== "insert" || edit.text.trim().length === 0) continue;
+			edits[index] = { ...edit, text: `${shift}${edit.text}` };
+		}
+		repaired = true;
+	}
+	return repaired ? [REPLACEMENT_INDENT_AUTO_SHIFT_WARNING] : [];
+}
+
 /**
  * Largest `k` such that the payload's last `k` lines exactly equal the `k`
  * surviving file lines just below the range AND dropping them zeroes `delta`.
@@ -927,6 +988,15 @@ function repairReplacementBoundaries(
 		after: new Map(),
 	};
 	for (const edit of projected) {
+		if (edit.kind === "insert" && edit.cursor.kind === "bof") {
+			const inserted = insertedByLine.get(1);
+			if (inserted) inserted.push(edit.text);
+			else insertedByLine.set(1, [edit.text]);
+			const before = insertedLineMaps.before.get(1);
+			if (before) before.push(edit.text);
+			else insertedLineMaps.before.set(1, [edit.text]);
+			continue;
+		}
 		if (edit.kind !== "insert") continue;
 		for (const anchor of getCursorAnchors(edit.cursor)) {
 			const lines = insertedByLine.get(anchor.line);
@@ -1272,9 +1342,10 @@ export function applyEdits(text: string, edits: readonly Edit[], options: ApplyE
 		fileLines,
 	);
 	validateLineBounds(targetEdits, fileLines);
+	const indentationWarnings = repairReplacementIndentation(targetEdits, fileLines);
 	const { edits: repaired, warnings: boundaryWarnings } = repairReplacementBoundaries(targetEdits, fileLines);
 	const { edits: landed, warnings: landingWarnings } = repairAfterInsertLandings(repaired, fileLines);
-	const warnings = [...boundaryWarnings, ...landingWarnings];
+	const warnings = [...indentationWarnings, ...boundaryWarnings, ...landingWarnings];
 
 	// Partition edits into bof, eof, and anchor-targeted buckets.
 	const bofLines: string[] = [];