laddercodec 0.2.1__tar.gz → 0.3.0__tar.gz

laddercodec-0.3.0/.github/scripts/check_public_site.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Reject private sources and incomplete generated docs in the public site."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+BLOCKED_FILENAMES = {
+    "agents",
+    "agents.html",
+    "agents.md",
+    "claude",
+    "claude.html",
+    "claude.md",
+    "gen_llms.py",
+    "gen_reference.py",
+    "llms-full.txt",
+}
+BLOCKED_PATH_PARTS = {"__pycache__", "agents", "claude"}
+EXPECTED_FILES = {
+    "index.html",
+    "llms.txt",
+    "reference/index.html",
+    "reference/api/codec/index.html",
+    "reference/api/csv/index.html",
+    "reference/api/instructions/index.html",
+}
+
+
+def ascii_text(value: object) -> str:
+    return str(value).encode("ascii", errors="backslashreplace").decode("ascii")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Check generated public-site paths.")
+    parser.add_argument("site", type=Path, help="Generated site directory to inspect")
+    args = parser.parse_args()
+
+    site = args.site
+    if not site.is_dir():
+        print(f"ERROR: public site directory does not exist: {ascii_text(site)}")
+        return 2
+
+    violations: list[str] = []
+    actual_files = {
+        path.relative_to(site).as_posix()
+        for path in site.rglob("*")
+        if path.is_file()
+    }
+    for relative_path in actual_files:
+        path = Path(relative_path)
+        if path.name.lower() in BLOCKED_FILENAMES or any(
+            part.lower() in BLOCKED_PATH_PARTS for part in path.parts
+        ):
+            violations.append(f"blocked public-site path: {relative_path}")
+
+    for missing in sorted(EXPECTED_FILES - actual_files):
+        violations.append(f"missing expected public-site path: {missing}")
+
+    for path in site.rglob("*"):
+        if path.suffix.lower() not in {".html", ".md", ".txt"} or not path.is_file():
+            continue
+        if "::: laddercodec." in path.read_text(encoding="utf-8", errors="replace"):
+            relative_path = path.relative_to(site).as_posix()
+            violations.append(f"unrendered API directive: {relative_path}")
+
+    if violations:
+        for violation in sorted(violations):
+            print(f"ERROR: {ascii_text(violation)}")
+        print(f"ERROR: public-site guard found {len(violations)} violation(s).")
+        return 1
+
+    print(f"OK: public-site guard passed: {ascii_text(site)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

laddercodec-0.3.0/.github/scripts/prune_public_site.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Remove explicitly private source files copied by Zensical 0.0.57."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+from pathlib import Path
+
+
+PRIVATE_ROOT_NAMES = {
+    "__pycache__",
+    "agents",
+    "agents.md",
+    "claude",
+    "claude.md",
+    "gen_llms.py",
+    "gen_reference.py",
+}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Prune private public-site paths.")
+    parser.add_argument("site", type=Path, help="Generated site directory to prune")
+    args = parser.parse_args()
+
+    site = args.site.resolve()
+    if not site.is_dir():
+        raise RuntimeError(f"Public site directory does not exist: {site}")
+
+    for path in site.iterdir():
+        if path.name.lower() not in PRIVATE_ROOT_NAMES:
+            continue
+        resolved = path.resolve()
+        if resolved.parent != site:
+            raise RuntimeError(f"Refusing to prune path outside public site: {resolved}")
+        if resolved.is_dir():
+            shutil.rmtree(resolved)
+        else:
+            resolved.unlink()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{laddercodec-0.2.1 → laddercodec-0.3.0}/.github/workflows/docs.yml

@@ -3,6 +3,8 @@ name: Docs
 on:
   push:
     branches: ["main"]
+  pull_request:
+    branches: ["main"]
   workflow_dispatch:
 
 permissions:
@@ -34,17 +36,25 @@ jobs:
       - name: Install docs dependencies
         run: uv sync --locked --group docs
 
+      - name: Cache-bust extra assets
+        run: |
+          sed -i -E "s#^(\s*- (stylesheets|javascripts)/[^?[:space:]]+)\$#\1?v=${GITHUB_SHA::8}#" mkdocs.yml
+          grep -E '\?v=' mkdocs.yml
+
       - name: Build docs
-        run: uv run mkdocs build --strict
-        env:
-          DISABLE_MKDOCS_2_WARNING: "true"
+        run: make docs-check
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
 
       - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
         uses: actions/upload-pages-artifact@v4
         with:
           path: site
 
   deploy:
+    if: github.event_name != 'pull_request'
     needs: build
     runs-on: ubuntu-latest
     environment:

{laddercodec-0.2.1 → laddercodec-0.3.0}/.gitignore

@@ -27,4 +27,5 @@ htmlcov/
 
 # Docs
 site/
+docs/reference/
 

{laddercodec-0.2.1 → 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,10 +115,11 @@ 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)
 ```
 
-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.
+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.
 
 ## Binary Format
 
@@ -127,7 +131,7 @@ Quick reference: three regions — program header (0x0254), payload region (0x02
 
 Full spec: [`docs/internals/wire-rendering.md`](docs/internals/wire-rendering.md) — flag bytes, left-edge rendering, segment flag boundary rules.
 
-Quick reference: three flag bytes per cell — segment (+0x19), right (+0x1D), down (+0x21). Wire tokens classified by (right, down) only. Segment flag boundary computed per-row. Row 0 exempt.
+Quick reference: three flag bytes per cell — segment (+0x19), right (+0x1D), down (+0x21). Wire tokens classified by (right, down) only. Segment flag boundary computed per-row. The encoder treats row 0 as exempt; native segment flags retain editing history.
 
 ## Instruction Blobs
 
@@ -160,7 +164,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 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".
+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). SCR headers use counted numeric widths and independent display flags. Every counted topology row, including the special first row, is parsed without recovery; ordinary stored wire rows are preserved. 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)
@@ -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.1 → laddercodec-0.3.0}/CHANGELOG.md

@@ -8,7 +8,43 @@
      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.1 (Unreleased)
+## 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
+- **SCR decode**: parse counted column widths, independent display flags, and all stored rows so valid populated special rows no longer trigger recovery, and malformed records fail without silently skipping a rung.
+- **SCR decode**: preserve branch wiring above a later rail-connected row instead of deleting the branch and shifting the lower wire upward.
+
+### Added
+- **Native drum regression fixtures**: preserve the original NOP's wire row and a branch above it after row insertion and drum placement, with native SCR/clipboard and CSV comparisons.
+
+### Documentation
+- Correct SCR flag meanings and fixture provenance, and distinguish native persisted flags from the encoder's construction conventions.
+
+## 0.2.1 (2026-08-25)
 
 ### Fixed
 - **SCR decode**: a Modbus `Send` at `device_id=0` no longer decodes as `device_id=1` — SCR blobs elide fields at their class default, and Send's device_id default (0) differs from Receive's (1).
@@ -23,7 +59,7 @@
 ### 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.
+- **SCR decode**: introduced deletion of presumed orphan wire rows above a later rail-connected row; the claimed native clipboard agreement was based on a synthetic fixture, and this behavior is reversed in 0.2.2.
 
 ### 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.

{laddercodec-0.2.1 → laddercodec-0.3.0}/Makefile

@@ -3,7 +3,7 @@
 
 .DEFAULT_GOAL := default
 
-.PHONY: default install lint test golden coverage-golden upgrade build clean docs-serve docs-build docs-check
+.PHONY: default install lint test golden coverage-golden upgrade build clean docs-generate docs-serve docs-build docs-check
 
 default: install lint test
 
@@ -29,11 +29,17 @@ upgrade:
 build:
 	uv build
 
-docs-serve:
-	DISABLE_MKDOCS_2_WARNING=true uv run --group docs mkdocs serve
+docs-generate:
+	uv run --group docs python docs/gen_reference.py
 
-docs-build:
-	DISABLE_MKDOCS_2_WARNING=true uv run --group docs mkdocs build --strict
+docs-serve: docs-generate
+	uv run --group docs zensical serve
+
+docs-build: docs-generate
+	uv run --group docs zensical build --clean --strict
+	uv run --group docs python .github/scripts/prune_public_site.py site
+	uv run --group docs python docs/gen_llms.py site
+	uv run --group docs python .github/scripts/check_public_site.py site
 
 docs-check: docs-build
 

laddercodec-0.3.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: laddercodec
+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/
+Author-email: ssweber <57631333+ssweber@users.noreply.github.com>
+License-Expression: MPL-2.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.11
+Description-Content-Type: text/markdown
+
+# laddercodec
+
+**The compatibility layer for CLICK ladder data.** laddercodec reads and writes CLICK's native representations and enables reliable round-tripping between CLICK and the pyrung/ClickNick toolchain. Tested against v2.60 to v3.9x captures. Zero runtime dependencies.
+
+It's the layer [ClickNick](https://pyrung.com/clicknick/) pastes through, and it's useful on its own to convert between CLICK ladder data, Python objects, and CSV.
+
+- Documentation: https://pyrung.com/laddercodec/
+- LLM docs index: https://pyrung.com/laddercodec/llms.txt
+- LLM full context: https://pyrung.com/laddercodec/llms-full.txt
+
+## Install
+
+```bash
+uv add laddercodec
+# or
+pip install laddercodec
+```
+
+Requires Python 3.11+.
+
+## Quick example
+
+```python
+from laddercodec import read_csv, encode, decode
+
+# CSV → binary (ready to paste into Click)
+rungs = read_csv("my_rung.csv")
+binary = encode(rungs[0])
+
+# Binary → structured data
+rung = decode(binary)
+print(rung.logical_rows)
+print(rung.instructions)
+```
+
+## What's included
+
+**[Encoder](https://pyrung.com/laddercodec/guides/encoding/)** — `encode()` takes `Rung` objects or canonical CSV and produces clipboard binary ready to paste into Click. Supports all standard instruction types, wire topologies, and styled comments.
+
+**[Decoder](https://pyrung.com/laddercodec/guides/decoding/)** — `decode()` reads clipboard binary back into structured Python objects (contacts, coils, timers, wires, comments). `decode_program()` reads ladder data from native CLICK program files.
+
+**[CSV I/O](https://pyrung.com/laddercodec/guides/csv-format/)** — `read_csv()` and `write_csv()` convert between the 33-column canonical CSV format and `Rung` objects. Multi-file program bundles supported.
+
+**[CLICK format reference](https://pyrung.com/laddercodec/internals/binary-format/)** — Technical reference for CLICK's native clipboard and program representations, including binary layouts and instruction records.
+
+## Status
+
+`laddercodec` is **beta** for clipboard encode/decode, CSV I/O, and `decode_program()`.
+
+`Email`, `Home`, `Position`, and `Velocity` still intentionally surface as `raw(...)` passthroughs so clipboard and program data round-trips stay lossless while those families remain opaque.
+
+## Learn more
+
+| | |
+|---|---|
+| [Encoding guide](https://pyrung.com/laddercodec/guides/encoding/) | Encode, decode, and round-trip your first rung |
+| [Decoding guide](https://pyrung.com/laddercodec/guides/decoding/) | Structured decode, program files, round-trip identity |
+| [CSV format](https://pyrung.com/laddercodec/guides/csv-format/) | 33-column canonical format, bundle layout, topology rules |
+| [Adding instructions](https://pyrung.com/laddercodec/guides/adding-instructions/) | Extend the codec with new instruction types |
+| [API reference](https://pyrung.com/laddercodec/reference/) | Auto-generated from docstrings |
+
+## Development
+
+```bash
+make install        # uv sync --all-extras --dev
+make test           # pytest
+make lint           # ruff + ty
+make golden         # regenerate .bin from .csv fixtures
+make docs-serve     # local docs dev server
+make                # all of the above
+```
+
+## License
+
+[MPL-2.0](LICENSE)

laddercodec-0.3.0/README.md

@@ -0,0 +1,75 @@
+# laddercodec
+
+**The compatibility layer for CLICK ladder data.** laddercodec reads and writes CLICK's native representations and enables reliable round-tripping between CLICK and the pyrung/ClickNick toolchain. Tested against v2.60 to v3.9x captures. Zero runtime dependencies.
+
+It's the layer [ClickNick](https://pyrung.com/clicknick/) pastes through, and it's useful on its own to convert between CLICK ladder data, Python objects, and CSV.
+
+- Documentation: https://pyrung.com/laddercodec/
+- LLM docs index: https://pyrung.com/laddercodec/llms.txt
+- LLM full context: https://pyrung.com/laddercodec/llms-full.txt
+
+## Install
+
+```bash
+uv add laddercodec
+# or
+pip install laddercodec
+```
+
+Requires Python 3.11+.
+
+## Quick example
+
+```python
+from laddercodec import read_csv, encode, decode
+
+# CSV → binary (ready to paste into Click)
+rungs = read_csv("my_rung.csv")
+binary = encode(rungs[0])
+
+# Binary → structured data
+rung = decode(binary)
+print(rung.logical_rows)
+print(rung.instructions)
+```
+
+## What's included
+
+**[Encoder](https://pyrung.com/laddercodec/guides/encoding/)** — `encode()` takes `Rung` objects or canonical CSV and produces clipboard binary ready to paste into Click. Supports all standard instruction types, wire topologies, and styled comments.
+
+**[Decoder](https://pyrung.com/laddercodec/guides/decoding/)** — `decode()` reads clipboard binary back into structured Python objects (contacts, coils, timers, wires, comments). `decode_program()` reads ladder data from native CLICK program files.
+
+**[CSV I/O](https://pyrung.com/laddercodec/guides/csv-format/)** — `read_csv()` and `write_csv()` convert between the 33-column canonical CSV format and `Rung` objects. Multi-file program bundles supported.
+
+**[CLICK format reference](https://pyrung.com/laddercodec/internals/binary-format/)** — Technical reference for CLICK's native clipboard and program representations, including binary layouts and instruction records.
+
+## Status
+
+`laddercodec` is **beta** for clipboard encode/decode, CSV I/O, and `decode_program()`.
+
+`Email`, `Home`, `Position`, and `Velocity` still intentionally surface as `raw(...)` passthroughs so clipboard and program data round-trips stay lossless while those families remain opaque.
+
+## Learn more
+
+| | |
+|---|---|
+| [Encoding guide](https://pyrung.com/laddercodec/guides/encoding/) | Encode, decode, and round-trip your first rung |
+| [Decoding guide](https://pyrung.com/laddercodec/guides/decoding/) | Structured decode, program files, round-trip identity |
+| [CSV format](https://pyrung.com/laddercodec/guides/csv-format/) | 33-column canonical format, bundle layout, topology rules |
+| [Adding instructions](https://pyrung.com/laddercodec/guides/adding-instructions/) | Extend the codec with new instruction types |
+| [API reference](https://pyrung.com/laddercodec/reference/) | Auto-generated from docstrings |
+
+## Development
+
+```bash
+make install        # uv sync --all-extras --dev
+make test           # pytest
+make lint           # ruff + ty
+make golden         # regenerate .bin from .csv fixtures
+make docs-serve     # local docs dev server
+make                # all of the above
+```
+
+## License
+
+[MPL-2.0](LICENSE)

{laddercodec-0.2.1 → 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.3.0/docs/gen_llms.py

@@ -0,0 +1,95 @@
+"""Generate a concise llms.txt index for the rendered Zensical site."""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+from collections.abc import Iterator, Sequence
+from pathlib import Path, PurePosixPath
+from urllib.parse import urljoin
+
+import yaml
+
+
+ROOT = Path(__file__).resolve().parent.parent
+CONFIG_PATH = ROOT / "mkdocs.yml"
+DOCS_DIR = ROOT / "docs"
+
+
+def _navigation_titles(nav: list[object]) -> dict[str, str]:
+    titles: dict[str, str] = {}
+
+    def visit(items: Sequence[object]) -> None:
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            for title, target in item.items():
+                if isinstance(target, str):
+                    titles[target] = str(title)
+                elif isinstance(target, list):
+                    visit(target)
+
+    visit(nav)
+    return titles
+
+
+def _source_uris(pattern: str) -> Iterator[str]:
+    candidates = sorted(
+        path.relative_to(DOCS_DIR).as_posix() for path in DOCS_DIR.rglob("*.md")
+    )
+    yield from fnmatch.filter(candidates, pattern)
+
+
+def _destination_uri(source_uri: str) -> str:
+    source = PurePosixPath(source_uri)
+    if source.name == "index.md":
+        parent = source.parent.as_posix()
+    else:
+        parent = source.with_suffix("").as_posix()
+    return "" if parent == "." else f"{parent}/"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate the LLM documentation index.")
+    parser.add_argument("site", type=Path, help="Rendered Zensical site directory")
+    args = parser.parse_args()
+
+    config = yaml.safe_load(CONFIG_PATH.read_text(encoding="utf-8"))
+    site_dir = args.site.resolve()
+    if not site_dir.is_dir():
+        raise RuntimeError(f"Rendered site directory does not exist: {site_dir}")
+
+    base_url = config["site_url"]
+    if not base_url.endswith("/"):
+        base_url += "/"
+    titles = _navigation_titles(config["nav"])
+
+    output = f"# {config['site_name']}\n\n"
+    if description := config.get("site_description"):
+        output += f"> {description}\n\n"
+
+    seen: set[str] = set()
+    for section, patterns in config["extra"]["llmstxt"]["sections"].items():
+        output += f"## {section}\n\n"
+        for pattern in patterns:
+            matches = list(_source_uris(pattern)) if "*" in pattern else [pattern]
+            for source_uri in matches:
+                if source_uri in seen:
+                    continue
+                seen.add(source_uri)
+                title = titles.get(source_uri)
+                if title is None:
+                    raise RuntimeError(f"Navigation title not found for {source_uri}")
+                destination_uri = _destination_uri(source_uri)
+                html_path = site_dir / Path(destination_uri) / "index.html"
+                if not html_path.is_file():
+                    raise RuntimeError(f"Rendered page not found: {html_path}")
+                output += f"- [{title}]({urljoin(base_url, destination_uri)})\n"
+        output += "\n"
+
+    (site_dir / "llms.txt").write_text(output, encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())