laddercodec 0.1.8__tar.gz → 0.2.0__tar.gz

laddercodec-0.2.0/CHANGELOG.md

@@ -0,0 +1,134 @@
+# Changelog
+
+<!-- Style guide: one sentence per entry. Describe the user-visible effect, not the
+     implementation. Group related fixes/features into a single entry when they share
+     a theme. Breaking changes and migration steps can be longer — users need the
+     specifics. Detail belongs in commit messages and PR descriptions, not here.
+
+     Review and condense before release — entries accumulate during development and
+     should be edited into shape before moving from Unreleased to a version heading. -->
+
+## 0.2.0
+
+### Fixed
+- **SCR decode**: correct the row-topology block framing — every row (including row 0) uses one uniform block format, fixing branch rungs whose wires (`T`/`|`/`-`) were silently dropped whenever a continuation row's first right-wired cell carried segment flag 1.
+- **SCR decode**: accept placement-ordered flag-table entries — native captures store columns out of order (e.g. `[6,1,0,3,2,4,5]`), which the old sorted-order validation rejected.
+- **SCR decode**: drop orphaned editor-debris wire rows stored above a rung's true row 0 (observed under drum boxes), matching what Click's own clipboard copy produces.
+
+### Changed
+- **SCR decode**: replace the heuristic topology parser (leading-row guessing, count_down special cases, end-marker scanning) with a deterministic parser derived from the verified format — see `docs/internals/binary-format.md` §"SCR row-topology blocks" for the spec.
+- **SCR decode**: `decode_program()` now parses rung records with a single forward cursor — comments, topology, and instructions are read from explicit lengths and counts instead of scanning for signatures, so comments attach to their own rung by construction and malformed files fail loudly with the byte offset (see §"SCR rung records" in the binary format doc).
+
+### Added
+- **Tumbler fixture**: 34 real Click programs (`tests/fixtures/tumbler/`), each pairing the internal `.scr` program file with a clipboard capture of the same program; `decode_program()` output is regression-tested byte-identical against the clipboard CSVs.
+- **Devtools**: `compare_csv.py` normalizes `R` vs `R1`/`R2` rung markers before comparing, so scr-derived and clipboard-saved CSVs diff cleanly.
+
+## 0.1.9
+
+### Added
+- **Time drums**: encode and decode all five time bases (`Tms`/`Ts`/`Tm`/`Th`/`Td`), plus jog and jump, matching event drums.
+- **CSV writer**: `write_csv(path, rungs, index=True)` emits 1-based sequential rung markers (`R1`, `R2`, `R3`, …) instead of plain `R`; readers accept `R` optionally followed by digits, so indexed files still round-trip.
+
+### Fixed
+- **Drum decode**: single-step event and time drums now decode from `Scr*.tmp` files instead of falling back to `RawInstruction`.
+- **Drum decode**: a stray NOP stranded on a drum's pin row is dropped instead of surfacing as a spurious `NOP` that broke `write_csv`.
+- **CSV writer**: a tall instruction (drum, timer, counter, …) with a wire branch or content running below its body keeps its rows positional instead of collapsing the following rows up, fixing `WriterError`/lost geometry on those rungs.
+
+### Performance
+- `decode_program()` is ~48% faster — topology block scanning uses `bytes.find()` instead of byte-by-byte iteration, and hot loops cache `len(data)` and precomputed constants.
+- `encode()` is ~35% faster — cell headers use a single pre-compiled `struct.Struct.pack` instead of 8 separate calls, and Math blobs use pre-computed empty slot bytes instead of 1000 per-instruction loop iterations.
+
+## 0.1.8
+
+### Fixed
+- **CSV writer**: downgrade trailing blank row mismatch from error to warning
+  when a tall instruction's stripped continuation absorbs extra blank rows on
+  read-back — fixes `WriterError` on rungs with blank rows beyond an
+  instruction's visual height
+
+## 0.1.7
+
+### Fixed
+- **SCR decode**: skip pure vertical pass-through rows in implied modifier
+  row fallback, preventing `|` → `T` and blank → `-` corruption on
+  continuation rows
+- **CSV converter**: recognize `Contact`/`CompareContact` objects with
+  `wire_down=True` during wire hydration, not just bare string tokens
+
+### Changed
+- **SCR decode**: remove `_implied_modifier_row_offsets` fallback — SCR
+  continuation row topology already encodes per-row horizontal connectivity
+  explicitly, verified across 883 rungs in 47 SCR files
+
+## 0.1.6
+
+### Fixed
+- **SCR decode**: replace backward/brute-force topology block scanning with a
+  single forward pass, fixing false positive matches from flag-table tail bytes
+  that caused spurious empty rungs with inflated row counts
+
+## 0.1.5
+
+### Changed
+- **Encode**: remove AF summary block — Click accepts multi-AF rungs without
+  it, eliminating complex gating logic
+- **CSV**: consolidate tall-instruction padding into shared hydrate/dehydrate
+  helpers in converter and writer
+
+### Added
+- **Devtools**: `combine_coverage.py` — combine random coverage fixtures into
+  a single multi-row rung for paste smoke-testing
+- **Devtools**: `coverage_golden.py` now regenerates all bins unconditionally
+
+## 0.1.4
+
+### Fixed
+- **CSV**: preserve multi-row AF round-trips, including pinned/tall AF blocks
+  away from row 0, multiple tall blocks in one rung, and generic tall
+  continuation rows
+- **SCR decode**: restore omitted wiring for generic tall AF continuation rows
+- **CSV writer**: fail loudly when emitted CSV rows lose decoded rung
+  semantics by reparsing writer output and checking for row, condition, or AF
+  mismatches before writing to disk
+
+## 0.1.3
+
+### Fixed
+- **RTF decode**: parse RTF comments structurally instead of regex-based
+  stripping, handling nested groups, font/color tables, and style toggles
+  correctly
+- **RTF decode**: handle `\uN` unicode escape sequences (signed 16-bit) and
+  validate `ansicpg1252` before decoding
+- **CSV**: preserve quoted string literals in AF token positional args — e.g.
+  `copy("d",TXT1)` no longer loses its quotes during parse
+- **Search instruction**: store text-search operands with quotes end-to-end,
+  removing the strip-on-decode/re-add-on-encode anti-pattern
+
+### Added
+- **Encode**: auto-sanitize non-ASCII characters (curly quotes, em-dashes,
+  arrows, etc.) in rung comments before RTF conversion via NFKD normalization
+
+
+## 0.1.2
+
+### Fixed
+- **Math**: preserve duplicate operands and normalize parenthesis spacing
+
+## 0.1.1
+
+### Fixed
+- **Encode**: correct `row_span` for tall AF instructions and single-rung list
+  routing
+
+## 0.1.0
+
+Initial release. Originally prototyped in
+[clicknick](https://github.com/ssweber/clicknick), then developed into a
+standalone library here.
+
+- Encode `Rung` objects or CSV into Click clipboard binary
+- Decode clipboard binary back into structured Python objects
+- Decode `Scr*.tmp` program files into `Program` objects
+- All standard Click instruction types supported natively
+- `RawInstruction` passthrough for unknown blob types
+- Zero runtime dependencies

{laddercodec-0.1.8 → laddercodec-0.2.0}/CLAUDE.md

@@ -98,6 +98,7 @@ tests/
 │   ├── test_decode.py       # decode() tests
 │   ├── test_decode_multi.py # decode() multi-rung tests
 │   ├── test_decode_program.py # decode_program() program file tests
+│   ├── test_decode_program_tumbler.py # 34 real programs: scr decode == clipboard CSV
 │   ├── test_verify_status.py # Golden verification status check
 │   ├── test_model.py        # InstructionType, operand validation
 │   └── test_empty_multirow.py  # Payload synthesis for rows 1..32
@@ -109,10 +110,12 @@ tests/
 │   ├── test_token_parser.py # Condition + AF token parsing
 │   └── test_writer.py       # CSV writer tests
 └── fixtures/
-    └── ladder_captures/golden/  # Golden CSV/BIN fixtures
+    ├── ladder_captures/golden/  # Golden CSV/BIN fixtures
+    ├── scr_captures/            # Scr program files + clipboard bins (decode_program)
+    └── tumbler/                 # 34 real programs: <name>.scr + <name>.clipboard.{bin,csv}
 ```
 
-Golden fixtures verified through Click paste round-trip.
+Golden fixtures verified through Click paste round-trip. The tumbler fixture pairs each Click internal program file (`.scr`) with a clipboard capture of the same program; `devtools/compare_csv.py <dir>` compares `<name>.csv` (scr decode) against `<name>.clipboard.csv` ground truth.
 
 ## Binary Format
 
@@ -157,7 +160,7 @@ All tested shapes pass Click round-trip (verified via paste → copy-back):
 
 The clipboard decoder (`decode.py`) reads Click clipboard binaries back into structured data. Validated against a 37-rung native capture covering all basic instruction types.
 
-The program file decoder (`decode_program.py`) reads Click's internal `Scr*.tmp` files. Returns a `Program` with name, index, and all rungs. Validated against 114-rung coverage fixture plus shift and counter programs.
+The program file decoder (`decode_program.py`) reads Click's internal `Scr*.tmp` files. Returns a `Program` with name, index, and all rungs. Validated against the 114-rung coverage fixture, shift/counter/drum programs, and the 34-program tumbler fixture (byte-identical CSV vs clipboard captures). Row topology uses the uniform row-block framing documented in `docs/internals/binary-format.md` §"SCR row-topology blocks".
 
 **All standard Click instruction types decoded natively:**
 - Contacts: NO, NC, edge (rise/fall), immediate (NO/NC)

{laddercodec-0.1.8 → laddercodec-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: laddercodec
-Version: 0.1.8
+Version: 0.2.0
 Summary: Binary codec for AutomationDirect CLICK PLC ladder clipboard format
 Project-URL: Repository, https://github.com/ssweber/laddercodec
 Project-URL: Documentation, https://ssweber.github.io/laddercodec/

{laddercodec-0.1.8 → laddercodec-0.2.0}/devtools/compare_csv.py

@@ -1,6 +1,9 @@
 """Compare {slug}.csv against {slug}.clipboard.csv in a directory.
 
-Reports which pairs are identical and which differ.
+Reports which pairs are identical and which differ.  Rung markers are
+normalized before comparison (indexed ``R1``/``R2`` vs plain ``R``), since
+scr-derived bundles are written with ``index=True`` while clipboard saves
+are not.
 
 Usage:
     uv run devtools/compare_csv.py <directory>
@@ -8,9 +11,17 @@ Usage:
 
 from __future__ import annotations
 
+import re
 import sys
 from pathlib import Path
 
+_INDEXED_MARKER = re.compile(r"^R\d+(?=,)")
+
+
+def _normalized_lines(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    return [_INDEXED_MARKER.sub("R", line) for line in text.splitlines()]
+
 
 def main() -> None:
     if len(sys.argv) != 2:
@@ -42,7 +53,7 @@ def main() -> None:
             missing += 1
             continue
 
-        if base_path.read_bytes() == clip_path.read_bytes():
+        if _normalized_lines(base_path) == _normalized_lines(clip_path):
             print(f"  IDENTICAL  {slug}")
             identical += 1
         else:

{laddercodec-0.1.8 → laddercodec-0.2.0}/devtools/dump_scr_tags.py

@@ -25,20 +25,14 @@ def main() -> None:
         print(f"\nRung {si}:")
         cursor = sec_off + 6
         for ii in range(count):
-            blob8 = _parse_blob(data, cursor + 8)
-            blob9 = _parse_blob(data, cursor + 9)
-            if blob8:
-                row = data[cursor]
-                col = data[cursor + 1]
-                blob_start = cursor + 8
-                cls, typ, end_off, next_pos, m1 = blob8
-            elif blob9:
-                row = data[cursor + 1]
-                col = data[cursor + 2]
-                blob_start = cursor + 9
-                cls, typ, end_off, next_pos, m1 = blob9
-            else:
+            blob = _parse_blob(data, cursor + 8)
+            if not blob:
                 break
+            row = data[cursor]
+            col = data[cursor + 1]
+            blob_start = cursor + 8
+            cls, typ, end_off, m1 = blob
+            next_pos = end_off + 2 + data[end_off]  # trailer-aware advance
 
             # Parse tagged fields
             pos = blob_start

{laddercodec-0.1.8 → laddercodec-0.2.0}/docs/guides/csv-format.md

@@ -6,7 +6,7 @@ used by `laddercodec` CSV tooling and by `pyrung.click.to_ladder()`.
 Relevant entry points:
 
 - `laddercodec.read_csv(path)`
-- `laddercodec.write_csv(path, rungs)`
+- `laddercodec.write_csv(path, rungs, *, index=False)`
 - `laddercodec.csv.bundle.parse_bundle(directory)`
 - `pyrung.click.to_ladder(program, tag_map)`
 - `pyrung.click.LadderBundle.write(directory)`
@@ -58,6 +58,9 @@ marker,A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z,AA,AB,AC,AD,AE,AF
 
 - `marker`:
   - `R` => first row of a rung
+  - `R<n>` (e.g. `R1`, `R2`) => first row of a rung, with an optional 1-based
+    index. `write_csv(path, rungs, index=True)` emits these; the index is
+    decorative and ignored on read.
   - `""` (blank) => continuation row of current rung
   - `#` => comment row
 - `AF`:
@@ -66,8 +69,8 @@ marker,A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z,AA,AB,AC,AD,AE,AF
 
 Rung segmentation rule for consumers:
 
-- A rung starts at each row with `marker == "R"` and continues until the next
-  `R` or EOF.
+- A rung starts at each row whose `marker` is `R` optionally followed by digits
+  (`R`, `R1`, `R2`, ...) and continues until the next such marker or EOF.
 
 ## Comment rows
 
@@ -464,4 +467,4 @@ On any issue:
 3. Treat `AF` as an opaque canonical token string unless your decoder
    intentionally parses token grammar.
 4. Treat unknown future token names as extension points (fail closed if strict).
-5. Segment rungs by `marker == "R"`.
+5. Segment rungs by a `marker` of `R` optionally followed by digits (`R`, `R1`, `R2`, ...).

{laddercodec-0.1.8 → laddercodec-0.2.0}/docs/internals/binary-format.md

@@ -198,24 +198,54 @@ The instruction blob content (tag IDs, operand values, wire types) is **identica
 
 The embedded fields at offsets +0 through +6 after the type code correspond to clipboard cell header offsets +0x09 through +0x10. The `end_offset` is an absolute file pointer to the blob boundary — the same boundary that clipboard's `find_blob_boundary()` derives by scanning tags. Tags use length-prefixed strings (no `FFFFFFFF` sentinel).
 
+The byte at `end_offset` is a 1-byte trailer length (observed 0 or 1): the next structure starts at `end_offset + 2 + data[end_offset]`. Certain instruction encodings (`RD`/`SD` always; `Copy`/`Math`/`Out`/`Drum` sometimes) emit a 1-byte trailer whose value is opaque.
+
+## SCR rung records
+
+An SCR file is a header followed by one rung record per rung, in order, parseable with a single forward cursor:
+
+```
+RUNG = [2B rung_index]        -- 1-based ordinal; asserted sequential
+       [4B rtf_len][rtf body] -- comment; rtf_len = 0 means none
+       TOPOLOGY               -- row-topology block (below)
+       [2B instr_count]       -- 0 = empty rung (nothing follows)
+       [4B section_marker]    -- only when instr_count > 0
+       instr_count x ENTRY    -- 8-byte header + blob (see framing above)
+ENTRY  = [1B row_1based][1B col][1B b2][1B b3][1B entry_seq][3B 00] + blob
+```
+
+Rung 0 carries a 7-byte file prelude instead of `rung_index`: `[2B file_marker][0d][4B total_rung_records]`. `file_marker` equals the per-file `section_marker` constant (opaque; validation magic only), and `total_rung_records` counts every rung record in the file.
+
+Programs end with 1–4 ordinary content-less rungs (the empty editor rungs below the last programmed rung; some carry a fully-wired row) — the decoder drops trailing records with no instructions and no comment. Files with `prog_idx == 1` (the main program) carry a 2-byte tail after the last record; subroutines end exactly at the last record.
+
 ## SCR row-topology blocks
 
 SCR files store per-rung wire topology in structured blocks that precede each rung's instruction section. Each block encodes the right-wire and segment-flag data that clipboard stores per-cell in the grid.
 
 ```
-[2B row_word][03 00 00]                    -- 5-byte header
-[leading-row wire blocks...]               -- rows before row 0 (count_down bridge)
-[1B af_segment][1B entry_count][00]        -- 3-byte trailer
-[entry_count x (1B seg_flag, 1B col_idx)]  -- row 0 flag table
-[continuation-row wire blocks...]          -- rows 1..N-1
-[20 00]                                    -- end marker
-[wire_down data]                           -- per-column vertical wire indices
+[2B row_word][03 00 00]         -- 5-byte header; row_word = stored rows + 1
+{ row block } x (row_word - 1)  -- one per grid row, in row order (row 0 first)
+[20 00]                         -- end marker
+[wire-down table]               -- exactly 32 column entries (see below)
+```
+
+Every row block — including row 0's — has the same uniform format:
+
 ```
+[1B flag][1B count][00]  +  count x ([1B seg][1B col])
+```
+
+- `flag` — the +0x19 segment flag of the row's AF (col 31) cell. 1 for normal output/coil/NOP rows, 0 for tall segment-0 instructions (timer/counter/drum).
+- `count` — number of right-wired cells on the row (condition cells plus AF when present). `count = 0` is an empty row: the 3-byte block `[flag][00][00]`.
+- Each entry pairs a cell's +0x19 segment flag with its column index (0–31, 31 = AF). Entries are **placement-ordered** — the column sequence is usually ascending but not guaranteed (native captures include orders like `[6,1,0,3,2,4,5]`), so columns must be treated as a set.
+
+A row block whose entries include col 0 with every condition-cell seg = 1 carries the grid-row-0 signature (row 0 is exempt from the per-row segment boundary). SCR can retain orphaned wire rows *above* the true row 0 — editor debris under a tall instruction box — which Click's own clipboard copy omits; the decoder drops non-empty stored rows preceding the first row with the row-0 signature.
 
-Each continuation-row wire block:
+The wire-down table after the `20 00` marker has exactly one entry per column 0–31:
 
 ```
-[1B seg][1B right_count][00 00][pairs of (col_idx, next_seg)...][final_col]
+no down wires: [00 00]
+down wires:    [1B count][00][count x 1-based row index]
 ```
 
-The block is parsed forward: leading-row blocks are consumed until the 3-byte trailer is found, then the row-0 flag table, then continuation rows, then the `0x0020` marker, then wire-down data.
+This table is the SCR serialization of the per-cell down flag (+0x21) that clipboard stores on each cell — it lists every down wire, including those carried by contact cells (rendered as a `T:` prefix, see [wire rendering](wire-rendering.md)). It is therefore a superset of the visible `T`/`|` wire tokens.

{laddercodec-0.1.8 → laddercodec-0.2.0}/docs/internals/wire-rendering.md

@@ -21,7 +21,7 @@ Wire tokens are classified by (right, down) only — the segment flag is indepen
 | 1 | 1 | `T` | Branch junction (right + down) |
 | 0 | 0 | *(blank)* | No wire |
 
-Instruction cells (contacts, coils) also set right=1 — they behave like horizontal wires with instruction data layered on top.
+Instruction cells (contacts, coils) also set right=1 — they behave like horizontal wires with instruction data layered on top. A contact cell can additionally set down=1 (a branch rooted directly under the contact): since right is already 1, that's the T shape, and the CSV renders it as a `T:` prefix on the contact token (e.g. `T:C1204`), mapping to `wire_down=True` on `Contact`/`CompareContact`.
 
 ## Left-edge rendering
 

{laddercodec-0.1.8 → laddercodec-0.2.0}/src/laddercodec/cell.py

@@ -21,6 +21,11 @@ from .topology import CELL_SIZE, COLS_PER_ROW
 # Instruction data starts at this offset in the cell header.
 _INSTR_DATA_OFFSET = 0x25
 
+# Pre-compiled struct for the 37-byte cell header (single pack replaces 8 calls).
+# Layout: pad(1) col(u32) row(u32) span(u8) vis(u8) 0(u8) extra(u8)
+#         instr_idx(i32) 1(u32) contact(u32) seg(u32) right(u32) down(u32)
+_HEADER_STRUCT = struct.Struct("<xIIBBBBiIIIII")
+
 
 # ---------------------------------------------------------------------------
 # Unified cell builder
@@ -67,37 +72,21 @@ class ClickCell:
     row_span: int = 1
     visual_rows: int = 1
 
-    def build_header(self) -> bytearray:
+    def build_header(self) -> bytes:
         """Build the 0x25 (37-byte) structured header."""
-        header = bytearray(_INSTR_DATA_OFFSET)
-
-        # 32-bit LE Column Index and Row Index
-        header[0x01:0x05] = struct.pack("<I", self.col)
-        header[0x05:0x09] = struct.pack("<I", self.global_row + 1)
-
-        # 8-bit structural bytes
+        # 8-bit structural bytes at +0x09..+0x0C
         if self.row_span > 1:
             # Multi-row AF instruction (timer): +0x09 = row span,
             # +0x0A = visual sub-rows, +0x0B stays 0x00 (no 0xFD marker).
-            header[0x09] = self.row_span
-            header[0x0A] = self.visual_rows
+            b09, b0a, b0c = self.row_span, self.visual_rows, 0
         elif self.blob or self.rung_has_instructions:
             # Instruction cell or wire cell in an instruction-bearing rung.
             # Native Click writes +0x0B=0x00, +0x0C=0x00 for these cells
             # (confirmed via native captures: 1rung_2rows, instr-cond__and).
-            header[0x09] = 0x01
-            header[0x0A] = 0x01
+            b09, b0a, b0c = 1, 1, 0
         else:
             # Pure wire/data cell in a wire-only rung: +0x0C = 0x01
-            header[0x09] = 0x01
-            header[0x0A] = 0x01
-            header[0x0C] = 0x01
-
-        # 32-bit LE Instruction Index (-1 packs to 0xFFFFFFFF for data cells)
-        header[0x0D:0x11] = struct.pack("<i", self.instr_index)
-
-        # 32-bit LE Structural Flag (always 1)
-        header[0x11:0x15] = struct.pack("<I", 1)
+            b09, b0a, b0c = 1, 1, 1
 
         # 32-bit LE Wire & Logic Flags
         if self.blob:
@@ -106,12 +95,20 @@ class ClickCell:
             contact_flag = self.nop_enable
         right_flag = self.af_nop if self.af_nop else self.wire_right
 
-        header[0x15:0x19] = struct.pack("<I", contact_flag)
-        header[0x19:0x1D] = struct.pack("<I", self.segment)
-        header[0x1D:0x21] = struct.pack("<I", right_flag)
-        header[0x21:0x25] = struct.pack("<I", self.wire_down)
-
-        return header
+        return _HEADER_STRUCT.pack(
+            self.col,
+            self.global_row + 1,
+            b09,
+            b0a,
+            0,
+            b0c,
+            self.instr_index,
+            1,
+            contact_flag,
+            self.segment,
+            right_flag,
+            self.wire_down,
+        )
 
     def build_tail(self) -> bytearray:
         """Build the 16-byte tail with dynamic rung index."""

{laddercodec-0.1.8 → laddercodec-0.2.0}/src/laddercodec/csv/contract.py

@@ -2,10 +2,16 @@
 
 from __future__ import annotations
 
+import re
+
 MARKER_COLUMN = "marker"
 OUTPUT_COLUMN = "AF"
 COMMENT_MARKER = "#"
 
+# Rung-start marker: ``R`` optionally followed by a 1-based decimal index
+# (``R``, ``R1``, ``R2``, ...).  The index is decorative and ignored on read.
+_RUNG_MARKER_RE = re.compile(r"R\d*")
+
 
 def _excel_column_name(index_1_based: int) -> str:
     value = index_1_based
@@ -21,8 +27,13 @@ CSV_HEADER = (MARKER_COLUMN, *CONDITION_COLUMNS, OUTPUT_COLUMN)
 TOTAL_COLUMNS = len(CSV_HEADER)
 
 
+def is_rung_marker(value: str) -> bool:
+    """Return True for a rung-start marker: ``R`` with optional 1-based index."""
+    return _RUNG_MARKER_RE.fullmatch(value) is not None
+
+
 def is_valid_marker(value: str) -> bool:
-    return value in {"R", "", COMMENT_MARKER}
+    return value in {"", COMMENT_MARKER} or is_rung_marker(value)
 
 
 def validate_header(fields: list[str]) -> None:

{laddercodec-0.1.8 → laddercodec-0.2.0}/src/laddercodec/csv/parser.py

@@ -8,7 +8,7 @@ from pathlib import Path
 from typing import Literal
 
 from .ast import CanonicalRow, ParsedCsvFileAst, RowAst, RungAst
-from .contract import TOTAL_COLUMNS, is_valid_marker, validate_header
+from .contract import TOTAL_COLUMNS, is_rung_marker, is_valid_marker, validate_header
 from .token_parser import parse_af_token, parse_condition_token
 
 
@@ -24,7 +24,9 @@ def _detect_file_role(path: Path) -> tuple[Literal["main", "subroutine"], str |
 def _canonical_row_from_fields(fields: list[str]) -> CanonicalRow:
     marker = fields[0].strip() if fields else ""
     if not is_valid_marker(marker):
-        raise ValueError(f"Invalid marker {marker!r}; expected 'R', '#', or blank")
+        raise ValueError(
+            f"Invalid marker {marker!r}; expected 'R' (optionally indexed, e.g. R1), '#', or blank"
+        )
 
     # Comment rows may be short (just marker + text); pad to full width.
     # Preserve whitespace in column A for code-style comments (indentation).
@@ -67,7 +69,7 @@ def _segment_rungs(rows: tuple[RowAst, ...]) -> tuple[RungAst, ...]:
             pending_comments.append(row)
             continue
 
-        if row.canonical.marker == "R":
+        if is_rung_marker(row.canonical.marker):
             if current:
                 rungs.append(RungAst(comment_rows=tuple(current_comments), rows=tuple(current)))
             current = [row]

{laddercodec-0.1.8 → laddercodec-0.2.0}/src/laddercodec/csv/writer.py

@@ -104,13 +104,32 @@ def _append_data_row(
     return data_row_count + 1
 
 
+def _followed_by_floating_row(af_tokens: Sequence[object], span_end: int) -> bool:
+    """True when a blank-AF row sits just below a tall instruction's span.
+
+    Such a row would be absorbed into the instruction's continuation slots on
+    reparse, so the instruction's trailing padding must stay positional rather
+    than dehydrated — otherwise the following content floats up.  A real AF
+    instruction (or the end of the rung) anchors the position, so dehydration
+    is safe there.
+    """
+    return span_end < len(af_tokens) and af_tokens[span_end] == ""
+
+
 def _emit_blank_continuation(
     rows: list[list[str]],
     data_row_count: int,
     conditions: Sequence[object],
+    keep_positional: bool = False,
 ) -> int:
-    """Emit a blank-AF continuation row only when it carries geometry."""
-    if _is_padding_row(conditions):
+    """Emit a blank-AF continuation row.
+
+    Trailing padding (blank cells and ``|`` pass-through wires) is dehydrated —
+    the reparser rebuilds it from the instruction's visual height.  But when a
+    blank-AF row follows the instruction's span (``keep_positional``), the row
+    is emitted so following content keeps its position on reparse.
+    """
+    if not keep_positional and _is_padding_row(conditions):
         return data_row_count
     return _append_data_row(rows, data_row_count, conditions, "")
 
@@ -139,13 +158,16 @@ def _emit_timer_block(
         message="timer continuation row must be blank AF",
     )
 
+    keep = _followed_by_floating_row(af_tokens, start + 2)
     data_row_count = _append_data_row(rows, data_row_count, condition_rows[start], timer)
     if timer.retained:
         data_row_count = _append_data_row(
             rows, data_row_count, condition_rows[start + 1], ".reset()"
         )
     else:
-        data_row_count = _emit_blank_continuation(rows, data_row_count, condition_rows[start + 1])
+        data_row_count = _emit_blank_continuation(
+            rows, data_row_count, condition_rows[start + 1], keep
+        )
     return data_row_count, 2
 
 
@@ -164,6 +186,7 @@ def _emit_counter_block(
             f"{counter.counter_type} requires {needed} decoded rows; got {len(condition_rows)}"
         )
 
+    keep = _followed_by_floating_row(af_tokens, start + 3)
     if counter.counter_type == "count_up":
         _require_blank_af(
             af_tokens[start + 1],
@@ -180,7 +203,7 @@ def _emit_counter_block(
             )
         else:
             data_row_count = _emit_blank_continuation(
-                rows, data_row_count, condition_rows[start + 1]
+                rows, data_row_count, condition_rows[start + 1], keep
             )
         if counter.reset_enabled:
             data_row_count = _append_data_row(
@@ -188,7 +211,7 @@ def _emit_counter_block(
             )
         else:
             data_row_count = _emit_blank_continuation(
-                rows, data_row_count, condition_rows[start + 2]
+                rows, data_row_count, condition_rows[start + 2], keep
             )
         return data_row_count, 3
 
@@ -212,7 +235,9 @@ def _emit_counter_block(
             rows, data_row_count, condition_rows[start + 2], ".reset()"
         )
     else:
-        data_row_count = _emit_blank_continuation(rows, data_row_count, condition_rows[start + 2])
+        data_row_count = _emit_blank_continuation(
+            rows, data_row_count, condition_rows[start + 2], keep
+        )
     return data_row_count, 3
 
 
@@ -270,6 +295,7 @@ def _emit_drum_block(
         message="drum .jog() row must be blank AF",
     )
 
+    keep = _followed_by_floating_row(af_tokens, start + 4)
     data_row_count = _append_data_row(rows, data_row_count, condition_rows[start], drum)
     data_row_count = _append_data_row(rows, data_row_count, condition_rows[start + 1], ".reset()")
     if drum.jump_enabled:
@@ -280,11 +306,15 @@ def _emit_drum_block(
             f".jump({drum.jump_target})",
         )
     else:
-        data_row_count = _emit_blank_continuation(rows, data_row_count, condition_rows[start + 2])
+        data_row_count = _emit_blank_continuation(
+            rows, data_row_count, condition_rows[start + 2], keep
+        )
     if drum.jog_enabled:
         data_row_count = _append_data_row(rows, data_row_count, condition_rows[start + 3], ".jog()")
     else:
-        data_row_count = _emit_blank_continuation(rows, data_row_count, condition_rows[start + 3])
+        data_row_count = _emit_blank_continuation(
+            rows, data_row_count, condition_rows[start + 3], keep
+        )
     return data_row_count, 4
 
 
@@ -304,6 +334,7 @@ def _emit_generic_tall_block(
             f"{type(af).__name__} requires {needed} decoded rows; got {len(condition_rows)}"
         )
 
+    keep = _followed_by_floating_row(af_tokens, start + visual_rows)
     data_row_count = _append_data_row(rows, data_row_count, condition_rows[start], af)
     for offset in range(1, visual_rows):
         _require_blank_af(
@@ -311,7 +342,7 @@ def _emit_generic_tall_block(
             message=f"{type(af).__name__} continuation row must be blank AF",
         )
         data_row_count = _emit_blank_continuation(
-            rows, data_row_count, condition_rows[start + offset]
+            rows, data_row_count, condition_rows[start + offset], keep
         )
     return data_row_count, visual_rows
 
@@ -498,6 +529,8 @@ def decoded_rung_to_rows(rung: Rung) -> list[list[str]]:
 def write_csv(
     path: Path | str,
     rungs: list[Rung],
+    *,
+    index: bool = False,
 ) -> None:
     """Write decoded rungs to a canonical CSV file.
 
@@ -508,6 +541,12 @@ def write_csv(
     rungs:
         One or more decoded rungs (from ``decode_rung()`` or
         ``decode_rungs()``).
+    index:
+        When ``True``, the per-rung ``R`` marker is replaced with a 1-based
+        sequential index (``R1``, ``R2``, ``R3``, ...) counting across the
+        whole file.  The default (``False``) emits a plain ``R``.  Indexed
+        files still round-trip through ``read_csv()`` — the digits are
+        decorative and ignored on read.
 
     Raises
     ------
@@ -518,6 +557,8 @@ def write_csv(
     with open(path, "w", newline="", encoding="utf-8") as f:
         writer = csv_mod.writer(f)
         writer.writerow(CSV_HEADER)
-        for rung in rungs:
+        for rung_number, rung in enumerate(rungs, start=1):  # start=1 → first rung is R1
             for row in decoded_rung_to_rows(rung):
+                if index and row and row[0] == "R":
+                    row = [f"R{rung_number}", *row[1:]]
                 writer.writerow(row)