Add per-connector / per-cable tweak with name placeholder (port of upstream PR wireviz#357)

Connectors and cables can now carry their own ``tweak:`` block with the
same ``override`` / ``append`` shape as the global one. The harness
folds per-node tweaks into the global tweak at instantiation, with an
optional placeholder substring rewritten to the node's actual
designator — making it practical to author a single tweak template and
apply it to many components.

Example:

    tweak:
      placeholder: "@@"

    connectors:
      X1:
        pinlabels: [A, B]
        tweak:
          append:
            - "@@_extra [color=red, style=dashed];"

renders X1's per-node tweak as ``X1_extra [color=red, style=dashed];``
in the .gv source. The same connector definition reused for X2 would
produce ``X2_extra ...``.

Placeholder semantics:
* Per-node ``tweak.placeholder`` overrides the global ``tweak.placeholder``.
* An empty string at the per-node level explicitly opts out of
  substitution for that node.
* ``None`` (the default) falls back to the global placeholder.
* When neither is set, no substitution happens — bare strings are
  appended/overridden as-written.

Implementation:

* DataClasses.py — ``Tweak`` gains ``placeholder: Optional[str] = None``.
  ``Connector`` and ``Cable`` gain ``tweak: Optional[Tweak] = None``,
  with ``__post_init__`` coercing a dict literal into a Tweak instance.
* Harness.py — new ``Harness._extend_tweak(node)`` method, called from
  ``add_connector()`` and ``add_cable()``, performs the placeholder
  substitution and merges into ``self.tweak``. Raises ``ValueError`` if
  two nodes contribute conflicting overrides for the same key.
* docs/syntax.md — documents per-connector / per-cable tweak fields and
  the new placeholder semantics.

Adapted from wireviz#357 (originally by
@kvid, targeting upstream ``dev``). Renamed ``extend_tweak`` to
``_extend_tweak`` to mark it private; otherwise faithful to the
original logic. ``make_list`` is already in master's wv_bom so no
helper backport needed.

Verified:
* Smoke test with placeholder ``@@`` and per-connector + per-cable
  ``append:`` blocks produces ``X1_extra``, ``W1_label``,
  ``cable W1`` in the rendered .gv (the @@'s are substituted).
* build_examples.py: deterministic outputs (.gv, .bom.tsv) byte-
  identical to baseline (no existing example uses the new syntax, so
  no new substitutions fire).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: SomethingNew71

docs/syntax.md

@@ -85,6 +85,9 @@ tweak:  # optional tweaking of .gv output
   # loops
   loops: <List>  # every list item is itself a list of exactly two pins
                  # on the connector that are to be shorted
+
+  # optional tweaking of .gv output executed for each instance of this connector
+  tweak:  # see tweak section below
 ```
 
 ## Cable attributes
@@ -148,6 +151,8 @@ tweak:  # optional tweaking of .gv output
   show_wirecount: <bool>    # defaults to true
   show_wirenumbers: <bool>  # defaults to true for cables; false for bundles
 
+  # optional tweaking of .gv output executed for each instance of this cable
+  tweak:  # see tweak section below
 ```
 
 ## Connection sets
@@ -457,6 +462,12 @@ Alternatively items can be added to just the BOM by putting them in the section
   # This feature is experimental and might change
   # or be removed in future versions.
 
+  placeholder: <str>  # Substring to be replaced with the node name in
+    # any per-connector / per-cable tweak overrides and append entries.
+    # An empty string disables placeholder substitution for that node.
+    # When omitted at the per-node level, the global placeholder
+    # (in the top-level tweak: section) is used as the fallback.
+
   override:  # dict of .gv entries to override
     # Each entry is identified by its leading string
     # in lines beginning with a TAB character.

src/wireviz/DataClasses.py

@@ -79,6 +79,7 @@ def __post_init__(self):
 
 @dataclass
 class Tweak:
+    placeholder: Optional[PlainText] = None
     override: Optional[Dict[Designator, Dict[str, Optional[str]]]] = None
     append: Union[str, List[str], None] = None
 
@@ -170,10 +171,13 @@ class Connector:
     loops: List[List[Pin]] = field(default_factory=list)
     ignore_in_bom: bool = False
     additional_components: List[AdditionalComponent] = field(default_factory=list)
+    tweak: Optional[Tweak] = None
 
     def __post_init__(self) -> None:
         if isinstance(self.image, dict):
             self.image = Image(**self.image)
+        if isinstance(self.tweak, dict):
+            self.tweak = Tweak(**self.tweak)
 
         self.ports_left = False
         self.ports_right = False
@@ -335,10 +339,13 @@ class Cable:
     show_wirenumbers: Optional[bool] = None
     ignore_in_bom: bool = False
     additional_components: List[AdditionalComponent] = field(default_factory=list)
+    tweak: Optional[Tweak] = None
 
     def __post_init__(self) -> None:
         if isinstance(self.image, dict):
             self.image = Image(**self.image)
+        if isinstance(self.tweak, dict):
+            self.tweak = Tweak(**self.tweak)
 
         if isinstance(self.gauge, str):  # gauge and unit specified
             try:

src/wireviz/Harness.py

@@ -30,6 +30,7 @@
     component_table_entry,
     generate_bom,
     get_additional_component_table,
+    make_list,
     pn_info_string,
 )
 from wireviz.wv_colors import get_color_hex, translate_color
@@ -84,9 +85,49 @@ def __post_init__(self):
     def add_connector(self, name: str, *args, **kwargs) -> None:
         check_old(f"Connector '{name}'", OLD_CONNECTOR_ATTR, kwargs)
         self.connectors[name] = Connector(name, *args, **kwargs)
+        self._extend_tweak(self.connectors[name])
 
     def add_cable(self, name: str, *args, **kwargs) -> None:
         self.cables[name] = Cable(name, *args, **kwargs)
+        self._extend_tweak(self.cables[name])
+
+    def _extend_tweak(self, node: Union[Connector, Cable]) -> None:
+        """Fold ``node.tweak`` into ``self.tweak`` after substituting the
+        node's name for the placeholder string.
+
+        Per-connector / per-cable ``tweak:`` entries let users author a
+        single template and have its ``override`` keys / ``append`` lines
+        rewritten with the actual designator at instantiation time. This
+        is the only place the placeholder substitution happens — the
+        global tweak is applied unchanged at graph emission time.
+        """
+        if not node.tweak:
+            return
+        ph = node.tweak.placeholder
+        # An empty string is a legal value to opt out of the global
+        # placeholder; only None falls back.
+        if ph is None:
+            ph = self.tweak.placeholder
+        rph = (lambda s: s.replace(ph, node.name)) if ph else (lambda s: s)
+
+        n_override = node.tweak.override or {}
+        s_override = self.tweak.override or {}
+        for ident, n_dict in n_override.items():
+            ident = rph(ident)
+            s_dict = s_override.get(ident, {})
+            for k, v in n_dict.items():
+                k, v = rph(k), rph(v)
+                if k in s_dict and v != s_dict[k]:
+                    raise ValueError(
+                        f"{node.name}.tweak.override.{ident}.{k} conflicts with another"
+                    )
+                s_dict[k] = v
+            s_override[ident] = s_dict or None
+        self.tweak.override = s_override or None
+        self.tweak.append = (
+            make_list(self.tweak.append)
+            + [rph(v) for v in make_list(node.tweak.append)]
+        ) or None
 
     def add_mate_pin(self, from_name, from_pin, to_name, to_pin, arrow_type) -> None:
         self.mates.append(MatePin(from_name, from_pin, to_name, to_pin, arrow_type))