laddercodec 0.2.2__tar.gz → 0.3.0__tar.gz

{laddercodec-0.2.2 → laddercodec-0.3.0}/AGENTS.md

@@ -43,6 +43,7 @@ src/laddercodec/
 ├── binary_helpers.py     # Shared binary primitives: UTF-16LE encode/decode, tagged fields
 ├── decode.py             # Decoder: decode() + internal decode_rung(), decode_rungs()
 ├── decode_program.py     # Program file decoder: decode_program() — Scr*.tmp to Program
+├── compat.py             # find_v4_only() / is_v4_only(): instructions an older CLICK would mangle
 ├── cell.py               # Cell object builders: ClickCell, preamble, terminal, row
 ├── topology.py           # Program header, rung preamble, cell offset math, wire flags
 ├── empty_multirow.py     # Deterministic empty multi-row payload synthesis
@@ -52,6 +53,7 @@ src/laddercodec/
 │   ├── contact.py        # Contact (NO/NC/edge/immediate), build_blob(), cell_params(), parser
 │   ├── comparison.py     # CompareContact (==, !=, >, <, >=, <=), build_blob(), cell_params(), parser
 │   ├── coil.py           # Coil (out/latch/reset, range, immediate, oneshot), build_blob(), cell_params(), parser
+│   ├── out_variant.py    # OutVariant (CLICK v4 toggle/debounce/flasher/timed), build_blob(), cell_params(), parser
 │   ├── timer.py          # Timer (on_delay/off_delay, retentive), build_blob(), cell_params(), parser
 │   ├── copy.py           # Copy (single/block/fill), BlockCopy, Fill — build_blob(), cell_params(), parser
 │   └── raw.py            # RawInstruction (opaque blob passthrough), build_blob(), cell_params()
@@ -91,6 +93,7 @@ src/laddercodec/
 tests/
 ├── test_smoke.py            # Basic sanity check
 ├── test_coverage.py         # Coverage golden fixture tests (instruction variants)
+├── test_v4_captures.py      # CLICK v4 captures: each rung decodes to its comment; native blob matching
 ├── golden_io.py             # Golden CSV/BIN read/write helpers
 ├── ladder/
 │   ├── test_encode.py       # encode() pipeline, multi-row, comments, wires, NOP
@@ -112,7 +115,8 @@ tests/
 └── 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}
+    ├── tumbler/                 # 34 real programs: <name>.scr + <name>.clipboard.{bin,csv}
+    └── v4_captures/             # CLICK v4 copy-backs of pyrung capture stubs (math, out, drum)
 ```
 
 Ladder golden fixtures are verified through Click paste round-trip. In `scr_captures`, `time_drums.bin` is synthetic (see that directory's README); do not use its differences from SCR as evidence of native cleanup. 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.
@@ -209,8 +213,10 @@ When the user provides a `.bin` + `.csv` from a Click capture:
 
 1. **Inspect the capture:** `uv run devtools/inspect_bin.py <file.bin>` — shows known instructions with `to_csv()` output, and RawInstruction/Unknown blobs with full tagged-field breakdown (tag IDs, sentinel types, values).
 2. **Identify what's new:** RawInstruction means the class name is recognized but the func code isn't. The field breakdown shows exactly which func code / field values differ from existing support.
-3. **Update the code:** add func codes, fields, or new instruction modules as needed. Update `csv/converter.py` to pass new kwargs through.
+3. **Update the code:** add func codes, fields, or new instruction modules as needed; CSV parsing goes through the family `SPEC`'s `parse_csv_call`.
 4. **Update coverage CSV:** `tests/fixtures/coverage/golden/<name>.csv` — use kwargs style for boolean flags (e.g. `oneshot=1`).
 5. **Verify:** `make test` + `make lint`.
 
+For CLICK v4 instructions captured from pyrung stubs (`tests/fixtures/v4_captures/`, `tests/test_v4_captures.py`), see "Capturing from CLICK v4" in the guide.
+
 See [`docs/guides/adding-instructions.md`](docs/guides/adding-instructions.md) for the full guide.

{laddercodec-0.2.2 → laddercodec-0.3.0}/CHANGELOG.md

@@ -8,6 +8,30 @@
      Review and condense before release — entries accumulate during development and
      should be edited into shape before moving from Unreleased to a version heading. -->
 
+## 0.3.0 (2026-11-01)
+
+### Added
+- **CLICK v4 Out variants**: `toggle(C1)`, `debounce(...)`, `flasher(...)` and `timed(...)` decode and encode as `OutVariant`, exported from the root package, matching Click-written blobs byte for byte.
+- **CLICK v4 Time & Event drum**: `time_event_drum(outputs=[...],presets=[1000,None,DS1],events=[None,C1,C2],unit=Tms,...)` decodes and encodes as `Drum(drum_kind="time_event")`, with `None` marking a step without a preset or event.
+- **CLICK v4 Break and Continue**: `break()` and `continue()` decode and encode as `Break` and `Continue`, exported from the root package; both used to decode as `next()`.
+- **CLICK v4 Math**: wide ranges encode up to CLICK's limit of 5000 interior addresses, where more than 500 used to raise `ValueError`, and `XD`/`YD` registers are recognized as operands, including `XD0u` and its place inside a range.
+- **CLICK v4 check**: `find_v4_only(rungs)` lists the instructions an older CLICK would silently change or may not hold (Break/Continue, Out variants, Time & Event drums, time drums with a duration from a register, v4 math functions, SUM over bits, Math ranges past 500 interior addresses), and `is_v4_only()` checks one.
+- **Pin OR legs**: OR legs under a counter, shift or drum pin push the later pins down and grow the box as CLICK does, in clipboard and SCR, exposed as `pin_rows`.
+
+### Changed
+- **CSV read**: a blank-AF row directly under `count_down` is an OR leg of its Down input rather than the bridge row.
+- **CSV errors**: pins out of order or repeated raise `ConvertError` instead of being dropped, a pin a timer does not have (e.g. `.down()`) raises `ConvertError` instead of reading as a blank row, and `write_csv` refuses a leg drawn onto an unused pin's row, which CSV cannot express.
+
+### Fixed
+- **Math encode**: formulas and constants are written the way Click's editor writes them (`ABS(x)*2` → `ABS ( x ) * 2`, `RAND` in its infix form, range interiors listed, `Ah` → `UH10`, `-5` → `H-5`, `-2.5` → `F-2.5`), so pasted formulas no longer raise Math instruction errors or fail CLICK v4's syntax check.
+- **Math encode**: `show_nicknames=True` wraps each operand once, where repeated or overlapping addresses (`DS10 + DS1 + DS1`) came out corrupted.
+- **Math decode**: `XD`/`YD` formulas keep their display constants, instead of `XD0 AND 1h` reading back as `XD0 AND UH1`.
+- **Drum encode**: with Jump off, Jog takes the func code Jump would have, so CLICK v4 no longer rejects a pasted drum with C000A ("all inputs of the box instruction must originate from the same branch").
+- **Unknown coils and drums**: an Out coil with an unknown func code or a drum with an unknown base decodes as `raw(...)`, instead of silently decoding as a plain `out(...)` or `time_drum`.
+- **Raw multi-part instructions**: a `raw(...)` token with part count 2+ rebuilds Click's part bytes, so `write_csv` no longer fails its round-trip check on raw drums and SCR raw blobs carry the right bytes.
+- **CSV read, OR inputs on boxes**: OR legs under any timer, counter, shift or drum input push its later pins down, so a `count_down` fed by a 3+ row OR no longer raises and a retentive timer fed by a 2+ row OR keeps its `.reset()`.
+- **CSV writer**: a box's empty pin rows and a `count_down`'s empty top row stay in place when a blank-AF row or a `count_down` follows, where `write_csv` used to fail its round-trip check.
+
 ## 0.2.2 (2026-09-10)
 
 ### Fixed

{laddercodec-0.2.2 → laddercodec-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: laddercodec
-Version: 0.2.2
+Version: 0.3.0
 Summary: Binary codec for AutomationDirect CLICK PLC ladder clipboard format
 Project-URL: Repository, https://github.com/ssweber/laddercodec
 Project-URL: Documentation, https://pyrung.com/laddercodec/

{laddercodec-0.2.2 → laddercodec-0.3.0}/devtools/dump_scr_tags.py

@@ -31,7 +31,8 @@ def main() -> None:
             row = data[cursor]
             col = data[cursor + 1]
             blob_start = cursor + 8
-            cls, typ, end_off, m1 = blob
+            cls, typ, end_off, part_rows = blob
+            m1 = len(part_rows)
             next_pos = end_off + 2 + data[end_off]  # trailer-aware advance
 
             # Parse tagged fields

{laddercodec-0.2.2 → laddercodec-0.3.0}/docs/gen_reference.py

@@ -26,7 +26,16 @@ PAGES: tuple[ReferencePage, ...] = (
         title="Codec API",
         tier="Stable Core",
         summary="Encode and decode Click clipboard binary and program files.",
-        symbols=("encode", "decode", "decode_program", "Rung", "Program", "Project"),
+        symbols=(
+            "encode",
+            "decode",
+            "decode_program",
+            "Rung",
+            "Program",
+            "Project",
+            "find_v4_only",
+            "is_v4_only",
+        ),
     ),
     ReferencePage(
         slug="csv",
@@ -44,6 +53,7 @@ PAGES: tuple[ReferencePage, ...] = (
             "Contact",
             "CompareContact",
             "Coil",
+            "OutVariant",
             "Timer",
             "Counter",
             "Copy",
@@ -60,6 +70,8 @@ PAGES: tuple[ReferencePage, ...] = (
             "End",
             "ForLoop",
             "Next",
+            "Break",
+            "Continue",
             "Send",
             "Receive",
             "ModbusAddress",

{laddercodec-0.2.2 → laddercodec-0.3.0}/docs/guides/adding-instructions.md

@@ -69,7 +69,14 @@ In `src/laddercodec/instructions/<module>.py`:
 - Add any new fields to the dataclass (e.g. `oneshot: bool = False`)
 - Update `build_blob()` to emit the new field value
 - Update `to_csv()` to include the new parameter
-- Update `parse_blob()` to extract the new field from the func code table
+- Update `from_tags()` to extract the new field from the func code table
+
+If the new variant shares a class name with an existing family (CLICK v4's toggle,
+debounce, flasher and timed are all class `Out`, type 0x2715), the existing family's
+`from_tags()` must return `None` for func codes it doesn't know. Otherwise the variant
+decodes silently as the old instruction. `from_tags()` dispatch tries every family in
+turn, so the new family can set `binary_class_names=()` and leave the class name's
+registry entry to the existing one (see `out_variant.py`).
 
 ### 3. Update the CSV-facing parse path
 
@@ -101,7 +108,7 @@ Same as above. For new types, inspect will often show `RawInstruction` with a ne
 In `src/laddercodec/instructions/`:
 
 - New `@dataclass` inheriting from `AfInstruction` (or `ConditionInstruction`)
-- Implement `to_csv()`, `build_blob()`, `cell_params()`, and `parse_blob()`
+- Implement `to_csv()`, `build_blob()`, `cell_params()`, and a module-level `from_tags()`
 - Follow existing modules (coil.py, timer.py, copy.py) as templates
 - Add `InstructionType` enum value in `model.py` if it uses a new type marker
 
@@ -114,11 +121,19 @@ If the instruction also needs auto-padding in CSV, set `min_csv_rows=N` on the f
 
 Example: timers currently use `visual_rows=2` and `min_csv_rows=2`, while counter/shift/drum families use explicit higher CSV row counts because their lower rows have pin semantics.
 
+`visual_rows` sets both cell header bytes, `+0x09` (rows spanned) and `+0x0A`
+(sub-rows). When a native capture shows them differing, add `"sub_rows"` for
+`+0x0A`: CLICK v4's timed coil spans 2 rows but writes 3 (`{"visual_rows": 2, "sub_rows": 3}`).
+
+**Reading tags in `from_tags()`:** flag tags (`0x11xx`/`0x12xx`) are present in
+`tags` with an empty value when set, and absent when `0`. Test them with
+`0x1201 in tags`, not by value.
+
 Also add a family `SPEC` in the module:
 
 - `binary_class_names`
 - `csv_names`
-- `parse_blob`
+- `from_tags`
 - `parse_csv_call` (for AF families)
 - `pin_names` if the family uses dot-prefixed continuation rows
 - `min_csv_rows` if the family should auto-pad in CSV
@@ -129,6 +144,8 @@ Also add a family `SPEC` in the module:
 |------|---------------|
 | `instructions/__init__.py` | Register the family `SPEC` in `AF_FAMILY_SPECS` or `CONDITION_FAMILY_SPECS`, and re-export the new class |
 | `__init__.py` | Re-export the new class in the public API |
+| `tests/test_public_api.py` | Add the class to `EXPECTED_ROOT_EXPORTS`, which pins the root `__all__` |
+| `docs/gen_reference.py` | Add the class to the Instructions API page; `make docs-build` fails on an unlisted export |
 
 `KNOWN_AF_NAMES` is now derived from the registered family specs, so `csv/ast.py` does not need manual token updates.
 
@@ -162,7 +179,7 @@ Coverage golden fixtures live in `tests/fixtures/coverage/golden/`. Each fixture
 
 ### Adding a fixture
 
-1. Create `tests/fixtures/coverage/golden/<rung_id>.csv` by hand — one rung per file, 33-column canonical format.
+1. Create `tests/fixtures/coverage/golden/<rung_id>.csv` by hand in the 33-column canonical format. Usually one rung per file; a file can hold several rungs (`math__v4.csv` holds 23) and is verified as one paste.
 2. Run `make coverage-golden` to generate the `.bin` from the CSV.
 3. Paste-verify in Click using `clicknick-rung guided`.
 4. `make test` — each `.csv` with a matching `.bin` gets a parametrized test comparing encoded output to golden binaries.
@@ -187,6 +204,49 @@ uv run devtools/combine_coverage.py --seed 42 # reproducible pick
 
 This picks N random coverage CSVs, stacks their data rows into one multi-row rung, and writes `devtools/combined.csv` + `devtools/combined.bin` for paste-testing.
 
+## Capturing from CLICK v4
+
+New CLICK v4 instructions are captured in groups. The paste CSVs are built with
+pyrung by `scratchpad/click-v4/captures/v4_capture.py`, whose README has the
+CLICK-side steps and address map per group. Each rung's comment is its id, then
+every AF token it should decode to, in row order:
+
+```
+#,drum__te_ds
+#,"time_event_drum(outputs=[C1321,C1322],presets=[DS1301,None],...)"
+#,.reset()
+```
+
+Run clicknick against the local checkouts, so `load` encodes with the laddercodec
+you are changing. From the clicknick directory:
+
+```bash
+make install-dev          # editable ../pyclickplc, ../pyrung, ../laddercodec
+UV_NO_SYNC=1 uv run --no-sync clicknick-rung load ../laddercodec/scratchpad/click-v4/captures/stubs/<group>.csv
+# build each rung in CLICK as its comment says, copy them all back, then:
+UV_NO_SYNC=1 uv run --no-sync clicknick-rung save ../laddercodec/scratchpad/click-v4/captures/copyback/<group>
+```
+
+A rung whose instruction laddercodec can't encode yet is pasted as a placeholder
+(NOP, or a v3 instruction with `1` standing in for a blank or register preset);
+its comment still names the target.
+
+In laddercodec:
+
+1. Copy `scratchpad/click-v4/captures/copyback/<group>.bin` to `tests/fixtures/v4_captures/`. `tests/test_v4_captures.py`
+   checks every labelled rung: one still decoding as `raw(...)` is xfail, any other
+   mismatch fails, and every capture must survive `write_csv`.
+2. Map the fields of the raw blobs (`devtools/inspect_bin.py`, or the `raw(...)`
+   tokens in the saved CSV) and model the instruction until its rungs pass.
+3. Add a test that re-encoding matches the blobs Click wrote, field for field
+   (see `test_out_variant_blobs_match_native` and `test_time_event_drum_blobs_match_native`).
+4. For the encode side, copy `scratchpad/click-v4/captures/expected/<group>.csv` (real tokens in the
+   AF column) to a coverage golden `<family>__v4.csv`, run `make coverage-golden`,
+   and paste-verify it with `clicknick-rung guided`.
+
+A typo made while building rungs in CLICK shows up as a failing rung, not an
+xfail. Fix the rung in CLICK and save again.
+
 ## Clicknick compatibility
 
 The `clicknick-rung guided` tool extracts operand addresses from CSV tokens for MDB provisioning. It uses `to_csv()` + regex to find address patterns, so **new instruction types work automatically** — no clicknick changes needed.

{laddercodec-0.2.2 → laddercodec-0.3.0}/docs/guides/csv-format.md

@@ -293,6 +293,38 @@ Builder side conditions are emitted as continuation rows with dot tokens in `AF`
 Pin rows are independent left-rail paths, not AND-chained through the parent
 output row conditions.
 
+Pins go in a fixed order (timers: reset; `count_up`: down, reset; `count_down`:
+reset; `shift`: clock, reset; drums: reset, jump, jog). Rows without an AF token
+between the instruction and a pin, or between two pins, are OR legs of the input
+above, and they push the later pins down. CLICK grows the box to match:
+
+```csv
+R,C1,-,...,-,"time_drum(...)"
+,C2,T,-,...,-,.reset()
+,C3,,...,,
+,C4,-,...,-,.jump(DS2)
+```
+
+Here `.jump()` is on row 3, not row 2. An unused pin still takes a row of its
+own, below the legs of the pin above it: with Jump off, `.reset()` with one leg
+then `.jog()` puts Jog on row 4, with a blank Jump row 3 (CLICK lays out a leg
+added with Insert Row the same way). Blank rows just above the next pin are read
+as the unused pins' rows, not legs. Legs under the last pin sit below the box.
+
+The same holds for legs under the main input:
+
+```csv
+R,X1,T:X2,T,-,...,-,"count_down(CT1,CTD1,preset=3)"
+,,T:X3,|,,...,,
+,,X4,,,...,,
+,X9,-,...,-,.reset()
+```
+
+`count_down`'s main input is its Down input, on box row 1 under the unused Up,
+so this box is 5 rows with Reset on row 4. A `count_up` without `.down()` puts
+the unused Down row under the main input's legs. A timer without `.reset()`
+stays 2 rows, with its main input's legs beside and below it.
+
 ## Parsing conveniences
 
 `laddercodec.read_csv()` accepts a few parsing conveniences beyond the canonical
@@ -308,7 +340,9 @@ writer contract:
 `forloop(count, oneshot=...)` lowers to:
 
 1. `for(count)` or `for(count,oneshot=1)` row (`marker=R`)
-2. Body instruction rows (`marker=R` per emitted body instruction row)
+2. Body rungs (`marker=R` each): a bare body instruction is a wire-only rung; a
+   body rung with contacts keeps them, and holds `break()` / `continue()`
+   (CLICK v4). A nested loop is its own `for` .. `next()` run, up to three deep.
 3. Closing `next()` row (`marker=R`)
 
 ## Subroutine tail guarantee
@@ -383,6 +417,7 @@ Producer may emit:
 - `return()`
 - `for(count)` or `for(count,oneshot=1)`
 - `next()`
+- `break()`, `continue()` (CLICK v4) - on a contacted rung inside a loop
 - `raw(ClassName,hex)` - opaque instruction passthrough for binary round-trip
   fidelity. `ClassName` is the Click binary class name (unquoted) and `hex` is
   the raw blob as a hex string. Runtime no-op; preserved so CSV -> DSL -> CSV

{laddercodec-0.2.2 → laddercodec-0.3.0}/docs/guides/decoding.md

@@ -29,14 +29,15 @@ All standard Click instruction types are decoded into domain objects:
 - **Contacts** → `Contact` (NO, NC, edge, immediate)
 - **Comparison contacts** → `CompareContact` (==, !=, >, <, >=, <=)
 - **Coils** → `Coil` (out, latch, reset, immediate, range, oneshot)
+- **CLICK v4 Out variants** → `OutVariant` (toggle, debounce, flasher, timed)
 - **Timers** → `Timer` (on_delay, off_delay, retentive)
 - **Counters** → `Counter` (count_up, count_down)
 - **Copy family** → `Copy`, `BlockCopy`, `Fill`, `Pack`, `Unpack`
 - **Math** → `Math` (decimal/hex expressions)
 - **Shift registers** → `Shift`
-- **Drum sequencers** → `Drum` (event/time)
+- **Drum sequencers** → `Drum` (event, time, and CLICK v4 time & event)
 - **Table search** → `Search`
-- **Flow control** → `Call`, `Return`, `End`, `ForLoop`, `Next`
+- **Flow control** → `Call`, `Return`, `End`, `ForLoop`, `Next`, `Break`, `Continue` (CLICK v4)
 - **Modbus** → `Send`, `Receive`
 
 Unrecognised cells fall back to `RawInstruction` with the raw bytes preserved. This keeps the decoder forward-compatible — unknown instruction types don't crash the pipeline.
@@ -109,6 +110,24 @@ The returned `Program` dataclass has:
 
 Each `Rung` in `program.rungs` has the same structure as clipboard-decoded rungs, so you can pass them to `encode()`, `write_csv()`, or any other API that accepts `Rung` objects.
 
+## Check for CLICK v4 instructions
+
+An older CLICK pastes v4 rungs without complaint and changes them: Break and
+Continue come back as plain Next, which closes the loop early. Check before
+pasting into a pre-v4 CLICK:
+
+```python
+from laddercodec import find_v4_only
+
+for index, instruction in find_v4_only(rungs):
+    print(f"rung {index}: {instruction.to_csv()} needs CLICK v4")
+```
+
+v4-only: `Break`, `Continue`, `OutVariant`, a time & event `Drum`, a time `Drum`
+with a duration from a register, and `Math` using MAX, MIN, MDN, AVG, ABS, RAND,
+SUM over a bit range, or ranges past 500 interior addresses. `is_v4_only()` checks
+a single instruction.
+
 ## Round-trip identity
 
 For all supported instruction types:

{laddercodec-0.2.2 → laddercodec-0.3.0}/docs/guides/encoding.md

@@ -189,7 +189,7 @@ raw address for that operand.
 All standard Click instruction families are supported from the root package:
 
 - Condition side: `Contact`, `CompareContact`
-- AF side: `Coil`, `Timer`, `Counter`, `Copy`, `BlockCopy`, `Fill`, `Pack`, `Unpack`, `Math`, `Shift`, `Search`, `Drum`, `Call`, `Return`, `End`, `ForLoop`, `Next`, `Send`, `Receive`
+- AF side: `Coil`, `OutVariant`, `Timer`, `Counter`, `Copy`, `BlockCopy`, `Fill`, `Pack`, `Unpack`, `Math`, `Shift`, `Search`, `Drum`, `Call`, `Return`, `End`, `ForLoop`, `Next`, `Send`, `Receive`
 
 Unknown AF blobs can still be preserved via `RawInstruction`, which keeps the
 binary payload intact for lossless round-trip.

laddercodec-0.3.0/docs/internals/instruction-blobs.md

@@ -0,0 +1,206 @@
+# Instruction Blobs
+
+This page documents the variable-length instruction data that follows the cell header in instruction cells. The blob starts at cell offset +0x25.
+
+For field layouts, func code tables, and tag constants for each known instruction type, see the source in `src/laddercodec/instructions/` — each module (`contact.py`, `comparison.py`, `coil.py`, `timer.py`) is the authoritative reference.
+
+## Generic blob structure
+
+All instruction blobs follow the same pattern:
+
+```
+[UTF-16LE class name, null-terminated]
+[type marker: uint32 LE, high byte always 0x27]
+[part count: uint16 LE (0x01 for contacts/coils, 0x02 for timers)]
+[extra bytes: (part_count - 1) bytes, if part_count > 1 — each later part's row]
+[field count: uint32 LE]
+[tagged fields...]
+```
+
+### Part rows
+
+A tall instruction's extra bytes give the row, below the main row, of each later
+part: `01` for a timer's reset, `01 02` for a counter (down, reset) or shift
+(clock, reset), `01 02 03` for a drum (reset, jump, jog). OR legs under an
+input (the main one included) push the later parts down, and CLICK grows the
+box: a drum with one leg under reset is `01 03 04`. A count_down's main part is
+its unused Up input, so its Down input is the first extra byte. The AF cell's `+0x09` becomes the last part's row + 1;
+`+0x0A` keeps the base height (`tests/fixtures/v4_captures/pins.bin`).
+
+### Tagged fields
+
+Each field is:
+
+```
+[2-byte tag]
+[FF FF FF FF sentinel]
+[UTF-16LE null-terminated value]
+```
+
+Field values are string-encoded even for numeric data (e.g. `"1000"` for a timer preset). Timer fields 6–7 use a variant format with a 4-byte sub-marker instead of the `FF FF FF FF` sentinel.
+
+## Known binary class names
+
+| Class name | Type markers | Instruction | Source |
+|---|---|---|---|
+| `ContactNO` | 0x2711 (NO), 0x2712 (NC) | NO/NC contacts | `contact.py` |
+| `Edge` | 0x2713 | Rising/falling edge contacts | `contact.py` |
+| `Compare` | 0x2714 | Comparison contacts (==, !=, >, <, >=, <=) | `comparison.py` |
+| `Out` | 0x2715, 0x2716, 0x2717 | All coil types (out, latch, reset) | `coil.py` |
+| `Tmr` | 0x2718 | Timers (on_delay, off_delay) | `timer.py` |
+
+The encoder uses `Out` as the class name for all coil types; the type marker and func code determine the variant. The decoder also recognizes `Latch` and `Reset` class names from native Click captures.
+
+## Out variants (CLICK v4)
+
+CLICK v4's toggle, debounce, flasher and timed coils are `Out` blobs with type
+marker 0x2715, the same as a plain `out`. They carry 15 fields, and only the
+func code separates them from plain coils. An `Out` blob whose func code is in
+neither table decodes as `raw(Out,...)`. Source: `out_variant.py`.
+
+| Tag | Field |
+|---|---|
+| `0x6066` | target |
+| `0x6067` | range end (always empty) |
+| `0x60B3` / `0x60B4` | on preset / on accumulator (`TD`) |
+| `0x60B5` / `0x60B6` | off preset / off accumulator (debounce, flasher) |
+| `0x11F8` | oneshot (always `0`) |
+| `0x11F5` | immediate (toggle) |
+| `0x1246` | `1` for toggle |
+| `0x1247` | maintained (timed) |
+| `0x21F9` | time unit: 0 ms, 1 s, 2 min |
+| `0x2248` | variant: 0 toggle, 1 debounce, 2 flasher, 3 timed |
+| `0x3218` | func code |
+| `0x20CA` | always `2` |
+
+| Variant | Func codes | Units | Rows (`+0x09` / `+0x0A`) |
+|---|---|---|---|
+| toggle | 8224, immediate 8225 | — | 1 / 1 |
+| debounce | 8226 ms, 8227 s | ms, s | 3 / 3 |
+| flasher | 8228 ms, 8229 s | ms, s | 3 / 3 |
+| timed | 8230–8232 ms/s/min, maintained 8233–8235 | ms, s, min | 2 / 3 |
+
+Each phase stores only its accumulator; Click claims the `T` of the same number
+with it. Timed is the one AF instruction whose cell header has more visual
+sub-rows (`+0x0A`) than rows spanned (`+0x09`).
+
+## Time & Event drum (CLICK v4)
+
+A drum's base is tag `0x2200`: `0` time, `1` event, `2` time & event. Any other
+value decodes as `raw(Drum,...)`. Source: `drum.py`.
+
+CLICK v4 copies every drum back with 82 fields: the 63 v3 fields, then 16 preset
+slots (`0x6891`), `0x428A`, `0x6068` and the terminator. The encoder writes the
+82-field layout for time & event drums only. Time and event drums keep the
+64-field v3 layout, which CLICK v4 still accepts.
+
+| Tag | Time & event drum |
+|---|---|
+| `0x6872` ×16 | events (blank for a step without one) |
+| `0x6891` ×16 | presets (blank for a step without one) |
+| `0x6068` | done bit of the accumulator's timer (`TD101` → `T101`) |
+| `0x428A` | `-1` as written by the encoder; see below |
+| `0x3A05` ×4 | func codes; no-jog base Tms 10503, Ts 10510, Tm 10517, Th 10524, Td 10532 |
+
+The func codes have the same 7-code block shape as the time drum (base, reset,
+jump, then jog group +3..+6) and the same Td skip.
+
+In every drum the codes run consecutively over the enabled pins. With Jump off,
+Jog takes Jump's code: event `8494, 8495, 0, 8496`, not `8497`. CLICK v3
+accepts the skipped code. CLICK v4 pastes it, then fails the syntax check with
+C000A ("All inputs of the box instruction must originate from the same branch")
+until the drum is reopened and OK'd (`v4_captures/drum_jog.bin`).
+
+`0x428A` looks like leftover editor state. Click fills in `-1` for a pasted drum
+that lacks the field. A time drum switched to Time & Event and back came out
+`-4`, with new func codes (Tms 10247/10248 where the v3 table has 8455/8456).
+
+## Break and Continue (CLICK v4)
+
+Break and Continue are class `Next` (type 0x2726), told apart by the func code in
+tag `0x3218`. Source: `forloop.py`.
+
+| `0x3218` | Instruction |
+|---|---|
+| absent | `next()`: v3 writes Next with the terminator field only |
+| `9220` | `next()`: CLICK v4 writes the func code |
+| `9232` | `continue()` |
+| `9233` | `break()` |
+
+Any other func code decodes as `raw(Next,...)`. Break and Continue are encoded
+with the two fields Click writes; `next()` keeps the one-field v3 form. Each
+version accepts either Next on paste and copies back its own: v3 drops `9220`,
+v4 adds it.
+
+## Math formulas
+
+A Math blob (class `Math`, type 0x271A) has 1010 tagged fields: 9 header
+fields, 500 operand slots (tag `0x6888`), 500 reserved slots (tag `0x688C`) and
+a terminator. Source: `math.py`.
+
+The formula appears four times in the header:
+
+| Tag | Field | Example for `SUM ( DS1 : DS3 ) + 5` |
+|---|---|---|
+| `0x61FF` | template, display | `SUM ( @ : @ ) + 5` |
+| `0x6228` | formula, display | `SUM ( DS1 : DS3 ) + 5` |
+| `0x6229` | template, internal | `SUM#(#@#:#@#)#+#H5` |
+| `0x61FD` | formula, internal | `SUM#(#DS1#:#DS3#)#+#H5` |
+
+- **Display form** is spaced the way Click's formula editor spaces it: one space
+  on each side of every operator, paren, comma and range colon (`ABS ( x )`,
+  `RAND ( 1 , 100 )`). The encoder normalizes `ABS(x)*2` to this form. A sign
+  stays on its constant (`( -5 )`) and is spaced from an address (`- DS401`).
+- **Internal form** is the display form with spaces replaced by `#` and each
+  bare decimal literal prefixed with `H`. Click splits it on `#`, so an
+  unspaced `ABS(` becomes a single unknown token. In CLICK v4 that pastes but
+  raises a Math instruction error.
+- **RAND** is stored infix in the internal form: `RAND ( a , b )` becomes
+  `a#RAND#b`, followed by a trailing `#` when RAND ends the formula
+  (`H1#RAND#H100#`, `H1#RAND#H10#+#DS1`). The display form keeps the function
+  call.
+
+### Operand and reserved slots
+
+Each slot is `[2B tag][4B index LE][UTF-16LE value]`, and an empty slot is just
+a null terminator. Operand slots hold every address in the formula, in order,
+duplicates included. Reserved slots hold the interior addresses of each
+`A : B` range, ranges in order. The endpoints are ordinary operands, so
+`SUM ( DS201 : DS300 )` stores DS201 and DS300 as operands and DS202..DS299 in
+the reserved slots.
+
+An `XD` or `YD` range also lists the upper half of address 0:
+`MAX ( XD0 : XD3 )` stores XD0u, XD1 and XD2.
+
+CLICK v4 copies Math back with 5000 reserved slots, not 500, for 5510 fields.
+A 500-slot blob still pastes into both v3 and v4, so the encoder writes 500
+unless the ranges have more than 500 interiors. CLICK's editor stops listing
+at 5000 without an error, even though the formula keeps the full range, and the
+encoder does the same.
+
+## Math nickname flag
+
+Math blobs contain a `nickname_flag` field (tag `0x2224`). When set to `"1"`,
+Click displays project-level tag names instead of raw addresses in the math
+formula. The flag is purely a display hint — the expression itself always
+stores concrete addresses.
+
+The `encode()` API exposes this via `show_nicknames=True`, which sets the flag
+on all math instructions in the buffer.
+
+## Blob boundary detection
+
+For unknown instruction types, the blob boundary can be detected using the generic multi-part formula:
+
+1. Read the class name (UTF-16LE, null-terminated)
+2. Read the type marker (uint32 LE)
+3. Read part count (uint16 LE), skip `(part_count - 1)` extra bytes
+4. Read field count (uint32 LE)
+5. Walk through tagged fields (each: 2B tag + 4B sentinel/marker + UTF-16LE value)
+6. The blob ends after all fields are consumed
+
+The `RawInstruction` fallback uses this formula to capture the complete blob as opaque bytes, enabling round-trip for unsupported instruction types via `raw(ClassName,hex)` CSV tokens.
+
+At the moment, `Email`, `Home`, `Position`, and `Velocity` still deliberately
+travel through this raw path. They round-trip correctly, but they are not yet
+modeled as dedicated DSL instruction classes.

laddercodec-0.3.0/scratchpad/click-v4/captures/.gitignore

@@ -0,0 +1,2 @@
+copyback/*
+!copyback/.gitkeep

laddercodec-0.3.0/scratchpad/click-v4/captures/README.md

@@ -0,0 +1,61 @@
+# CLICK v4 captures
+
+`v4_capture.py` writes one paste CSV per group into `stubs/`, plus pyrung's own export into `expected/`.
+Each rung's comment is its id, then every AF token it should decode to. laddercodec's
+`tests/test_v4_captures.py` checks every captured rung against that comment.
+The laddercodec side of the loop is in `docs/guides/adding-instructions.md`, "Capturing from CLICK v4".
+
+The generator builds the rungs with pyrung, so it runs in pyrung's environment. From the laddercodec root:
+
+```
+uv run --project ../pyrung python scratchpad/click-v4/captures/v4_capture.py
+```
+
+Done so far: math, out, drum, pins (fixtures in `tests/fixtures/v4_captures/`, goldens `<group>__v4` in
+`tests/fixtures/coverage/golden/`). loop: Break/Continue taken from a hand capture (`loop_exits.bin`); the
+`loop__v4` golden (the whole group, real Break/Continue) is paste-verified, so `stubs/loop.csv` needs no copy-back.
+
+## Per group
+
+Run clicknick against the local checkouts (`make install-dev` in clicknick once, then `UV_NO_SYNC=1` and
+`uv run --no-sync`). From the clicknick directory:
+
+1. `clicknick-rung load ../laddercodec/scratchpad/click-v4/captures/stubs/<group>.csv`, then paste into CLICK v4.
+2. Build each rung from its comment (see "What to do" below), then Syntax Check.
+3. Select all the group's rungs and copy them, then
+   `clicknick-rung save ../laddercodec/scratchpad/click-v4/captures/copyback/<group>`
+   (this writes `<group>.bin` and `<group>.csv`; keep it out of `stubs/`, which the generator rewrites;
+   `save` does not create `copyback/`).
+   Once every rung matches its comment or decodes as `raw(...)`, copy the `.bin` to
+   `tests/fixtures/v4_captures/` and delete the copy-back.
+4. In laddercodec, `make test`: rungs still decoded as `raw(...)` are xfail, and any other mismatch fails.
+
+What to do in CLICK:
+
+| Group | Placeholder | What to do |
+|---|---|---|
+| out | NOP | Replace it with Out using the variant in the comment. `on_acc=TD5` means TD5 in the dialog. |
+| drum | v3 Time drum | Change the base to Time & Event. Set each event; blank the preset where the comment says `None`, and enter `DS....` where it names a register. |
+| drum `time_ds*` | real instruction | Nothing, unless the paste is rejected. |
+| math | real instruction | Nothing, unless the paste is rejected. If it is, rebuild it from the comment. |
+| loop | NOP on a contacted body rung | Replace it with Break or Continue, as the rung's comment says. The other rungs are real. |
+| pins | real instruction, each pin fed by one contact | The id names the OR'd pin(s). Under each, insert a row per extra leg and OR in the next contact up (see `expected/pins.csv`): `drum_reset_or` +1 leg on Reset, `drum_reset_or3` +2 on Reset, `drum_jump_or` +1 on Jump, `drum_all_or` +1 on each pin, `count_up_down_or` +1 on Down, `shift_clock_or` +1 on Clock. Let the box grow. Don't route a leg back up past the next pin. |
+
+Math comments use CLICK's spelling, `NAME ( a , b )` (`SUM ( ... : ... )` and `RAND ( DD111 , DD112 )` are seen
+natively; `ABS ( x )` is inferred). The `math__rand_*` bodies are stand-ins (pyrung has no `randint` yet) with
+the token written by hand. Whatever the copy-back decodes to is the answer; fix the expected line to match.
+
+A loop case is several rungs (For, body rungs, Next), each labelled `<id>/<k>` with its own AF tokens. Copy
+every rung of the group back, Next rungs included.
+
+## Address map
+
+| Group | Contacts | Targets / outputs | Timers | Data |
+|---|---|---|---|---|
+| out | C1001–C1020 | C1101–C1117, Y001–Y003 | T1–T24 / TD1–TD24 | DS1001–DS1006 (presets) |
+| drum | C1201–C1207 | C1311–C1372 (C13n1.. for drum n) | TD101–TD107 (accumulators) | DS1201–DS1207 (step), DS1210 (jump step), DS1301–DS1304 (durations); done C1401–C1407; events C1501–C1509; reset/jog/jump C1601–C1609 |
+| math | C1701–C1723 | DS1501–DS1508, DD201–DD205, DF201–DF205, DH201–DH205 | — | DS1401–DS1412, DD101–DD112, DF101–DF111, DH101–DH106, C1801–C1816 |
+| loop | C1901–C1906 (For rungs), C1921–C1926 (body rungs) | C1941–C1942 | — | DS1601–DS1613 (counters, limits) |
+| pins | C1050–C1097 (rung n: enable C(1042+8n), pin legs the next 7) | C1021–C1024 (drum outputs), C1031–C1034 (done), C1041–C1048 (shift bits) | TD111–TD114, CT1/CTD1 | DS1701–DS1704 (step), DS1710 (jump step) |
+
+T1–T40 are reserved for the Out family (C0112: an Out coil claims its whole timer number).