haybale-protokol-osc 0.0.3__tar.gz

haybale_protokol_osc-0.0.3/.gitignore

@@ -0,0 +1,42 @@
+# Patterns below are anchored with a leading slash (/build/) so they match only
+# at the repo root. An unanchored pattern (build/) matches at EVERY depth —
+# including inside barn/, where it would silently exclude your library's own
+# files. See the note at the end of this file before adding patterns.
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging (root only)
+/build/
+/dist/
+*.egg-info/
+*.egg
+
+# Virtual environments (root only)
+/.venv/
+/venv/
+/env/
+
+# Test / type-check caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+.coverage
+htmlcov/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Haywire per-session UI state (open graph, pan/zoom) — not project state
+.haywire/workspace_state.json
+
+# ── Before you add a pattern ────────────────────────────────────────────────
+# Anything ignored inside barn/<your-library>/ will be MISSING for everyone who
+# installs your library — haywire share publishes by git URL, so consumers get
+# a clone of this repo, not a built package. If a pattern is only meant for the
+# repo root, anchor it with a leading slash: /build/ not build/.

haybale_protokol_osc-0.0.3/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.5
+Name: haybale-protokol-osc
+Version: 0.0.3
+Summary: OSC for haybale-protokol: UDP and TCP gates, OSC Receive and Send nodes
+Project-URL: Source, https://github.com/going-haywire/haybale-protokol
+License: MIT
+Keywords: control,network,osc,protocol
+Requires-Python: >=3.12
+Requires-Dist: haybale-core>=0.4.2
+Requires-Dist: haybale-protokol
+Requires-Dist: haywire-core>=0.5.0
+Requires-Dist: python-osc==1.10.2

haybale_protokol_osc-0.0.3/README.md

@@ -0,0 +1,75 @@
+# Protokol OSC
+
+# Protokol OSC
+
+OSC over UDP and TCP for Haywire, on top of `haybale-protokol`: an OSC Receive node and an OSC Send
+node, each using a gate from the project's `.haywire/protokol.toml` (see the Protokol notes
+for the file format).
+
+## TCP
+
+A TCP gate is a client (`role = "client"`, connects to `host`) or a server
+(`role = "server"`, accepts any number of peers on `bind`). Choose the framing your peer
+speaks: `framing = "1.0"` (length prefix) or `"1.1"` (SLIP, the default). A client keeps
+reconnecting (0.5 s, 1 s, 2 s, 4 s, then every 5 s) and shows `reconnecting (n)`; anything sent
+while it is disconnected is dropped and counted, never queued. A server sends each message to
+all its peers. TCP gates may be `two-way`, so one gate can feed an OSC Receive and an OSC Send.
+
+A peer that disappears without closing (power cut, lost Wi-Fi) is noticed by TCP keepalive
+after about 11 s; a client then reconnects. A peer that stops reading is disconnected once
+it holds up a send for 0.2 s, rather than slowing the graph down.
+
+## Gates on a node
+
+A node's **Gate** setting takes one or more gates. Pick them as chips from the list, which
+offers this project's OSC gates that fit the node (input or two-way for Receive, output or
+two-way for Send), or type a name and press Enter. OSC Receive listens on every listed gate;
+its **From gate** outlet says where a message came in. OSC Send sends each message to every
+listed gate. A listed gate that cannot be used is reported in `status`; the others still work.
+
+## OSC Receive
+
+Runs its flow for each message on its input gate whose address matches **Address**, an OSC
+address pattern (`*`, `?`, `[0-9]`, `{a,b}`; empty takes everything). Each wildcard gets a
+`match_N` outlet, which takes the type of whatever you connect it to.
+
+**Arg Shape** lists the arguments: OSC type tags (`i f d h s b T r`), groupings
+`vi2`–`vi4`, `vf2`–`vf4`, `m3`, `m4` for vectors and matrices, and `_` / `_n` to skip
+arguments. The `args` outlet always carries every argument as a list; each token adds its own outlet. A message that does not fit is skipped and counted
+in `status`. By default the node fires once at start with the last message the gate saw
+(**Start Value**) and keeps only the newest message when its flow runs behind.
+
+## OSC Send
+
+Sends **Address** with one argument per inlet, in inlet order. Connect anything to the empty
+inlet to add an argument. Vectors go out as their components (`vf3` → three `f`). Use `d` or
+`h` in the shape for 64-bit numbers. An int that does not fit a 32-bit `i` is dropped, and
+`status` says which argument it was. Each control tick sends, unless the **Only send changes** setting is on: then
+a tick sends only when the address, type tags or values differ from the last message sent.
+
+The Arg shape and the pins follow each other: typing the shape rebuilds the pins, and
+growing, unplugging (a grown pin) or reordering pins rewrites the shape.
+
+<!-- marketstall:share-url:start -->
+Always the latest (tracks the current branch):
+
+```sh
+https://github.com/going-haywire/haybale-protokol/blob/master/marketstall.toml
+```
+
+Frozen to this version:
+
+```sh
+https://github.com/going-haywire/haybale-protokol/blob/v0.0.3/marketstall.toml
+```
+<!-- marketstall:share-url:end -->
+
+OSC for haybale-protokol: UDP and TCP gates, OSC Receive and Send nodes
+
+## Nodes
+### Protokol
+- **OSC Receive** — Triggered for each OSC message on an input gate that matches the address pattern
+- **OSC Send** — Sends one OSC message to an output gate each time it runs
+
+## States
+- **Protokol OSC** — Registers the OSC driver with Protokol

haybale_protokol_osc-0.0.3/haybale_protokol_osc/NOTES.md

@@ -0,0 +1,49 @@
+# Protokol OSC
+
+OSC over UDP and TCP for Haywire, on top of `haybale-protokol`: an OSC Receive node and an OSC Send
+node, each using a gate from the project's `.haywire/protokol.toml` (see the Protokol notes
+for the file format).
+
+## TCP
+
+A TCP gate is a client (`role = "client"`, connects to `host`) or a server
+(`role = "server"`, accepts any number of peers on `bind`). Choose the framing your peer
+speaks: `framing = "1.0"` (length prefix) or `"1.1"` (SLIP, the default). A client keeps
+reconnecting (0.5 s, 1 s, 2 s, 4 s, then every 5 s) and shows `reconnecting (n)`; anything sent
+while it is disconnected is dropped and counted, never queued. A server sends each message to
+all its peers. TCP gates may be `two-way`, so one gate can feed an OSC Receive and an OSC Send.
+
+A peer that disappears without closing (power cut, lost Wi-Fi) is noticed by TCP keepalive
+after about 11 s; a client then reconnects. A peer that stops reading is disconnected once
+it holds up a send for 0.2 s, rather than slowing the graph down.
+
+## Gates on a node
+
+A node's **Gate** setting takes one or more gates. Pick them as chips from the list, which
+offers this project's OSC gates that fit the node (input or two-way for Receive, output or
+two-way for Send), or type a name and press Enter. OSC Receive listens on every listed gate;
+its **From gate** outlet says where a message came in. OSC Send sends each message to every
+listed gate. A listed gate that cannot be used is reported in `status`; the others still work.
+
+## OSC Receive
+
+Runs its flow for each message on its input gate whose address matches **Address**, an OSC
+address pattern (`*`, `?`, `[0-9]`, `{a,b}`; empty takes everything). Each wildcard gets a
+`match_N` outlet, which takes the type of whatever you connect it to.
+
+**Arg Shape** lists the arguments: OSC type tags (`i f d h s b T r`), groupings
+`vi2`–`vi4`, `vf2`–`vf4`, `m3`, `m4` for vectors and matrices, and `_` / `_n` to skip
+arguments. The `args` outlet always carries every argument as a list; each token adds its own outlet. A message that does not fit is skipped and counted
+in `status`. By default the node fires once at start with the last message the gate saw
+(**Start Value**) and keeps only the newest message when its flow runs behind.
+
+## OSC Send
+
+Sends **Address** with one argument per inlet, in inlet order. Connect anything to the empty
+inlet to add an argument. Vectors go out as their components (`vf3` → three `f`). Use `d` or
+`h` in the shape for 64-bit numbers. An int that does not fit a 32-bit `i` is dropped, and
+`status` says which argument it was. Each control tick sends, unless the **Only send changes** setting is on: then
+a tick sends only when the address, type tags or values differ from the last message sent.
+
+The Arg shape and the pins follow each other: typing the shape rebuilds the pins, and
+growing, unplugging (a grown pin) or reordering pins rewrites the shape.

haybale_protokol_osc-0.0.3/haybale_protokol_osc/OVERVIEW.md

@@ -0,0 +1,11 @@
+# Protokol OSC
+
+OSC for haybale-protokol: UDP and TCP gates, OSC Receive and Send nodes
+
+## Nodes
+### Protokol
+- **OSC Receive** — Triggered for each OSC message on an input gate that matches the address pattern
+- **OSC Send** — Sends one OSC message to an output gate each time it runs
+
+## States
+- **Protokol OSC** — Registers the OSC driver with Protokol

haybale_protokol_osc-0.0.3/haybale_protokol_osc/QUICKREF.md

@@ -0,0 +1,8 @@
+# haybale-protokol-osc — component index (v0.0.3)
+
+## node
+- `haybale-protokol-osc:node:OscReceiveNode` — OSC Receive — Triggered for each OSC message on an input gate that matches the address pattern  _tags: osc, receive, control, network, protokol, touchosc_
+- `haybale-protokol-osc:node:OscSendNode` — OSC Send — Sends one OSC message to an output gate each time it runs  _tags: osc, send, control, network, protokol, touchosc_
+
+## state
+- `haybale-protokol-osc:state:OscState` — Protokol OSC — Registers the OSC driver with Protokol

haybale_protokol_osc-0.0.3/haybale_protokol_osc/__init__.py

@@ -0,0 +1,103 @@
+"""
+OSC for haybale-protokol: the OSC Protocol driver and the OSC Receive and Send nodes.
+
+Add your custom components in the corresponding folders:
+- nodes/      — node definitions
+- macros/     — macro documents (.hwm)
+- types/      — custom data types
+- widgets/    — UI widgets for data types
+- skins/      — custom node skins
+- adapters/   — type-to-type conversion adapters
+- settings/   — library settings definitions
+- states/     — library app and session states
+- themes/     — workbench and node themes
+- panels/     — custom UI panels
+- editors/    — custom UI editors
+"""
+
+from pathlib import Path
+
+from haywire.api import (
+    AdapterRegistry,
+    BaseLibrary,
+    MacroRegistry,
+    NodeRegistry,
+    SettingsRegistry,
+    SkinRegistry,
+    ThemeRegistry,
+    TypeRegistry,
+    WidgetRegistry,
+    library,
+)
+
+from haywire.api.workbench import EditorRegistry, PanelRegistry, StateRegistry
+
+
+@library(
+    file_watcher=True,
+)
+class Library(BaseLibrary):
+    """OSC over UDP for haybale-protokol."""
+
+    def register_components(self):
+        """Register all components with the global registries."""
+        base_path = Path(__file__).parent
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "settings"),
+            registry_cls=SettingsRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "states"),
+            registry_cls=StateRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "themes"),
+            registry_cls=ThemeRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "types"),
+            registry_cls=TypeRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "adapters"),
+            registry_cls=AdapterRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "widgets"),
+            registry_cls=WidgetRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "skins"),
+            registry_cls=SkinRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "nodes"),
+            registry_cls=NodeRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "macros"),
+            registry_cls=MacroRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "panels"),
+            registry_cls=PanelRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "editors"),
+            registry_cls=EditorRegistry,
+        )
+
+    def validate(self) -> bool:
+        """Validate library structure."""
+        return True

haybale_protokol_osc-0.0.3/haybale_protokol_osc/arg_pins.py

@@ -0,0 +1,241 @@
+"""Argument pins that follow the Arg shape, shared by OSC Receive and OSC Send.
+
+The Arg shape text is the source of truth. Each named token has a pin with a stable id
+(``arg_<n>``, numbers never reused, because an edge's id contains its port's id); the node
+store keeps the ids in shape order. The pin edits a user makes rewrite the text:
+
+- connecting the empty ``ADD`` slot appends the edge type's token (undo takes it back);
+- deleting the edge that grew a pin removes the pin and its token (typed pins stay);
+- reordering pins reorders the tokens; ``_`` skips stay where they are.
+
+Every rewrite goes through the ``arg_shape`` port, whose ``on_change`` rebuilds the pins,
+inside the user's one action, so each edit is one undo step.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from haywire.api import ADD, PortOrigin
+
+from haybale_protokol_osc.shape import ShapeError, Token, parse_shape, token_for_type
+
+ARG_ID = re.compile(r"arg_(\d+)")
+
+
+class ArgPins:
+    """Mixin for a ``BaseNode`` with an ``arg_shape`` config port and ``arg_<n>`` pins."""
+
+    #: True for Receive (outlets, ``_`` allowed), False for Send (inlets).
+    receive: bool = False
+
+    # Provided by BaseNode (the mixin comes first in the bases, so it defines no stubs).
+    ports: dict[str, Any]
+    store: Any
+    value: Any
+    add: Any
+    post_value: Any
+
+    # -- the node supplies --------------------------------------------------------
+
+    def _arg_spec(self, port_id: str, type_cls: Any, origin: PortOrigin, label: str) -> Any:
+        """The inlet or outlet spec of one argument pin."""
+        raise NotImplementedError
+
+    # -- reading ------------------------------------------------------------------
+
+    def _tokens(self) -> list[Token]:
+        """The current Arg shape; raises ``ShapeError`` when the text is invalid."""
+        return parse_shape(str(self.value("arg_shape") or ""), receive=self.receive)
+
+    def _arg_ids(self) -> list[str]:
+        return list(getattr(self.store, "arg_ids", []))
+
+    def _slot_id(self) -> str:
+        return str(getattr(self.store, "arg_slot", "arg_1"))
+
+    def _arg_ports(self) -> list[Any]:
+        """The typed argument pins, in shape order."""
+        return [self.ports[port_id] for port_id in self._arg_ids() if port_id in self.ports]
+
+    def _pins_mismatch(self) -> str | None:
+        """Why the argument pins no longer match the Arg shape (a pin removed from its menu), or ``None``."""
+        try:
+            named = [token for token in self._tokens() if token.haywire_type is not None]
+        except ShapeError as exc:
+            return f"Arg shape: {exc}"
+        if len(self._arg_ports()) != len(named):
+            return "pins and Arg shape differ: retype the Arg shape"
+        return None
+
+    # -- building -----------------------------------------------------------------
+
+    def _add_arg_ports(self, tokens: list[Token]) -> None:
+        """Add one pin per named token, then the empty slot. Call inside the node's ``rejig``."""
+        import haywire.api as builtin
+
+        from haybale_core.types.specs import BYTES
+
+        named = [token for token in tokens if token.haywire_type is not None]
+        ids = self._arg_ids()[: len(named)]
+        slot = self._slot_id()
+        while len(ids) < len(named):
+            # The empty slot holds no edge (connecting grows it), so its id is free to take.
+            ids.append(slot if slot not in ids else self._new_arg_id(ids))
+        if slot in ids:
+            slot = self._new_arg_id(ids)
+        self.store.arg_ids = ids
+        self.store.arg_slot = slot
+        grown = getattr(self.store, "arg_grown", [])
+        self.store.arg_grown = [port_id for port_id in grown if port_id in ids]
+        for position, (port_id, token) in enumerate(zip(ids, named, strict=True), start=1):
+            name = str(token.haywire_type)
+            type_cls = BYTES if name == "BYTES" else getattr(builtin, name)
+            self.add(self._arg_spec(port_id, type_cls, PortOrigin.RESOLVED, f"{position}: {token.text}"))
+        self.add(self._arg_spec(slot, ADD, PortOrigin.DECLARED, "+"))
+
+    def _move_slot_last(self) -> None:
+        """Put the empty slot after every other port, so it is the last pin of its side."""
+        slot = self.ports.get(self._slot_id())
+        if slot is None:
+            return
+        others = [port.order for port in self.ports.values() if port is not slot]
+        if others and slot.order <= max(others):
+            slot.order = max(others) + 1
+            wrapper = getattr(self, "wrapper", None)
+            if wrapper is not None:
+                wrapper.mark_layout_changed()
+
+    def _new_arg_id(self, taken: list[str]) -> str:
+        used = [int(m.group(1)) for port_id in (*self.ports, *taken) if (m := ARG_ID.fullmatch(port_id))]
+        floor = int(getattr(self.store, "arg_next", 1))
+        number = max([floor - 1, *used]) + 1
+        self.store.arg_next = number + 1
+        return f"arg_{number}"
+
+    def _accept_text(self) -> None:
+        """Remember the current config texts as the last ones that applied."""
+        for port_id in ("address", "arg_shape"):
+            if port_id in self.ports:
+                setattr(self.store, f"good_{port_id}", str(self.value(port_id) or ""))
+
+    def _reject_text(self, port: Any, error: Exception) -> None:
+        """Put ``port`` back to its last applied text and say why the new one was refused."""
+        self._report(f"not applied: {error}")
+        good = str(getattr(self.store, f"good_{getattr(port, 'id', '')}", ""))
+        if getattr(port, "id", None) in ("address", "arg_shape") and self.value(port.id) != good:
+            port.set_value(good)
+
+    def _write_shape(self, tokens: list[Token]) -> None:
+        """Set the Arg shape text; its ``on_change`` rebuilds the pins."""
+        self.ports["arg_shape"].set_value(" ".join(token.text for token in tokens))
+
+    # -- pin edits ------------------------------------------------------------------
+
+    def hb_grow(self, port: Any, edge_wrapper: Any) -> None:
+        """An edge on the empty slot becomes an argument of the edge's type."""
+
+        if port.type_cls is None or not issubclass(port.type_cls, ADD) or port.id != self._slot_id():
+            return
+        other = edge_wrapper._outlet_port if port.is_inlet() else edge_wrapper._inlet_port
+        if other is None:
+            return
+        type_name = getattr(other.stored_type, "__name__", "")
+        text = token_for_type(type_name)
+        if text is None:
+            self._report(f"OSC cannot carry {type_name}")
+            return
+        try:
+            tokens = self._tokens()
+        except ShapeError as exc:
+            self._report(f"not applied: {exc}")
+            return
+        self.store.arg_ids = [*self._arg_ids(), port.id]
+        self.store.arg_grown = [*getattr(self.store, "arg_grown", []), port.id]
+        self.store.arg_slot = self._new_arg_id(self._arg_ids())
+        self._write_shape([*tokens, *parse_shape(text, receive=self.receive)])
+
+    def release_pins(self, port_ids: list[str]) -> list[str]:
+        """Remove the grown argument pins whose edge is gone, with their tokens."""
+        grown = list(getattr(self.store, "arg_grown", []))
+        candidates = [
+            port_id
+            for port_id in port_ids
+            if port_id in grown and port_id in self.ports and not self.ports[port_id].is_linked()
+        ]
+        if not candidates:
+            return []
+        try:
+            tokens = self._tokens()
+        except ShapeError:
+            return []
+        ids = self._arg_ids()
+        stash = dict(getattr(self.store, "arg_released", {}))
+        for port_id in candidates:
+            index = ids.index(port_id)
+            position = _named_positions(tokens)[index]
+            stash[port_id] = [index, position, tokens[position].text]
+            del tokens[position]
+            del ids[index]
+            grown.remove(port_id)
+        self.store.arg_released = stash
+        self.store.arg_ids = ids
+        self.store.arg_grown = grown
+        self._write_shape(tokens)
+        return candidates
+
+    def restore_pins(self, port_ids: list[str]) -> None:
+        """Bring back pins ``release_pins`` removed, at their places in the shape."""
+        stash = dict(getattr(self.store, "arg_released", {}))
+        try:
+            tokens = self._tokens()
+        except ShapeError:
+            return
+        ids = self._arg_ids()
+        grown = list(getattr(self.store, "arg_grown", []))
+        for port_id in reversed(port_ids):
+            if port_id not in stash:
+                continue
+            index, position, text = stash.pop(port_id)
+            tokens.insert(position, *parse_shape(text, receive=self.receive))
+            ids.insert(index, port_id)
+            grown.append(port_id)
+        self.store.arg_released = stash
+        self.store.arg_ids = ids
+        self.store.arg_grown = grown
+        self._write_shape(tokens)
+
+    def reorder_ports(self, ordered_ids: list[str]) -> None:
+        """Reorder pins as the base does, then reorder the Arg shape to match."""
+        super().reorder_ports(ordered_ids)  # type: ignore[misc]
+        try:
+            self._reorder_tokens()
+        finally:
+            self._move_slot_last()
+
+    def _reorder_tokens(self) -> None:
+        ids = self._arg_ids()
+        if any(port_id not in self.ports for port_id in ids):
+            return  # a pin was removed from its menu; the status guard reports it
+        new_ids = sorted(ids, key=lambda port_id: self.ports[port_id].order)
+        if new_ids == ids:
+            return
+        try:
+            tokens = self._tokens()
+        except ShapeError:
+            return
+        positions = _named_positions(tokens)
+        named = {port_id: tokens[position] for port_id, position in zip(ids, positions, strict=True)}
+        for position, port_id in zip(positions, new_ids, strict=True):
+            tokens[position] = named[port_id]
+        self.store.arg_ids = new_ids
+        self._write_shape(tokens)
+
+    def _report(self, text: str) -> None:
+        """Show ``text`` on the node's status outlet."""
+        self.post_value("status", text)
+
+
+def _named_positions(tokens: list[Token]) -> list[int]:
+    return [position for position, token in enumerate(tokens) if token.haywire_type is not None]

haybale_protokol_osc-0.0.3/haybale_protokol_osc/docs/haybale-protokol-osc.node.OscReceiveNode.md

@@ -0,0 +1,50 @@
+# OSC Receive
+
+`haybale-protokol-osc:node:OscReceiveNode` · kind: node
+
+Triggered for each OSC message on an input gate that matches the address pattern
+
+## Ports
+
+| id | direction | type | description |
+|---|---|---|---|
+| `gate` | config | `haywire-core:type:STRING` | One or more input (or two-way) gates from the project's Gate file, .haywire/protokol.toml; pick them from the list, which offers this project's OSC gates that can receive, or type a name and press Enter. Make gates in the Gates editor. The node opens each gate's Line when the graph starts and gives it back when it stops; messages from every gate run the same flow, and the From gate outlet says which one a message came in on. A gate that is missing, of another protocol or whose port is busy is reported in status; the others still work. A change applies on the next start. |
+| `address` | config | `haywire-core:type:STRING` | The OSC address pattern to listen to; empty takes every message on the gate. Wildcards: \* (any text within one /part), ? (one character), [0-9] or [!a] (one character from a set), {left,right} (one of the words). Each wildcard adds a capture outlet, match_1, match_2 … from left to right. A capture starts as an empty + pin and takes the type of the inlet you connect it to (text, int, float or bool); a part that does not convert is reported in status. Changing the pattern rebuilds the match_ outlets; an invalid pattern is put back. |
+| `arg_shape` | config | `haywire-core:type:STRING` | The Arg shape: the arguments the node expects, as tokens separated by spaces. i or h: int; f or d: float; s: text; b: blob; T: bool; r: colour; vi2–vi4 and vf2–vf4: 2 to 4 ints or floats as one vector; m3, m4: 9 or 16 floats as a matrix; _ skips one argument, _3 skips three. The args outlet always carries every argument as a list; each token adds its own outlet, in order. The shape and the pins follow each other: connecting the + pin at the bottom adds a token for the connected type, deleting the edge that grew a pin removes the pin and its token, and dragging pins into another order reorders the tokens. A message that does not fit is skipped and counted in status; extra arguments are ignored. An invalid shape is put back. |
+| `received` | outlet | `haywire-core:type:EXEC` | Signal for controlling execution flow between nodes |
+| `address_out` | outlet | `haywire-core:type:STRING` | Text data |
+| `from_gate` | outlet | `haywire-core:type:STRING` | The gate the message came in on |
+| `args` | outlet | `haybale-core:type:LIST` | Every argument of the message, as a list |
+| `arg_1` | outlet | `haywire-core:type:ADD` | Grows a new port from whatever connects to it |
+| `timetag` | outlet | `haywire-core:type:FLOAT` | Decimal number |
+| `status` | outlet | `haywire-core:type:STRING` | Text data |
+
+## Settings
+
+| name | bag | default | description |
+|---|---|---|---|
+| `queue_mode` | dispatch | `'Auto (by message kind)'` | Block runs the flow for every message; a slow flow then falls behind, never the Line. Drop keeps only the newest message. Auto uses Drop for values (faders, axes, OSC) and Block for events (notes, buttons). |
+| `max_queue_size` | dispatch | `100` | How many messages Block holds while the flow runs behind. Drop always holds one. |
+| `start_value` | dispatch | `'Auto (by message kind)'` | Fire once with the last message the Line saw when the graph starts. Auto: on for values, off for events. |
+
+## Notes
+
+Runs its flow for each OSC message on its gate that matches its address.
+
+`Gate` names an input gate in the project's Gate file (`.haywire/protokol.toml`). `Address`
+is an OSC address pattern (`*`, `?`, `[0-9]`, `{a,b}`); empty takes every message. Each
+wildcard gets a capture outlet, `match_1`, `match_2`..., which takes the type of what it is
+connected to. `args` always carries every argument as a list. `Arg Shape` lists the
+arguments (`f i vf3 s`, `_` to skip one), each token adding its own outlet. A message that
+does not fit the shape is skipped and counted in `status`.
+
+The outlets keep the latest values, so other flows can read them.
+
+Outputs:
+    received: Control flow for each matching message
+    address: The address that matched
+    args: Every argument, as a list
+    arg_N: One argument (or a group, such as a vector) per Arg Shape token
+    match_N: What each wildcard matched
+    timetag: The OSC bundle's timetag, 0 for a message outside a bundle
+    status: The gate's state and how many messages were skipped

haybale_protokol_osc-0.0.3/haybale_protokol_osc/docs/haybale-protokol-osc.node.OscSendNode.md

@@ -0,0 +1,38 @@
+# OSC Send
+
+`haybale-protokol-osc:node:OscSendNode` · kind: node
+
+Sends one OSC message to an output gate each time it runs
+
+## Ports
+
+| id | direction | type | description |
+|---|---|---|---|
+| `exec` | inlet | `haywire-core:type:EXEC` | Signal for controlling execution flow between nodes |
+| `address` | inlet | `haywire-core:type:STRING` | Text data |
+| `arg_1` | inlet | `haywire-core:type:ADD` | Grows a new port from whatever connects to it |
+| `gate` | config | `haywire-core:type:STRING` | One or more output (or two-way) gates from the project's Gate file, .haywire/protokol.toml; pick them from the list, which offers this project's OSC gates that can send, or type a name and press Enter. Make gates in the Gates editor. Each send goes to every listed gate. The node opens each gate's Line when the graph starts and gives it back when it stops. A gate that is missing, of another protocol or cannot reach its peer is reported in status and the others still get the message; a message no gate could take counts as dropped, never queued. A change applies on the next start. |
+| `arg_shape` | config | `haywire-core:type:STRING` | The Arg shape: one token per argument inlet, in inlet order. i: int; f: float; s: text; b: blob; T: bool; r: colour; vi2–vi4 and vf2–vf4: a vector, sent as its components; m3, m4: a matrix, sent as 9 or 16 floats. Use d or h instead of f or i for 64-bit numbers. There is no _: every inlet is sent, and an unconnected inlet sends its own value. Typing the shape rebuilds the inlets; connecting the + pin at the bottom adds a token for the connected type, deleting the edge that grew a pin removes the pin and its token, and dragging pins into another order reorders the tokens. An int too large for i is dropped and named in status; an invalid shape is put back. |
+| `next` | outlet | `haywire-core:type:EXEC` | Signal for controlling execution flow between nodes |
+| `shape` | outlet | `haywire-core:type:STRING` | Text data |
+| `status` | outlet | `haywire-core:type:STRING` | Text data |
+
+## Settings
+
+| name | bag | default | description |
+|---|---|---|---|
+| `only_changes` | sending | `False` | Off: every control tick sends the message. On: a tick sends only when the address, type tags or values differ from the last message sent; the first tick of a run always sends, and a dropped send is retried on the next tick. Skipped ticks are counted as 'unchanged' in status. |
+
+## Notes
+
+Sends `Address` with one argument per argument inlet, in inlet order, to its gate.
+
+`Gate` names an output gate in the project's Gate file. Connect anything to the empty
+inlet at the bottom to add an argument; `Arg Shape` lists the arguments (`f i vf3 s`) and
+follows the inlets. A vector goes out as its components (`vf3` → three `f`); use `d` or `h`
+in the shape for 64-bit numbers. An unconnected inlet sends its own value.
+
+Outputs:
+    next: Control flow after sending
+    shape: The OSC type tags sent last
+    status: What was sent and dropped, or why nothing can be sent

haybale_protokol_osc-0.0.3/haybale_protokol_osc/docs/haybale-protokol-osc.state.OscState.md

@@ -0,0 +1,9 @@
+# Protokol OSC
+
+`haybale-protokol-osc:state:OscState` · kind: state
+
+Registers the OSC driver with Protokol
+
+## Notes
+
+Hands ``OscDriver`` to ``ProtokolState`` on enable and takes it back on disable.