feat: migrate WIT interface to match latest version used by chonkle

Author: pjhartzell

.github/workflows/release.yml

@@ -34,7 +34,7 @@ jobs:
         run: |
           uv run componentize-py \
             --wit-path wit \
-            --world tiff-predictor-2-python \
+            --world codec \
             componentize -p src app \
             -o tiff-predictor-2-python.wasm
 

CHANGELOG.md

@@ -12,6 +12,10 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - Embedded `chonkle:signature` custom section in the Wasm binary, declaring codec metadata (identifier, implementation name, input/output port types).
 
+### Changed
+
+- Migrated WIT interface to match latest version used by `chonkle` (port-map based API).
+
 ## [v0.1.0] - 2026-03-05
 
 Initial release.

README.md

@@ -15,29 +15,35 @@ Supports 1, 2, and 4 bytes-per-sample data (uint8, uint16, uint32).
 
 ## Wasm Component interface
 
-The module is built as a [Wasm Component](https://component-model.bytecodealliance.org/) and exports a `codec` interface defined in a WebAssembly Interface Type ([WIT](https://component-model.bytecodealliance.org/design/wit.html)) file:
+The module is built as a [Wasm Component](https://component-model.bytecodealliance.org/) and exports a `transform` interface defined in a WebAssembly Interface Type ([WIT](https://component-model.bytecodealliance.org/design/wit.html)) file:
 
 ```wit
-package cylf:tiff-predictor-2-python@0.1.0;
+package chonkle:codec@0.1.0;
 
-interface codec {
-    encode: func(data: list<u8>, config: string) -> result<list<u8>, string>;
-    decode: func(data: list<u8>, config: string) -> result<list<u8>, string>;
+interface transform {
+    type port-name = string;
+    type port-map = list<tuple<port-name, list<u8>>>;
+
+    encode: func(inputs: port-map) -> result<port-map, string>;
+    decode: func(inputs: port-map) -> result<port-map, string>;
 }
 
-world tiff-predictor-2-python {
-    export codec;
+world codec {
+    export transform;
 }
 ```
 
-The `package` line declares a namespace, name, and version — the Component Model's equivalent of a package identifier. It scopes the interface names so they don't collide with interfaces from other packages, and it's what tooling uses to refer to this component as a dependency.
+Both `encode` and `decode` take a `port-map` — a list of named byte buffers — and return a `port-map` on success or a human-readable error string on failure.
+
+This codec expects three input ports:
 
-The `world` declares what this component exposes to the outside world. `export codec` means any host that loads this component can call the functions in the `codec` interface.
+- **`bytes`** — the raw pixel data
+- **`bytes_per_sample`** — UTF-8 digit string (`"1"`, `"2"`, or `"4"`)
+- **`width`** — UTF-8 digit string (e.g. `"256"`)
 
-Both `encode` and `decode` take a byte array of pixel data and a JSON config string with `bytes_per_sample` and `width` keys, e.g. `{"bytes_per_sample": 2, "width": 256}`. Both also return a WIT [`result`](https://component-model.bytecodealliance.org/design/wit.html#results) — WIT's typed success-or-failure type, similar to Rust's `Result` or a checked exception in other languages. The two type parameters are the success type and the error type:
+It returns one output port:
 
-- **`list<u8>`** (success) — WIT's byte array; contains the encoded or decoded bytes
-- **`string`** (failure) — a human-readable error message, e.g. for an invalid or missing config key
+- **`bytes`** — the encoded or decoded pixel data
 
 ## Prerequisites
 
@@ -49,7 +55,7 @@ Both `encode` and `decode` take a byte array of pixel data and a JSON config str
 uv sync
 uv run componentize-py \
     --wit-path wit \
-    --world tiff-predictor-2-python \
+    --world codec \
     componentize -p src app \
     -o tiff-predictor-2-python.wasm
 ```

src/app.py

@@ -1,6 +1,6 @@
 """componentize-py entry point.
 
-Bridges the WIT-generated Codec protocol to the pure-Python implementation
+Bridges the WIT-generated Transform protocol to the pure-Python implementation
 in tiff_predictor_2.py.
 """
 
@@ -9,15 +9,36 @@
 import tiff_predictor_2
 
 
-class Codec:
-    def encode(self, data: bytes, config: str) -> bytes:
+class Transform:
+    def encode(self, inputs: list[tuple[str, bytes]]) -> list[tuple[str, bytes]]:
         try:
-            return tiff_predictor_2.encode(data, config)
+            data, bps, width = _unpack_inputs(inputs)
+            result = tiff_predictor_2.encode(data, bps, width)
+            return [("bytes", result)]
         except ValueError as e:
             raise Err(str(e)) from e
 
-    def decode(self, data: bytes, config: str) -> bytes:
+    def decode(self, inputs: list[tuple[str, bytes]]) -> list[tuple[str, bytes]]:
         try:
-            return tiff_predictor_2.decode(data, config)
+            data, bps, width = _unpack_inputs(inputs)
+            result = tiff_predictor_2.decode(data, bps, width)
+            return [("bytes", result)]
         except ValueError as e:
             raise Err(str(e)) from e
+
+
+def _unpack_inputs(inputs: list[tuple[str, bytes]]) -> tuple[bytes, int, int]:
+    """Extract and parse the three required ports from a port-map."""
+    ports = dict(inputs)
+    data = _require_port(ports, "bytes")
+    bps = int(_require_port(ports, "bytes_per_sample").decode())
+    width = int(_require_port(ports, "width").decode())
+    return data, bps, width
+
+
+def _require_port(ports: dict[str, bytes], name: str) -> bytes:
+    """Look up a port by name, raising ValueError if missing."""
+    if name not in ports:
+        msg = f"missing required port: {name}"
+        raise ValueError(msg)
+    return ports[name]

src/tiff_predictor_2.py

@@ -6,15 +6,15 @@
 """
 
 import array
-import json
 
 # bytes-per-sample -> array typecode (unsigned integers)
 _TYPECODES: dict[int, str] = {1: "B", 2: "H", 4: "I"}
 
 
-def decode(data: bytes, config: str) -> bytes:
+def decode(data: bytes, bps: int, width: int) -> bytes:
     """Undo horizontal differencing via cumulative sum per row."""
-    bps, width, height = _parse_config(config, len(data))
+    _validate(bps, width)
+    height = len(data) // (width * bps)
     mask = (1 << (bps * 8)) - 1
 
     arr = array.array(_TYPECODES[bps], data)
@@ -26,12 +26,13 @@ def decode(data: bytes, config: str) -> bytes:
     return arr.tobytes()
 
 
-def encode(data: bytes, config: str) -> bytes:
+def encode(data: bytes, bps: int, width: int) -> bytes:
     """Apply horizontal differencing (row-wise differences).
 
     Iterates backwards so each subtraction reads the original predecessor.
     """
-    bps, width, height = _parse_config(config, len(data))
+    _validate(bps, width)
+    height = len(data) // (width * bps)
     mask = (1 << (bps * 8)) - 1
 
     arr = array.array(_TYPECODES[bps], data)
@@ -43,21 +44,11 @@ def encode(data: bytes, config: str) -> bytes:
     return arr.tobytes()
 
 
-def _parse_config(config: str, data_len: int) -> tuple[int, int, int]:
-    """Parse JSON config and return (bps, width, height).
-
-    Raises ValueError for invalid or missing parameters.
-    """
-    cfg = json.loads(config)
-    bps = cfg.get("bytes_per_sample", 0)
-    width = cfg.get("width", 0)
-
+def _validate(bps: int, width: int) -> None:
+    """Validate parameters. Raises ValueError for invalid values."""
     if bps not in _TYPECODES:
         msg = f"unsupported bytes_per_sample: {bps}"
         raise ValueError(msg)
     if width <= 0:
         msg = f"invalid width: {width}"
         raise ValueError(msg)
-
-    height = data_len // (width * bps)
-    return bps, width, height

tests/test_tiff_predictor_2.py

@@ -1,22 +1,17 @@
 """Tests for tiff_predictor_2.py
 
 Ported from tiff-predictor-2-c/test_tiff_predictor_2.c.  The Python tests
-call encode()/decode() with bytes + JSON config (the public API), rather
+call encode()/decode() with bytes + parameters (the public API), rather
 than testing internal helpers directly.
 """
 
 import array
-import json
 
 import pytest
 
 from tiff_predictor_2 import decode, encode
 
 
-def _config(bps: int, width: int) -> str:
-    return json.dumps({"bytes_per_sample": bps, "width": width})
-
-
 def _to_bytes(typecode: str, values: list[int]) -> bytes:
     """Convert a list of integers to bytes via array.array (native byte order)."""
     return array.array(typecode, values).tobytes()
@@ -30,37 +25,37 @@ def test_bps1(self) -> None:
         """[10, 5, 3, 1] -> [10, 15, 18, 19]"""
         data = _to_bytes("B", [10, 5, 3, 1])
         expected = _to_bytes("B", [10, 15, 18, 19])
-        assert decode(data, _config(1, 4)) == expected
+        assert decode(data, 1, 4) == expected
 
     def test_bps1_wrapping(self) -> None:
         """200 + 100 = 300, mod 256 = 44."""
         data = _to_bytes("B", [200, 100])
-        result = array.array("B", decode(data, _config(1, 2)))
+        result = array.array("B", decode(data, 1, 2))
         assert result[0] == 200
         assert result[1] == (200 + 100) % 256
 
     def test_bps2(self) -> None:
         """[1000, 500, 200] -> [1000, 1500, 1700]"""
         data = _to_bytes("H", [1000, 500, 200])
         expected = _to_bytes("H", [1000, 1500, 1700])
-        assert decode(data, _config(2, 3)) == expected
+        assert decode(data, 2, 3) == expected
 
     def test_bps4(self) -> None:
         """[100000, 50000, 25000] -> [100000, 150000, 175000]"""
         data = _to_bytes("I", [100000, 50000, 25000])
         expected = _to_bytes("I", [100000, 150000, 175000])
-        assert decode(data, _config(4, 3)) == expected
+        assert decode(data, 4, 3) == expected
 
     def test_multirow(self) -> None:
         """2 rows, width=3, bps=1 — rows decoded independently."""
         data = _to_bytes("B", [10, 5, 3, 20, 2, 1])
         expected = _to_bytes("B", [10, 15, 18, 20, 22, 23])
-        assert decode(data, _config(1, 3)) == expected
+        assert decode(data, 1, 3) == expected
 
     def test_single_column(self) -> None:
         """width=1: nothing to accumulate, buffer unchanged."""
         data = _to_bytes("B", [42, 99])
-        assert decode(data, _config(1, 1)) == data
+        assert decode(data, 1, 1) == data
 
 
 # ---- encode tests -----------------------------------------------------------
@@ -71,37 +66,37 @@ def test_bps1(self) -> None:
         """[10, 15, 18, 19] -> [10, 5, 3, 1]"""
         data = _to_bytes("B", [10, 15, 18, 19])
         expected = _to_bytes("B", [10, 5, 3, 1])
-        assert encode(data, _config(1, 4)) == expected
+        assert encode(data, 1, 4) == expected
 
     def test_bps1_wrapping(self) -> None:
         """44 - 200 = -156, mod 256 = 100."""
         data = _to_bytes("B", [200, 44])
-        result = array.array("B", encode(data, _config(1, 2)))
+        result = array.array("B", encode(data, 1, 2))
         assert result[0] == 200
         assert result[1] == (44 - 200) % 256
 
     def test_bps2(self) -> None:
         """[1000, 1500, 1700] -> [1000, 500, 200]"""
         data = _to_bytes("H", [1000, 1500, 1700])
         expected = _to_bytes("H", [1000, 500, 200])
-        assert encode(data, _config(2, 3)) == expected
+        assert encode(data, 2, 3) == expected
 
     def test_bps4(self) -> None:
         """[100000, 150000, 175000] -> [100000, 50000, 25000]"""
         data = _to_bytes("I", [100000, 150000, 175000])
         expected = _to_bytes("I", [100000, 50000, 25000])
-        assert encode(data, _config(4, 3)) == expected
+        assert encode(data, 4, 3) == expected
 
     def test_multirow(self) -> None:
         """2 rows, width=3, bps=1 — rows encoded independently."""
         data = _to_bytes("B", [10, 15, 18, 20, 22, 23])
         expected = _to_bytes("B", [10, 5, 3, 20, 2, 1])
-        assert encode(data, _config(1, 3)) == expected
+        assert encode(data, 1, 3) == expected
 
     def test_single_column(self) -> None:
         """width=1: nothing to difference, buffer unchanged."""
         data = _to_bytes("B", [42, 99])
-        assert encode(data, _config(1, 1)) == data
+        assert encode(data, 1, 1) == data
 
 
 # ---- roundtrip tests --------------------------------------------------------
@@ -110,13 +105,11 @@ def test_single_column(self) -> None:
 class TestRoundtrip:
     def test_encode_then_decode(self) -> None:
         original = _to_bytes("H", [1000, 1500, 1700, 2000, 2100, 2300])
-        cfg = _config(2, 3)
-        assert decode(encode(original, cfg), cfg) == original
+        assert decode(encode(original, 2, 3), 2, 3) == original
 
     def test_decode_then_encode(self) -> None:
         original = _to_bytes("H", [1000, 1500, 1700, 2000, 2100, 2300])
-        cfg = _config(2, 3)
-        assert encode(decode(original, cfg), cfg) == original
+        assert encode(decode(original, 2, 3), 2, 3) == original
 
 
 # ---- invalid config tests ---------------------------------------------------
@@ -125,24 +118,16 @@ def test_decode_then_encode(self) -> None:
 class TestInvalidConfig:
     def test_decode_bps_zero(self) -> None:
         with pytest.raises(ValueError, match="bytes_per_sample"):
-            decode(b"\x01\x02\x03\x04", _config(0, 4))
+            decode(b"\x01\x02\x03\x04", 0, 4)
 
     def test_decode_width_zero(self) -> None:
         with pytest.raises(ValueError, match="width"):
-            decode(b"\x01\x02\x03\x04", _config(1, 0))
-
-    def test_decode_empty_config(self) -> None:
-        with pytest.raises(ValueError, match="bytes_per_sample"):
-            decode(b"\x01\x02\x03\x04", "{}")
+            decode(b"\x01\x02\x03\x04", 1, 0)
 
     def test_encode_bps_zero(self) -> None:
         with pytest.raises(ValueError, match="bytes_per_sample"):
-            encode(b"\x01\x02\x03\x04", _config(0, 4))
+            encode(b"\x01\x02\x03\x04", 0, 4)
 
     def test_encode_width_zero(self) -> None:
         with pytest.raises(ValueError, match="width"):
-            encode(b"\x01\x02\x03\x04", _config(1, 0))
-
-    def test_encode_empty_config(self) -> None:
-        with pytest.raises(ValueError, match="bytes_per_sample"):
-            encode(b"\x01\x02\x03\x04", "{}")
+            encode(b"\x01\x02\x03\x04", 1, 0)

wit/codec.wit

@@ -0,0 +1,14 @@
+package chonkle:codec@0.1.0;
+
+interface transform {
+    /// A named byte buffer — one port in the port map.
+    type port-name = string;
+    type port-map = list<tuple<port-name, list<u8>>>;
+
+    encode: func(inputs: port-map) -> result<port-map, string>;
+    decode: func(inputs: port-map) -> result<port-map, string>;
+}
+
+world codec {
+    export transform;
+}