From 400e111f83b8b8bc465fa86730394bec1c295c00 Mon Sep 17 00:00:00 2001
From: Cole Gentry <peapod2007@gmail.com>
Date: Fri, 2 Oct 2026 16:03:20 -0400
Subject: [PATCH 01/11] =?UTF-8?q?docs(plans):=20batch=20C=20design=20?=
 =?UTF-8?q?=E2=80=94=20errors,=20wire=20count,=20include,=20twisted=20pair?=
 =?UTF-8?q?s,=20shorts,=20sheet=20PDF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/plans/2026-10-02-batch-c-design.md | 137 ++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 docs/plans/2026-10-02-batch-c-design.md

diff --git a/docs/plans/2026-10-02-batch-c-design.md b/docs/plans/2026-10-02-batch-c-design.md
new file mode 100644
index 00000000..d4a82836
--- /dev/null
+++ b/docs/plans/2026-10-02-batch-c-design.md
@@ -0,0 +1,137 @@
+# Batch C — larger upstream features (design)
+
+Date: 2026-10-02. Branch: `fix/upstream-batch-c`. Issues from
+[the upstream triage](2026-10-02-upstream-issue-triage.md). Decisions marked
+**Decided** were confirmed by Cole on 2026-10-02.
+
+Upstream `dev` implements none of these. Open upstream PRs (#382, #455,
+#506) are on `dev` or unreviewed, so only their ideas are used.
+
+Implementation order: C1 (#505, #508), C2 (#220), C3 (#3/#353), C4
+(#350), C5 (#32/#304). Each is one commit with tests in
+`tests/test_upstream_issues.py`.
+
+## C1a. Error messages (#505, #207)
+
+Stage 1 only.
+
+- New `wireviz.wv_errors.WireVizError(ValueError)`.
+- `parse()` wraps the processing of each connection set. An error is
+  re-raised with the prefix `connection set N (X1 → W1 → X2): `, and keeps
+  its class when it is a `ValueError` or `TypeError`; any other exception
+  becomes `WireVizError`. `raise ... from exc` keeps the cause.
+- The `style: simple` error names the connector.
+- CLI: `WireVizError`, `ValueError`, `TypeError`, `yaml.YAMLError` and
+  `FileNotFoundError` from `parse()` print one line through
+  `click.ClickException` (exit 1). New `--debug` flag re-raises for a
+  traceback.
+- Not now: YAML line numbers (stage 2, needs mark tracking in the loader).
+
+## C1b. Infer the wire count (#508)
+
+**Decided:** a bare named cable means wires 1..n.
+
+- A pre-pass in `parse()` over all connection sets, before components
+  are created. For each cable designator with no `wirecount` and no
+  `colors`, the implied wire count is the largest of: the integer wire
+  numbers used for it, and the connection count of any set where it
+  appears as a bare name.
+- A bare named cable (`- B1`, no template separator) in a set with n
+  parallel connections means wires 1..n (before: wire 1, n times). An
+  autogenerated cable (`- W.`) keeps its meaning: one new instance per
+  connection.
+- Color or label references cannot imply a count: the existing error
+  stays, with a better message.
+- CHANGELOG: list the bare-name change under "Behavior changes".
+
+## C2. Include files (#220)
+
+**Decided:** top-level `include:` list, merged at dict level.
+
+```yaml
+include:
+  - lib/connectors.yml
+  - lib/cables.yml
+connectors: ...
+```
+
+- Paths resolve against the including file's directory (or `source_path`
+  for str/dict input), then against `include_paths` (new `parse()`
+  argument, CLI `-I/--include-path`, repeatable).
+- Recursive. A cycle or a depth over 16 is an error naming the files.
+- Merge `connectors`, `cables` and `additional_bom_items` (list append)
+  from includes into the main data. The main file wins on a duplicate
+  key. The same key in two included files is an error naming both
+  files. `metadata`, `options`, `tweak` and `connections` come from the
+  main file only; in an included file they are an error (say so, do not
+  drop them silently).
+- `image.src` of an included component is made absolute against the
+  included file's directory before merging.
+- YAML anchors and `<<:` do not cross files: each file is parsed on its
+  own. Documented.
+- `untrusted=True` refuses `include` (it reads files).
+- PNG embedding stores the merged YAML, so a PNG is self-contained.
+- `--prepend` stays as it is, and is now documented in syntax.md.
+
+## C3. Twisted pairs (#3, #353)
+
+Syntax as kvid proposed in #353:
+
+```yaml
+cables:
+  W1:
+    colors: [RD, BK, WH, BU]
+    twisted: [[RD, BK], [WH, BU]]          # or wire numbers / wire labels
+    # optional rate:  twisted: [{wires: [1, 2], rate: 20/m}]
+```
+
+- Each group is 2 or more wires, referenced by number, color or wire
+  label (same resolution as connections). A wire in two groups, a group
+  under 2 wires, or an unknown wire is an error.
+- Rendering in the wire table: the rows of a group are made contiguous
+  (the group starts at the row of its first wire) and wrapped in a
+  nested table with a thin **solid** border and a caption row
+  "Twisted pair" / "Twisted triad" / "Twisted group", plus `: <rate>`.
+  Solid, because a dashed border means a shield (IEC) and bundles
+  already use a dashed box. Ports keep the original wire number
+  (`w{i}`), so edges do not change.
+- No drawn twist (split splines are a Graphviz limitation; out of scope).
+- The grouping helper is generic, so shielded cores (#330) can reuse it.
+
+## C4. Jumpers / internal shorts (#350)
+
+**Decided:** `shorts:`, shorted pins count as populated.
+
+```yaml
+connectors:
+  TB1:
+    pincount: 6
+    shorts: [[1, 2, 3], {RD: [5, 6]}]     # pin numbers or labels
+```
+
+- Each short is 2 or more pins, by number or label. Optional color as a
+  one-key mapping, like loops.
+- Drawn in the pin table: one narrow column per short, a filled cell at
+  each member pin and a solid bar between the first and last member.
+  Plain HTML table cells; no gvpr/neato.
+- Shorted pins are activated (visible with `hide_disconnected_pins`) and
+  count as `populated`.
+- No automatic BOM entry; users add `additional_components`.
+- `loops` keep their meaning (external wire loops).
+
+## C5. Print-ready sheet PDF (#32, #304)
+
+**Decided:** WeasyPrint as an optional extra, new format code.
+
+1. Template fixes (`din-6771.html`): named CSS pages per sheet size, so
+   a browser and WeasyPrint print one page at the right size; the
+   diagram area scales the SVG to fit above the BOM and title block;
+   `%date%` placeholder.
+2. New output format `sheet` (CLI `-f D`, file `<name>.sheet.pdf`): the
+   HTML output rendered to PDF with WeasyPrint. `pip install
+   "wireviz[pdf]"` adds it; without it a clear error says how to
+   install it. WeasyPrint gets a `url_fetcher` that refuses every URL
+   (all images are already inlined), so it reads no files or network.
+   `-f P` keeps its meaning (Graphviz diagram-only PDF).
+3. Later (not this batch): BOM headings in `options.terminology`, page
+   orientation, BOM auto-scaling.

From 3ebf21f9bc36245f878e8825eda2b289ed91a99d Mon Sep 17 00:00:00 2001
From: Cole Gentry <peapod2007@gmail.com>
Date: Fri, 2 Oct 2026 16:09:12 -0400
Subject: [PATCH 02/11] =?UTF-8?q?feat(errors):=20name=20the=20connection?=
 =?UTF-8?q?=20set=20in=20errors,=20infer=20wire=20count=20=E2=80=94=20#505?=
 =?UTF-8?q?,=20#207,=20#508?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- every error raised while a connection set is processed is prefixed
  with 'connection set N (X1 → W1 → X2): '; ValueError/TypeError keep
  their class, anything else becomes wv_errors.WireVizError(ValueError)
- the CLI prints input errors as one line (exit 1); --debug re-raises
- a cable without wirecount/colors takes its wire count from the wire
  numbers used for it (all sets; per template instance)
- behavior change: a bare named cable (- B1) uses wires 1..n instead of
  wire 1 n times; autogenerated '- W.' is unchanged
- clearer style: simple and unknown-wire-count messages
---
 docs/CHANGELOG.md             |   7 +
 docs/syntax.md                |   4 +
 src/wireviz/DataClasses.py    |   6 +-
 src/wireviz/wireviz.py        | 393 +++++++++++++++++++++-------------
 src/wireviz/wv_cli.py         |  40 +++-
 src/wireviz/wv_errors.py      |  11 +
 tests/test_dataclasses.py     |   4 +-
 tests/test_upstream_issues.py | 131 +++++++++++-
 8 files changed, 435 insertions(+), 161 deletions(-)
 create mode 100644 src/wireviz/wv_errors.py

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 0f719609..0bdb0475 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -21,8 +21,15 @@ Fixes for open issues in the original [wireviz/WireViz](https://github.com/wirev
 - `image: file.png` works as a short form of `image: {src: file.png}` ([#292](https://github.com/wireviz/WireViz/issues/292)).
 - Loops accept pin labels ([#432](https://github.com/wireviz/WireViz/issues/432)); loops on non-sequential pin numbers have a regression test ([#465](https://github.com/wireviz/WireViz/issues/465)).
 
+### Behavior changes
+
+- A cable named alone in a connection set (`- B1`) now uses wires 1 to n instead of wire 1 n times ([#508](https://github.com/wireviz/WireViz/issues/508)). Autogenerated cables (`- W.`) are unchanged.
+- Errors in the input name the connection set (`connection set 2 (X1 → W1 → X2): ...`) and the CLI prints them as one line with exit code 1; `--debug` shows the traceback ([#505](https://github.com/wireviz/WireViz/issues/505), [#207](https://github.com/wireviz/WireViz/issues/207)). Library callers can catch `wireviz.wv_errors.WireVizError` (a `ValueError`).
+
 ### New features
 
+- A cable with no `wirecount` or `colors` takes its wire count from the wire numbers used in the connections ([#508](https://github.com/wireviz/WireViz/issues/508)).
+
 - CSV BOM output: `-f c` / `output_formats="csv"` writes `<name>.bom.csv` ([#98](https://github.com/wireviz/WireViz/issues/98)).
 - Loop colors: `loops: [{RD: [VCC, SENSE]}]` ([#457](https://github.com/wireviz/WireViz/issues/457)).
 - `options.show_title: true` draws `metadata.title` above the diagram in PNG, SVG and PDF ([#460](https://github.com/wireviz/WireViz/issues/460)).
diff --git a/docs/syntax.md b/docs/syntax.md
index 44993508..3aa94870 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -266,6 +266,10 @@ connections:
   - `<int>-<int>` auto-expands to a range.
   - `<str>` to refer to a wire's label or color, if unambiguous.
 
+- `<designator>` alone (no wire list) uses wires 1 to n, where n is the number of parallel connections in the set. An autogenerated cable (`<template>.`) instead creates one new instance per connection.
+
+If a cable has neither `wirecount` nor `colors`, its wire count is taken from the highest wire number used for it in any connection set (or from n for a cable named alone). Wires referenced only by color or label cannot set the count.
+
 ### Arrows
 
 Arrows may be used in place of wires to join two connectors. This can represent the mating of matching connectors.
diff --git a/src/wireviz/DataClasses.py b/src/wireviz/DataClasses.py
index 2da8962d..32d86632 100644
--- a/src/wireviz/DataClasses.py
+++ b/src/wireviz/DataClasses.py
@@ -295,7 +295,8 @@ def __post_init__(self) -> None:
         if self.style == "simple":
             if self.pincount and self.pincount > 1:
                 raise Exception(
-                    "Connectors with style set to simple may only have one pin"
+                    f"Connector {self.name}: style simple allows only one pin, "
+                    f"but pincount is {self.pincount}"
                 )
             self.pincount = 1
 
@@ -560,7 +561,8 @@ def __post_init__(self) -> None:
         else:  # wirecount implicit in length of color list
             if not self.colors:
                 raise Exception(
-                    f"Cable {self.name}: unknown number of wires. Must specify wirecount or colors (implicit length)"
+                    f"Cable {self.name}: unknown number of wires. Set wirecount or colors, "
+                    "or connect it by wire number (e.g. W1: [1-4])"
                 )
             self.wirecount = len(self.colors)
 
diff --git a/src/wireviz/wireviz.py b/src/wireviz/wireviz.py
index 209f0fb0..b3b6ecf0 100755
--- a/src/wireviz/wireviz.py
+++ b/src/wireviz/wireviz.py
@@ -14,6 +14,7 @@
 
 from wireviz.DataClasses import Metadata, Options, Tweak
 from wireviz.Harness import Harness
+from wireviz.wv_errors import WireVizError
 from wireviz.wv_helper import (
     expand,
     file_read_text,
@@ -268,6 +269,9 @@ def parse(
                 yaml_data[sec] = []
 
     connection_sets = yaml_data["connections"]
+    implied_wirecounts = _implied_wirecounts(
+        connection_sets, template_cables, harness.options.template_separator
+    )
 
     # go through connection sets, generate and connect components ==============
 
@@ -318,162 +322,206 @@ def alternate_type():  # flip between connector and cable/arrow
         nonlocal expected_type
         expected_type = alternating_types[1 - alternating_types.index(expected_type)]
 
-    for connection_set in connection_sets:
-        # The steps below rewrite the set in place. A YAML alias (*name)
-        # makes several sets share one list, so work on a private copy.
-        connection_set = copy.deepcopy(connection_set)
-        # figure out number of parallel connections within this set
-        connectioncount = []
-        for entry in connection_set:
-            if isinstance(entry, list):
-                connectioncount.append(len(entry))
-            elif isinstance(entry, dict):
-                connectioncount.append(len(expand(list(entry.values())[0])))
-                # e.g.: - X1: [1-4,6] yields 5
-            else:
-                pass  # strings do not reveal connectioncount
-        if not any(connectioncount):
-            # no item in the list revealed connection count;
-            # assume connection count is 1
-            connectioncount = [1]
-            # Example: The following is a valid connection set,
-            #          even though no item reveals the connection count;
-            #          the count is not needed because only a component-level mate happens.
-            # -
-            #   - CONNECTOR
-            #   - ==>
-            #   - CONNECTOR
-
-        # check that all entries are the same length
-        if len(set(connectioncount)) > 1:
-            raise Exception(
-                "All items in connection set must reference the same number of connections"
-            )
-        # all entries are the same length, connection count is set
-        connectioncount = connectioncount[0]
-
-        # expand string entries to list entries of correct length
-        for index, entry in enumerate(connection_set):
-            if isinstance(entry, str):
-                connection_set[index] = [entry] * connectioncount
-
-        # resolve all designators
-        for index, entry in enumerate(connection_set):
-            if isinstance(entry, list):
-                for subindex, item in enumerate(entry):
-                    template, designator = resolve_designator(
-                        item, template_separator_char
+    for set_number, connection_set in enumerate(connection_sets, start=1):
+        set_label = _describe_set(connection_set)  # before the set is rewritten
+        try:
+            # The steps below rewrite the set in place. A YAML alias (*name)
+            # makes several sets share one list, so work on a private copy.
+            connection_set = copy.deepcopy(connection_set)
+            # figure out number of parallel connections within this set
+            connectioncount = []
+            for entry in connection_set:
+                if isinstance(entry, list):
+                    connectioncount.append(len(entry))
+                elif isinstance(entry, dict):
+                    connectioncount.append(len(expand(list(entry.values())[0])))
+                    # e.g.: - X1: [1-4,6] yields 5
+                else:
+                    pass  # strings do not reveal connectioncount
+            if not any(connectioncount):
+                # no item in the list revealed connection count;
+                # assume connection count is 1
+                connectioncount = [1]
+                # Example: The following is a valid connection set,
+                #          even though no item reveals the connection count;
+                #          the count is not needed because only a component-level mate happens.
+                # -
+                #   - CONNECTOR
+                #   - ==>
+                #   - CONNECTOR
+
+            # check that all entries are the same length
+            if len(set(connectioncount)) > 1:
+                raise Exception(
+                    "All items in connection set must reference the same number of connections"
+                )
+            # all entries are the same length, connection count is set
+            connectioncount = connectioncount[0]
+
+            # expand string entries to list entries of correct length
+            for index, entry in enumerate(connection_set):
+                if isinstance(entry, str):
+                    template_name, sep, designator_name = entry.partition(
+                        template_separator_char
                     )
-                    connection_set[index][subindex] = designator
-            elif isinstance(entry, dict):
-                key = list(entry.keys())[0]
-                template, designator = resolve_designator(key, template_separator_char)
-                value = entry[key]
-                connection_set[index] = {designator: value}
-            else:
-                pass  # string entries have been expanded in previous step
-
-        # expand all pin lists
-        for index, entry in enumerate(connection_set):
-            if isinstance(entry, list):
-                connection_set[index] = [{designator: 1} for designator in entry]
-            elif isinstance(entry, dict):
-                designator = list(entry.keys())[0]
-                pinlist = expand(entry[designator])
-                connection_set[index] = [{designator: pin} for pin in pinlist]
-            else:
-                pass  # string entries have been expanded in previous step
-
-        # Populate wiring harness ==============================================
-
-        expected_type = None  # reset check for alternating types
-        # at the beginning of every connection set
-        # since each set may begin with either type
-
-        # generate components
-        for entry in connection_set:
-            for item in entry:
-                designator = list(item.keys())[0]
-                template = designators_and_templates[designator]
-
-                if designator in harness.connectors:  # existing connector instance
-                    check_type(designator, template, "connector")
-                elif template in template_connectors.keys():
-                    # generate new connector instance from template
-                    check_type(designator, template, "connector")
-                    harness.add_connector(
-                        name=designator, **template_connectors[template]
+                    if template_name in template_cables and (
+                        not sep or designator_name
+                    ):
+                        # a bare named cable uses wires 1..n (upstream #508)
+                        connection_set[index] = {
+                            entry: list(range(1, connectioncount + 1))
+                        }
+                    else:
+                        connection_set[index] = [entry] * connectioncount
+
+            # resolve all designators
+            for index, entry in enumerate(connection_set):
+                if isinstance(entry, list):
+                    for subindex, item in enumerate(entry):
+                        template, designator = resolve_designator(
+                            item, template_separator_char
+                        )
+                        connection_set[index][subindex] = designator
+                elif isinstance(entry, dict):
+                    key = list(entry.keys())[0]
+                    template, designator = resolve_designator(
+                        key, template_separator_char
                     )
-
-                elif designator in harness.cables:  # existing cable instance
-                    check_type(designator, template, "cable/arrow")
-                elif template in template_cables.keys():
-                    # generate new cable instance from template
-                    check_type(designator, template, "cable/arrow")
-                    harness.add_cable(name=designator, **template_cables[template])
-
-                elif is_arrow(designator):
-                    check_type(designator, template, "cable/arrow")
-                    # arrows do not need to be generated here
+                    value = entry[key]
+                    connection_set[index] = {designator: value}
                 else:
-                    raise Exception(
-                        f"{template} is an unknown template/designator/arrow."
-                    )
+                    pass  # string entries have been expanded in previous step
+
+            # expand all pin lists
+            for index, entry in enumerate(connection_set):
+                if isinstance(entry, list):
+                    connection_set[index] = [{designator: 1} for designator in entry]
+                elif isinstance(entry, dict):
+                    designator = list(entry.keys())[0]
+                    pinlist = expand(entry[designator])
+                    connection_set[index] = [{designator: pin} for pin in pinlist]
+                else:
+                    pass  # string entries have been expanded in previous step
+
+            # Populate wiring harness ==============================================
+
+            expected_type = None  # reset check for alternating types
+            # at the beginning of every connection set
+            # since each set may begin with either type
+
+            # generate components
+            for entry in connection_set:
+                for item in entry:
+                    designator = list(item.keys())[0]
+                    template = designators_and_templates[designator]
+
+                    if designator in harness.connectors:  # existing connector instance
+                        check_type(designator, template, "connector")
+                    elif template in template_connectors.keys():
+                        # generate new connector instance from template
+                        check_type(designator, template, "connector")
+                        harness.add_connector(
+                            name=designator, **template_connectors[template]
+                        )
 
-            alternate_type()  # entries in connection set must alternate between connectors and cables/arrows
+                    elif designator in harness.cables:  # existing cable instance
+                        check_type(designator, template, "cable/arrow")
+                    elif template in template_cables.keys():
+                        # generate new cable instance from template
+                        check_type(designator, template, "cable/arrow")
+                        attribs = template_cables[template]
+                        if not attribs.get("wirecount") and not attribs.get("colors"):
+                            # infer the wire count from the connections (#508)
+                            count = implied_wirecounts.get(designator) or max(
+                                [
+                                    i[designator]
+                                    for e in connection_set
+                                    for i in e
+                                    if designator in i
+                                    and isinstance(i[designator], int)
+                                ],
+                                default=0,
+                            )
+                            if count:
+                                attribs = {**attribs, "wirecount": count}
+                        harness.add_cable(name=designator, **attribs)
+
+                    elif is_arrow(designator):
+                        check_type(designator, template, "cable/arrow")
+                        # arrows do not need to be generated here
+                    else:
+                        raise Exception(
+                            f"{template} is an unknown template/designator/arrow."
+                        )
 
-        # transpose connection set list
-        # before: one item per component, one subitem per connection in set
-        # after:  one item per connection in set, one subitem per component
-        connection_set = list(map(list, zip(*connection_set)))
+                alternate_type()  # entries in connection set must alternate between connectors and cables/arrows
+
+            # transpose connection set list
+            # before: one item per component, one subitem per connection in set
+            # after:  one item per connection in set, one subitem per component
+            connection_set = list(map(list, zip(*connection_set)))
+
+            # connect components
+            for index_entry, entry in enumerate(connection_set):
+                for index_item, item in enumerate(entry):
+                    designator = list(item.keys())[0]
+
+                    if designator in harness.cables:
+                        if index_item == 0:
+                            # list started with a cable, no connector to join on left side
+                            from_name, from_pin = (None, None)
+                        else:
+                            from_name, from_pin = get_single_key_and_value(
+                                entry[index_item - 1]
+                            )
+                        via_name, via_pin = (designator, item[designator])
+                        if index_item == len(entry) - 1:
+                            # list ends with a cable, no connector to join on right side
+                            to_name, to_pin = (None, None)
+                        else:
+                            to_name, to_pin = get_single_key_and_value(
+                                entry[index_item + 1]
+                            )
+                        harness.connect(
+                            from_name, from_pin, via_name, via_pin, to_name, to_pin
+                        )
 
-        # connect components
-        for index_entry, entry in enumerate(connection_set):
-            for index_item, item in enumerate(entry):
-                designator = list(item.keys())[0]
+                    elif is_arrow(designator):
+                        if index_item == 0:  # list starts with an arrow
+                            raise Exception(
+                                "An arrow cannot be at the start of a connection set"
+                            )
+                        elif index_item == len(entry) - 1:  # list ends with an arrow
+                            raise Exception(
+                                "An arrow cannot be at the end of a connection set"
+                            )
 
-                if designator in harness.cables:
-                    if index_item == 0:
-                        # list started with a cable, no connector to join on left side
-                        from_name, from_pin = (None, None)
-                    else:
                         from_name, from_pin = get_single_key_and_value(
                             entry[index_item - 1]
                         )
-                    via_name, via_pin = (designator, item[designator])
-                    if index_item == len(entry) - 1:
-                        # list ends with a cable, no connector to join on right side
-                        to_name, to_pin = (None, None)
-                    else:
+                        via_name, via_pin = (designator, None)
                         to_name, to_pin = get_single_key_and_value(
                             entry[index_item + 1]
                         )
-                    harness.connect(
-                        from_name, from_pin, via_name, via_pin, to_name, to_pin
-                    )
-
-                elif is_arrow(designator):
-                    if index_item == 0:  # list starts with an arrow
-                        raise Exception(
-                            "An arrow cannot be at the start of a connection set"
-                        )
-                    elif index_item == len(entry) - 1:  # list ends with an arrow
-                        raise Exception(
-                            "An arrow cannot be at the end of a connection set"
-                        )
-
-                    from_name, from_pin = get_single_key_and_value(
-                        entry[index_item - 1]
-                    )
-                    via_name, via_pin = (designator, None)
-                    to_name, to_pin = get_single_key_and_value(entry[index_item + 1])
-                    if "-" in designator:  # mate pin by pin
-                        harness.add_mate_pin(
-                            from_name, from_pin, to_name, to_pin, designator
-                        )
-                    elif "=" in designator and index_entry == 0:
-                        # mate two connectors as a whole
-                        harness.add_mate_component(from_name, to_name, designator)
+                        if "-" in designator:  # mate pin by pin
+                            harness.add_mate_pin(
+                                from_name, from_pin, to_name, to_pin, designator
+                            )
+                        elif "=" in designator and index_entry == 0:
+                            # mate two connectors as a whole
+                            harness.add_mate_component(from_name, to_name, designator)
+        except Exception as exc:
+            # Name the connection set (upstream #505, #207). Input errors
+            # keep their class; anything else becomes a WireVizError.
+            context = f"connection set {set_number} ({set_label})"
+            cls = (
+                type(exc) if isinstance(exc, (ValueError, TypeError)) else WireVizError
+            )
+            try:
+                error = cls(f"{context}: {exc}")
+            except Exception:  # an exception class with a special signature
+                error = WireVizError(f"{context}: {exc}")
+            raise error from exc
 
     # Auto-instantiate any declared connector that has loops but was not
     # referenced in a connection set. A connector whose only purpose is to
@@ -564,6 +612,65 @@ def alternate_type():  # flip between connector and cable/arrow
         return tuple(returns) if len(returns) != 1 else returns[0]
 
 
+def _describe_set(connection_set) -> str:
+    """Return "X1 → W1 → X2" for the items of a connection set."""
+    names = []
+    for entry in connection_set:
+        if isinstance(entry, dict) and entry:
+            names.append(str(next(iter(entry))))
+        elif isinstance(entry, list) and entry:
+            first = entry[0]
+            names.append(str(next(iter(first)) if isinstance(first, dict) else first))
+        else:
+            names.append(str(entry))
+    return " → ".join(names)
+
+
+def _implied_wirecounts(connection_sets, template_cables: Dict, separator: str) -> Dict:
+    """Return {cable designator: wire count} for cables that have neither
+    wirecount nor colors, from the wire numbers used for them (upstream
+    #508). A bare named cable in a set of n connections uses wires 1..n.
+    Autogenerated instances (``W.``) are counted where they are created."""
+    implied = {}
+
+    def designator_of(name):
+        if not isinstance(name, str):
+            return None, None
+        if separator in name:
+            template, _, designator = name.partition(separator)
+            return (template, designator) if designator else (None, None)
+        return name, name
+
+    for connection_set in connection_sets:
+        if not isinstance(connection_set, list):
+            continue
+        counts = [
+            len(e) if isinstance(e, list) else len(expand(list(e.values())[0]))
+            for e in connection_set
+            if isinstance(e, (list, dict)) and e
+        ]
+        n = max(counts) if counts else 1
+        for entry in connection_set:
+            if isinstance(entry, str):
+                template, designator, wires = *designator_of(entry), list(
+                    range(1, n + 1)
+                )
+            elif isinstance(entry, dict) and len(entry) == 1:
+                key, value = next(iter(entry.items()))
+                template, designator = designator_of(key)
+                wires = [w for w in expand(value) if isinstance(w, int)]
+            else:
+                continue
+            attribs = template_cables.get(template)
+            if designator is None or attribs is None:
+                continue
+            if attribs.get("wirecount") or attribs.get("colors"):
+                continue
+            if wires:
+                implied[designator] = max(implied.get(designator, 0), max(wires))
+    return implied
+
+
 def _disable_keys(yaml_data: Dict, keys) -> None:
     """Drop attributes from connectors and cables: ``"image"`` from all of
     them, ``"X1.image"`` from X1 only (upstream #410)."""
diff --git a/src/wireviz/wv_cli.py b/src/wireviz/wv_cli.py
index 363e4b26..ba8eaa85 100644
--- a/src/wireviz/wv_cli.py
+++ b/src/wireviz/wv_cli.py
@@ -5,6 +5,7 @@
 from pathlib import Path
 
 import click
+import yaml
 
 if __name__ == "__main__":
     sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
@@ -88,6 +89,12 @@
     "or from one (e.g. X1.image, where X1 is the key under connectors: or "
     "cables:). Repeatable.",
 )
+@click.option(
+    "--debug",
+    is_flag=True,
+    default=False,
+    help="Show a Python traceback for errors in the input.",
+)
 @click.option(
     "-V",
     "--version",
@@ -104,6 +111,7 @@ def wireviz(
     template_dir,
     embed_yaml,
     disable_keys,
+    debug,
     version,
 ):
     """
@@ -248,20 +256,30 @@ def wireviz(
                 err=True,
             )
 
-        wv.parse(
-            yaml_input,
-            output_formats=output_formats,
-            output_dir=_output_dir,
-            output_name=_output_name,
-            image_paths=image_paths,
-            source_path=file,
-            template_dir=template_dir,
-            embed_yaml=embed_yaml,
-            disable_keys=disable_keys,
-        )
+        try:
+            _parse_for_cli(
+                yaml_input,
+                output_formats=output_formats,
+                output_dir=_output_dir,
+                output_name=_output_name,
+                image_paths=image_paths,
+                source_path=file,
+                template_dir=template_dir,
+                embed_yaml=embed_yaml,
+                disable_keys=disable_keys,
+            )
+        except (ValueError, TypeError, yaml.YAMLError, FileNotFoundError) as exc:
+            # An error in the input: one clear line, no traceback (#505).
+            if debug:
+                raise
+            raise click.ClickException(f"{file}: {exc}") from exc
 
     click.echo("", err=True)
 
 
+def _parse_for_cli(*args, **kwargs):
+    return wv.parse(*args, **kwargs)
+
+
 if __name__ == "__main__":
     wireviz()
diff --git a/src/wireviz/wv_errors.py b/src/wireviz/wv_errors.py
new file mode 100644
index 00000000..fb3ea81f
--- /dev/null
+++ b/src/wireviz/wv_errors.py
@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+"""Errors WireViz raises for problems in the input."""
+
+
+class WireVizError(ValueError):
+    """A problem in the harness description (YAML), not a bug in WireViz.
+
+    It is a ValueError, so existing ``except ValueError`` code catches it.
+    Input errors that are already a ValueError or TypeError keep their
+    class; the connection-set context is added to their message.
+    """
diff --git a/tests/test_dataclasses.py b/tests/test_dataclasses.py
index 830da5fe..77751e50 100644
--- a/tests/test_dataclasses.py
+++ b/tests/test_dataclasses.py
@@ -32,7 +32,9 @@ def test_connector_simple_style_caps_pincount_to_1():
 
 
 def test_connector_simple_style_rejects_multi_pin():
-    with pytest.raises(Exception, match="simple may only have one pin"):
+    with pytest.raises(
+        Exception, match="Connector X1: style simple allows only one pin"
+    ):
         Connector(name="X1", style="simple", pincount=2)
 
 
diff --git a/tests/test_upstream_issues.py b/tests/test_upstream_issues.py
index 4736a416..bd2a64b6 100644
--- a/tests/test_upstream_issues.py
+++ b/tests/test_upstream_issues.py
@@ -116,9 +116,10 @@ def test_issue342_empty_file_via_cli(tmp_path: Path, runner):
     f = tmp_path / "empty.yml"
     f.write_text("")
     result = runner.invoke(cli, ["-f", "s", str(f)])
-    assert result.exit_code != 0
-    assert "IsADirectoryError" not in repr(result.exception)
-    assert "input is empty" in str(result.exception)
+    assert result.exit_code == 1
+    assert "IsADirectoryError" not in result.stderr
+    assert "input is empty" in result.stderr
+    assert "Traceback" not in result.stderr
 
 
 def test_issue487_colon_in_designators():
@@ -596,5 +597,127 @@ def test_quoted_numeric_wire_and_pin_labels():
 
 
 def test_empty_cable_error_names_the_cable():
+    # Wires referenced by color cannot imply a wire count (#508).
+    src = "connectors: {X1: {pincount: 1}}\ncables:\n  W1:\nconnections:\n  - - X1: [1]\n    - W1: [RD]\n"
     with pytest.raises(Exception, match="Cable W1: unknown number of wires"):
-        parse("cables:\n  W1:\nconnections: [[W1]]\n", return_types="harness")
+        parse(src, return_types="harness")
+
+
+# ===========================================================================
+# Batch C1 — error context (#505, #207) and wire count inference (#508)
+# ===========================================================================
+
+
+def test_issue505_error_names_the_connection_set():
+    src = """
+connectors: {X1: {pincount: 2}, X2: {pincount: 2}}
+cables: {W1: {wirecount: 2}}
+connections:
+  - - X1: [1, 2]
+    - W1: [1, 2]
+    - X2: [1, 2]
+  - - X1: [1]
+    - W1: [3]
+    - X2: [1]
+"""
+    with pytest.raises(ValueError) as exc:
+        parse(src, return_types="harness")
+    assert "connection set 2 (X1 → W1 → X2): W1:3 is out of range" in str(exc.value)
+
+
+def test_issue505_unknown_designator_is_wirevizerror():
+    from wireviz.wv_errors import WireVizError
+
+    src = (
+        "connectors: {X1: {pincount: 1}}\nconnections:\n  - - X1: [1]\n    - W9: [1]\n"
+    )
+    with pytest.raises(WireVizError, match="connection set 1 .*W9 is an unknown"):
+        parse(src, return_types="harness")
+
+
+def test_issue505_cli_prints_one_line(runner, tmp_path: Path):
+    from wireviz.wv_cli import wireviz as cli
+
+    f = tmp_path / "bad.yml"
+    f.write_text(
+        "connectors: {X1: {pincount: 1}}\ncables: {W1: {wirecount: 1}}\n"
+        "connections:\n  - - X1: [5]\n    - W1: [1]\n"
+    )
+    result = runner.invoke(cli, ["-f", "s", str(f)])
+    assert result.exit_code == 1
+    assert "Error:" in result.stderr and "X1:5 not found" in result.stderr
+    assert "Traceback" not in result.stderr
+    debug = runner.invoke(cli, ["-f", "s", "--debug", str(f)])
+    assert debug.exception is not None and "X1:5 not found" in str(debug.exception)
+
+
+def test_issue508_infer_wire_count_from_wire_numbers():
+    src = """
+connectors: {X1: {pincount: 4}, X2: {pincount: 4}}
+cables: {B1: {}}
+connections:
+  - - X1: [1-4]
+    - B1: [1-4]
+    - X2: [1-4]
+"""
+    h = parse(src, return_types="harness")
+    assert h.cables["B1"].wirecount == 4
+
+
+def test_issue508_bare_named_cable_uses_wires_1_to_n():
+    src = """
+connectors: {X1: {pincount: 3}, X2: {pincount: 3}}
+cables: {B1: {}, B2: {wirecount: 3}}
+connections:
+  - - X1: [1-3]
+    - B1
+    - X2: [1-3]
+  - - X1: [1-3]
+    - B2
+    - X2: [1-3]
+"""
+    h = parse(src, return_types="harness")
+    assert h.cables["B1"].wirecount == 3
+    for name in ("B1", "B2"):
+        assert [c.via_port for c in h.cables[name].connections] == [1, 2, 3]
+
+
+def test_issue508_largest_wire_number_over_all_sets():
+    src = """
+connectors: {X1: {pincount: 6}}
+cables: {B1: {}}
+connections:
+  - - X1: [1, 2]
+    - B1: [1, 2]
+  - - X1: [5]
+    - B1: [5]
+"""
+    assert parse(src, return_types="harness").cables["B1"].wirecount == 5
+
+
+def test_issue508_template_instances_get_their_own_count():
+    src = """
+connectors: {X1: {pincount: 4}}
+cables: {W: {}}
+connections:
+  - - X1: [1, 2]
+    - W.W1: [1, 2]
+  - - X1: [1-4]
+    - W.W2: [1-4]
+"""
+    h = parse(src, return_types="harness")
+    assert h.cables["W1"].wirecount == 2 and h.cables["W2"].wirecount == 4
+
+
+def test_issue508_autogenerated_bare_cable_keeps_its_meaning():
+    """`- W.` still makes one new single-wire cable per connection."""
+    src = """
+connectors: {X1: {pincount: 2}, X2: {pincount: 2}}
+cables: {W: {wirecount: 1}}
+connections:
+  - - X1: [1, 2]
+    - W.
+    - X2: [1, 2]
+"""
+    h = parse(src, return_types="harness")
+    assert len(h.cables) == 2

From 7be8dc6ea74084f1f16fc70f6a404bcb793508b3 Mon Sep 17 00:00:00 2001
From: Cole Gentry <peapod2007@gmail.com>
Date: Fri, 2 Oct 2026 16:14:32 -0400
Subject: [PATCH 03/11] =?UTF-8?q?feat(include):=20top-level=20include:=20f?=
 =?UTF-8?q?or=20shared=20connector/cable=20libraries=20=E2=80=94=20#220?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- include: [file, ...] merges connectors and cables by name (main file
  wins; the same name in two includes is an error naming both files) and
  appends additional_bom_items; metadata/options/tweak/connections stay
  main-file only
- nested includes, cycle and depth checks; paths relative to the
  including file, then -I/--include-path / parse(include_paths=...)
- relative image paths in an included file resolve against that file
- PNG output embeds the merged YAML; untrusted mode refuses include
- docs: include and --prepend in syntax.md
---
 CLAUDE.md                     |   1 +
 docs/CHANGELOG.md             |   1 +
 docs/syntax.md                |  22 ++++++
 src/wireviz/wireviz.py        |  21 +++++
 src/wireviz/wv_cli.py         |  11 +++
 src/wireviz/wv_include.py     | 141 ++++++++++++++++++++++++++++++++++
 tests/test_upstream_issues.py | 115 +++++++++++++++++++++++++++
 7 files changed, 312 insertions(+)
 create mode 100644 src/wireviz/wv_include.py

diff --git a/CLAUDE.md b/CLAUDE.md
index 8d620e30..60c6ba75 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -98,6 +98,7 @@ The pipeline is **YAML → Harness object graph → GraphViz `.gv` → rendered
 - **`svgembed.py`** — inlines referenced raster images into the SVG so the SVG/HTML output is self-contained.
 - **`wv_bom.py`** — BOM aggregation/dedup logic (`mini_bom_mode`, part-number handling, additional components). Reused for both the standalone `.bom.tsv` and the BOM table embedded in HTML.
 - **`wv_colors.py`** — IEC 60757 color codes, color-scheme generators (DIN 47100, 25-pair, TIA/EIA 568), `ColorMode` (SHORT / FULL / HEX, upper/lower).
+- **`wv_include.py`** — top-level `include:` (upstream #220): dict-level merge of `connectors`/`cables`/`additional_bom_items` from other files; main file wins, a duplicate between includes is an error; relative image paths are made absolute per included file. `parse()` refuses `include` when `untrusted=True` (it reads files).
 - **`wv_images.py`** — turns `data:image/...;base64` URIs and `.webp` files into PNG files in the harness's private temp dir (`Harness.temp_dir()`, removed when the Harness is garbage-collected). Graphviz needs a file in a format its build can read.
 - **`wv_helper.py`** — shared utilities: `awg_equiv`/`mm2_equiv` gauge conversion, `expand` (range syntax), `tuplelist2tsv`, `smart_file_resolve` (image-path resolution against the input dir + `--prepend` dirs).
 
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index b43caf16..2eb437be 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -30,6 +30,7 @@ Fixes for open issues in the original [wireviz/WireViz](https://github.com/wirev
 
 ### New features
 
+- `include:` merges shared connector/cable libraries from other files; `-I/--include-path` adds search directories ([#220](https://github.com/wireviz/WireViz/issues/220)). Not allowed in untrusted mode.
 - A cable with no `wirecount` or `colors` takes its wire count from the wire numbers used in the connections ([#508](https://github.com/wireviz/WireViz/issues/508)).
 
 - CSV BOM output: `-f c` / `output_formats="csv"` writes `<name>.bom.csv` ([#98](https://github.com/wireviz/WireViz/issues/98)).
diff --git a/docs/syntax.md b/docs/syntax.md
index 3aa94870..b029bc3c 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -368,6 +368,28 @@ connections:
 If any component is defined in the `connectors` or `cables` sections but not referenced in `connections`, a warning is printed in the console.
 
 
+## Include files
+
+A harness file can pull shared connector and cable definitions from other files:
+
+```yaml
+include:              # a file name or a list of file names
+  - lib/connectors.yml
+  - lib/cables.yml
+```
+
+- Paths are relative to the including file. The CLI option `-I/--include-path <dir>` (or `parse(include_paths=...)`) adds directories to search after that.
+- `connectors` and `cables` are merged by name. A definition in the including file wins over the same name in an included file. The same name in two included files is an error that names both files.
+- `additional_bom_items` from included files are added.
+- `metadata`, `options`, `tweak` and `connections` are allowed only in the main file.
+- Included files may include other files. A loop of includes is an error.
+- A relative `image: src:` in an included file is relative to that file.
+- Each file is read on its own, so YAML anchors (`&name`, `*name`, `<<:`) do not work across files.
+- A PNG output embeds the merged YAML, so it does not depend on the library files.
+
+The older CLI option `-p/--prepend <file>` still works: it puts the text of the file in front of the main file, so anchors defined there can be used in the main file. Prefer `include:`: with `--prepend`, two files that both have a `connectors:` section silently lose the first one.
+
+
 ## Metadata entries
 
 ```yaml
diff --git a/src/wireviz/wireviz.py b/src/wireviz/wireviz.py
index b3b6ecf0..23ea43db 100755
--- a/src/wireviz/wireviz.py
+++ b/src/wireviz/wireviz.py
@@ -24,6 +24,7 @@
     yaml_load,
 )
 from wireviz.wv_images import is_data_uri, materialize_data_uri, materialize_webp
+from wireviz.wv_include import resolve_includes
 from wireviz.wv_safety import UNTRUSTED_MAX_INPUT_BYTES, check_untrusted_image
 
 from . import APP_NAME
@@ -41,6 +42,7 @@ def parse(
     embed_yaml: bool = True,
     untrusted: bool = False,
     disable_keys: Union[None, str, Tuple[str, ...], List[str]] = None,
+    include_paths: Union[None, str, Path, List] = None,
 ) -> Any:
     """
     This function takes an input, parses it as a WireViz Harness file,
@@ -114,6 +116,10 @@ def parse(
             harness is built, e.g. ``"image"``; ``"X1.image"`` drops it
             from one component only (upstream #410). Lets one YAML render
             with and without images, notes, etc.
+        include_paths (Path | str | List, optional):
+            Directories searched for files named in a top-level
+            ``include:`` list, after the including file's directory
+            (upstream #220). See ``wv_include.py``.
 
     Returns:
         Depending on the return_types parameter, may return:
@@ -142,6 +148,21 @@ def parse(
         )
     if untrusted:
         _reject_tweaks(yaml_data)
+        if "include" in yaml_data:
+            raise ValueError("include is not allowed for untrusted input")
+    if "include" in yaml_data:
+        base = yaml_file or (
+            Path(source_path)
+            if source_path is not None and str(source_path) != "-"
+            else None
+        )
+        if isinstance(include_paths, (str, Path)):
+            include_paths = [include_paths]
+        resolve_includes(
+            yaml_data, base.parent if base else Path.cwd(), list(include_paths or [])
+        )
+        # A PNG must be self-contained: embed the merged YAML.
+        yaml_str = _yaml_source(yaml_data, None)
     if disable_keys:
         _disable_keys(yaml_data, disable_keys)
     # When inp was a Path, derive source_path automatically so callers
diff --git a/src/wireviz/wv_cli.py b/src/wireviz/wv_cli.py
index ba8eaa85..f0a44c8b 100644
--- a/src/wireviz/wv_cli.py
+++ b/src/wireviz/wv_cli.py
@@ -80,6 +80,15 @@
     default=True,
     help="Do not embed the source YAML in PNG output as an iTXt chunk.",
 )
+@click.option(
+    "-I",
+    "--include-path",
+    "include_paths",
+    multiple=True,
+    type=Path,
+    help="Directory searched for files named in include: (after the "
+    "including file's directory). Repeatable.",
+)
 @click.option(
     "--disable-key",
     "disable_keys",
@@ -110,6 +119,7 @@ def wireviz(
     output_name,
     template_dir,
     embed_yaml,
+    include_paths,
     disable_keys,
     debug,
     version,
@@ -267,6 +277,7 @@ def wireviz(
                 template_dir=template_dir,
                 embed_yaml=embed_yaml,
                 disable_keys=disable_keys,
+                include_paths=list(include_paths),
             )
         except (ValueError, TypeError, yaml.YAMLError, FileNotFoundError) as exc:
             # An error in the input: one clear line, no traceback (#505).
diff --git a/src/wireviz/wv_include.py b/src/wireviz/wv_include.py
new file mode 100644
index 00000000..0c151beb
--- /dev/null
+++ b/src/wireviz/wv_include.py
@@ -0,0 +1,141 @@
+# -*- coding: utf-8 -*-
+"""Top-level ``include:`` of shared connector/cable libraries (upstream #220).
+
+Each included file is parsed on its own and merged into the including
+file at dict level:
+
+- ``connectors`` and ``cables`` are merged by key. The including file
+  wins over its includes; the same key in two included files is an
+  error that names both files.
+- ``additional_bom_items`` are appended.
+- ``metadata``, ``options``, ``tweak`` and ``connections`` belong to the
+  main file only; in an included file they are an error.
+- A relative ``image.src`` in an included file is made absolute against
+  that file's directory.
+- Includes nest. A cycle, or nesting deeper than ``MAX_INCLUDE_DEPTH``,
+  is an error.
+
+YAML anchors and ``<<:`` do not cross files.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Sequence, Union
+
+from wireviz.wv_helper import file_read_text, yaml_load
+
+MAX_INCLUDE_DEPTH = 16
+MERGED_SECTIONS = ("connectors", "cables")
+MAIN_ONLY_SECTIONS = ("metadata", "options", "tweak", "connections")
+
+
+def resolve_includes(
+    yaml_data: Dict,
+    base_dir: Path,
+    include_paths: Sequence[Union[str, Path]] = (),
+    _stack: Optional[List[Path]] = None,
+) -> List[Path]:
+    """Merge the files named in ``yaml_data["include"]`` into ``yaml_data``
+    (in place) and return every file that was read."""
+    stack = _stack or []
+    includes = yaml_data.pop("include", None)
+    if includes is None:
+        return []
+    if isinstance(includes, str):
+        includes = [includes]
+    if not isinstance(includes, list) or not all(isinstance(i, str) for i in includes):
+        raise TypeError("include must be a file name or a list of file names")
+    if len(stack) >= MAX_INCLUDE_DEPTH:
+        raise ValueError(
+            f"include: nesting is deeper than {MAX_INCLUDE_DEPTH} levels ({stack[-1]})"
+        )
+
+    main_keys = {
+        section: set(yaml_data.get(section) or {}) for section in MERGED_SECTIONS
+    }
+    origin = {section: {} for section in MERGED_SECTIONS}  # key -> included file
+    read = []
+    for name in includes:
+        path = _find(name, base_dir, include_paths)
+        if path in stack:
+            chain = " -> ".join(str(p) for p in [*stack, path])
+            raise ValueError(f"include: cycle {chain}")
+        data = yaml_load(file_read_text(path))
+        if data is None:
+            data = {}
+        if not isinstance(data, dict):
+            raise TypeError(f"include {path}: expected a mapping at the top level")
+        for section in MAIN_ONLY_SECTIONS:
+            if section in data:
+                raise ValueError(
+                    f"include {path}: {section} is allowed only in the main file"
+                )
+        read.append(path)
+        read += resolve_includes(data, path.parent, include_paths, [*stack, path])
+        _absolute_images(data, path.parent)
+
+        for section in MERGED_SECTIONS:
+            entries = data.get(section) or {}
+            if not isinstance(entries, dict):
+                raise TypeError(f"include {path}: {section} must be a mapping")
+            target = yaml_data.get(section)
+            if not isinstance(target, dict):
+                target = yaml_data[section] = {}
+            for key, attribs in entries.items():
+                if key in main_keys[section]:
+                    continue  # the including file wins
+                if key in origin[section]:
+                    raise ValueError(
+                        f"include: {section}.{key} is defined in both "
+                        f"{origin[section][key]} and {path}"
+                    )
+                origin[section][key] = path
+                target[key] = attribs
+        extra = data.get("additional_bom_items") or []
+        if extra:
+            yaml_data["additional_bom_items"] = list(
+                yaml_data.get("additional_bom_items") or []
+            ) + list(extra)
+    return read
+
+
+def _find(name: str, base_dir: Path, include_paths) -> Path:
+    candidate = Path(name).expanduser()
+    if candidate.is_absolute():
+        roots = [candidate]
+    else:
+        roots = [Path(base_dir) / candidate] + [
+            Path(p) / candidate for p in include_paths
+        ]
+    for path in roots:
+        if path.is_file():
+            return path.resolve()
+    searched = "\n".join(str(p) for p in roots)
+    raise FileNotFoundError(f"include {name} was not found. Searched:\n{searched}")
+
+
+def _absolute_images(data: Dict, base_dir: Path) -> None:
+    """Make relative image paths of an included file absolute, so they
+    resolve against the included file and not the main file."""
+    for section in MERGED_SECTIONS:
+        for key, attribs in list((data.get(section) or {}).items()):
+            if not isinstance(attribs, dict):
+                continue
+            image = attribs.get("image")
+            src = (
+                image
+                if isinstance(image, str)
+                else (image.get("src") if isinstance(image, dict) else None)
+            )
+            if (
+                not isinstance(src, str)
+                or src[:5].lower() == "data:"
+                or Path(src).is_absolute()
+            ):
+                continue
+            resolved = str((base_dir / src).resolve())
+            data[section][key] = {
+                **attribs,
+                "image": (
+                    resolved if isinstance(image, str) else {**image, "src": resolved}
+                ),
+            }
diff --git a/tests/test_upstream_issues.py b/tests/test_upstream_issues.py
index bd2a64b6..bf396dab 100644
--- a/tests/test_upstream_issues.py
+++ b/tests/test_upstream_issues.py
@@ -721,3 +721,118 @@ def test_issue508_autogenerated_bare_cable_keeps_its_meaning():
 """
     h = parse(src, return_types="harness")
     assert len(h.cables) == 2
+
+
+# ===========================================================================
+# Batch C2 — include (#220)
+# ===========================================================================
+
+
+def _write(path: Path, text: str) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text)
+    return path
+
+
+MAIN_WITH_INCLUDE = """
+include: [lib/parts.yml]
+connections:
+  - - X1: [1, 2]
+    - W1: [1, 2]
+    - X2: [1, 2]
+"""
+
+
+def test_issue220_include_merges_library(tmp_path: Path):
+    _write(
+        tmp_path / "lib/parts.yml",
+        "connectors:\n  X1: {pinlabels: [A, B]}\n  X2: {pinlabels: [A, B]}\n"
+        "cables:\n  W1: {wirecount: 2}\n",
+    )
+    main = _write(tmp_path / "main.yml", MAIN_WITH_INCLUDE)
+    h = parse(main, return_types="harness")
+    assert set(h.connectors) == {"X1", "X2"} and "W1" in h.cables
+
+
+def test_issue220_main_file_wins_and_includes_conflict(tmp_path: Path):
+    _write(
+        tmp_path / "a.yml", "connectors:\n  X1: {pincount: 2}\n  X3: {pincount: 1}\n"
+    )
+    _write(tmp_path / "b.yml", "connectors:\n  X3: {pincount: 5}\n")
+    main = _write(
+        tmp_path / "main.yml",
+        "include: [a.yml]\nconnectors:\n  X1: {pincount: 9}\nconnections: [[X1]]\n",
+    )
+    assert parse(main, return_types="harness").connectors["X1"].pincount == 9
+    clash = _write(tmp_path / "clash.yml", "include: [a.yml, b.yml]\nconnections: []\n")
+    with pytest.raises(ValueError, match="connectors.X3 is defined in both"):
+        parse(clash, return_types="harness")
+
+
+def test_issue220_nested_cycle_and_main_only_sections(tmp_path: Path):
+    _write(tmp_path / "a.yml", "include: [b.yml]\nconnectors: {XA: {pincount: 1}}\n")
+    _write(tmp_path / "b.yml", "connectors: {XB: {pincount: 1}}\n")
+    main = _write(tmp_path / "m.yml", "include: [a.yml]\nconnections: [[XA], [XB]]\n")
+    assert set(parse(main, return_types="harness").connectors) == {"XA", "XB"}
+
+    _write(tmp_path / "c1.yml", "include: [c2.yml]\n")
+    _write(tmp_path / "c2.yml", "include: [c1.yml]\n")
+    cyc = _write(tmp_path / "cyc.yml", "include: [c1.yml]\n")
+    with pytest.raises(ValueError, match="cycle"):
+        parse(cyc, return_types="harness")
+
+    _write(tmp_path / "opt.yml", "options: {fontname: arial}\n")
+    bad = _write(tmp_path / "bad.yml", "include: opt.yml\n")
+    with pytest.raises(ValueError, match="options is allowed only in the main file"):
+        parse(bad, return_types="harness")
+
+
+def test_issue220_include_paths_and_cli(tmp_path: Path, runner):
+    from wireviz.wv_cli import wireviz as cli
+
+    _write(
+        tmp_path / "shared/lib/parts.yml",
+        "connectors:\n  X1: {pincount: 2}\n  X2: {pincount: 2}\ncables:\n  W1: {wirecount: 2}\n",
+    )
+    main = _write(tmp_path / "proj/main.yml", MAIN_WITH_INCLUDE)
+    with pytest.raises(FileNotFoundError):
+        parse(main, return_types="harness")
+    assert parse(main, return_types="harness", include_paths=[tmp_path / "shared"])
+    result = runner.invoke(cli, ["-f", "s", "-I", str(tmp_path / "shared"), str(main)])
+    assert result.exit_code == 0, result.stderr
+    assert (tmp_path / "proj/main.svg").exists()
+
+
+def test_issue220_images_resolve_against_included_file(tmp_path: Path):
+    _write(tmp_path / "lib/img/pic.png", "")
+    (tmp_path / "lib/img/pic.png").write_bytes(TRS.read_bytes())
+    _write(
+        tmp_path / "lib/parts.yml",
+        "connectors:\n  X1: {pincount: 1, image: img/pic.png}\n",
+    )
+    main = _write(
+        tmp_path / "main.yml", "include: [lib/parts.yml]\nconnections: [[X1]]\n"
+    )
+    assert "data:image/png;base64," in parse(main, return_types="svg")
+
+
+def test_issue220_png_embeds_merged_yaml(tmp_path: Path):
+    import io
+
+    from wireviz.Harness import read_yaml_from_png
+
+    _write(tmp_path / "lib.yml", "connectors:\n  X1: {pincount: 1}\n")
+    main = _write(tmp_path / "main.yml", "include: [lib.yml]\nconnections: [[X1]]\n")
+    png = parse(main, return_types="png")
+    embedded = read_yaml_from_png(io.BytesIO(png))
+    assert "include" not in embedded and "X1" in embedded
+    assert parse(embedded, return_types="harness").connectors["X1"]
+
+
+def test_issue220_untrusted_refuses_include():
+    with pytest.raises(ValueError, match="include is not allowed"):
+        parse(
+            "include: [/etc/hosts]\nconnectors: {}\n",
+            return_types="harness",
+            untrusted=True,
+        )

From b5b399c9125c60527887ffd7236d63549c4b43ae Mon Sep 17 00:00:00 2001
From: Cole Gentry <peapod2007@gmail.com>
Date: Fri, 2 Oct 2026 16:16:27 -0400
Subject: [PATCH 04/11] =?UTF-8?q?feat(twisted):=20twisted=20pairs,=20triad?=
 =?UTF-8?q?s=20and=20groups=20in=20the=20cable=20box=20=E2=80=94=20#3,=20#?=
 =?UTF-8?q?353?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cable twisted: [[RD, BK], {wires: [3, 4], rate: 20/m}] lists each group's
wires together, framed (solid border; dashed means a shield) with a
caption such as 'Twisted pair: 20/m'. Wires are referenced by number,
color or label; ports keep the wire number, so edges do not change.
Errors for a group under 2 wires, a wire in two groups, unknown wires.
---
 docs/CHANGELOG.md             |  1 +
 docs/syntax.md                |  5 +++
 src/wireviz/DataClasses.py    | 64 +++++++++++++++++++++++++++++++++++
 src/wireviz/Harness.py        | 27 +++++++++++++--
 tests/test_upstream_issues.py | 55 ++++++++++++++++++++++++++++++
 5 files changed, 149 insertions(+), 3 deletions(-)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 2eb437be..2310a197 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -30,6 +30,7 @@ Fixes for open issues in the original [wireviz/WireViz](https://github.com/wirev
 
 ### New features
 
+- Cable `twisted: [[RD, BK], {wires: [3, 4], rate: 20/m}]` shows twisted pairs, triads and groups as framed groups in the cable box ([#3](https://github.com/wireviz/WireViz/issues/3), [#353](https://github.com/wireviz/WireViz/issues/353)).
 - `include:` merges shared connector/cable libraries from other files; `-I/--include-path` adds search directories ([#220](https://github.com/wireviz/WireViz/issues/220)). Not allowed in untrusted mode.
 - A cable with no `wirecount` or `colors` takes its wire count from the wire numbers used in the connections ([#508](https://github.com/wireviz/WireViz/issues/508)).
 
diff --git a/docs/syntax.md b/docs/syntax.md
index b029bc3c..b726b46c 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -3,6 +3,8 @@
 ## Main sections
 
 ```yaml
+include:  # optional list of files with shared definitions (see below)
+
 connectors:  # dictionary of all used connectors
   <str>   :    # unique connector designator/name
     ...          # connector attributes (see below)
@@ -164,6 +166,9 @@ tweak:  # optional tweaking of .gv output
   show_name: <bool>         # defaults to true
   show_wirecount: <bool>    # defaults to true
   show_wirenumbers: <bool>  # defaults to true for cables; false for bundles
+  twisted: <List>           # twisted groups, each a list of 2+ wires by number, color
+                            # or wire label, e.g. [[RD, BK], [3, 4]]; a group may be
+                            # {wires: [...], rate: 20/m}; shown framed in the cable box
   show_box: <bool>          # defaults to true; false hides the cable box and draws
                             # each wire straight from connector to connector
                             # (every wire then needs a connector at both ends)
diff --git a/src/wireviz/DataClasses.py b/src/wireviz/DataClasses.py
index 006d0f96..0f5e9b7a 100644
--- a/src/wireviz/DataClasses.py
+++ b/src/wireviz/DataClasses.py
@@ -491,6 +491,8 @@ class Cable:
     show_wirecount: bool = True
     # False: no cable box; each wire is drawn from connector to connector (#212)
     show_box: bool = True
+    # Twisted groups (upstream #3, #353): [[RD, BK], {wires: [3, 4], rate: 20/m}]
+    twisted: List = field(default_factory=list)
     show_wirenumbers: Optional[bool] = None
     ignore_in_bom: bool = False
     additional_components: List[AdditionalComponent] = field(default_factory=list)
@@ -583,6 +585,32 @@ def __post_init__(self) -> None:
                     '"s" may not be used as a wire label for a shielded cable.'
                 )
 
+        self.twisted_groups: List[Tuple[List[int], Optional[str]]] = []
+        if not isinstance(self.twisted, list):
+            raise TypeError(f"Cable {self.name}: twisted must be a list of wire groups")
+        twisted_seen = {}
+        for group in self.twisted:
+            rate = None
+            wires = group
+            if isinstance(group, dict):
+                if set(group) - {"wires", "rate"}:
+                    raise ValueError(
+                        f"Cable {self.name}: a twisted group takes only wires and rate"
+                    )
+                wires, rate = group.get("wires"), group.get("rate")
+            if not isinstance(wires, list) or len(wires) < 2:
+                raise ValueError(
+                    f"Cable {self.name}: each twisted group needs a list of 2 or more wires"
+                )
+            numbers = [self.wire_number(w) for w in wires]
+            for number in numbers:
+                if number in twisted_seen:
+                    raise ValueError(
+                        f"Cable {self.name}: wire {number} is in more than one twisted group"
+                    )
+                twisted_seen[number] = True
+            self.twisted_groups.append((numbers, None if rate is None else str(rate)))
+
         # if lists of part numbers are provided check this is a bundle and that it matches the wirecount.
         for idfield in [self.manufacturer, self.mpn, self.supplier, self.spn, self.pn]:
             if isinstance(idfield, list):
@@ -605,6 +633,42 @@ def __post_init__(self) -> None:
             if isinstance(item, dict):
                 self.additional_components[i] = AdditionalComponent(**item)
 
+    def wire_number(self, wire) -> int:
+        """Return the 1-based number of a wire given by number, color or
+        wire label."""
+        if isinstance(wire, int) and not isinstance(wire, bool):
+            if 1 <= wire <= self.wirecount:
+                return wire
+        else:
+            for values in (self.colors, self.wirelabels):
+                if wire in values:
+                    if values.count(wire) > 1:
+                        raise ValueError(
+                            f"Cable {self.name}: {wire} is used for more than one wire"
+                        )
+                    return values.index(wire) + 1
+        raise ValueError(f"Cable {self.name}: wire {wire} not found")
+
+    def wire_display_order(self) -> Tuple[List[int], Dict[int, int]]:
+        """Return the order the wires are listed in the cable box, and
+        {wire: twisted group index}. The wires of a twisted group are
+        listed together, at the place of the group's lowest wire."""
+        group_of = {
+            wire: index
+            for index, (numbers, _) in enumerate(self.twisted_groups)
+            for wire in numbers
+        }
+        order, done = [], set()
+        for wire in range(1, self.wirecount + 1):
+            if wire in done:
+                continue
+            members = (
+                self.twisted_groups[group_of[wire]][0] if wire in group_of else [wire]
+            )
+            order += members
+            done.update(members)
+        return order, group_of
+
     # The *_pin arguments accept a tuple, but it seems not in use with the current code.
     def connect(
         self,
diff --git a/src/wireviz/Harness.py b/src/wireviz/Harness.py
index 81fcf512..a04f8c24 100644
--- a/src/wireviz/Harness.py
+++ b/src/wireviz/Harness.py
@@ -653,9 +653,26 @@ def create_graph(self) -> Graph:
             wirehtml.append('<table border="0" cellspacing="0" cellborder="0">')
             wirehtml.append("   <tr><td>&nbsp;</td></tr>")
 
-            for i, (connection_color, wirelabel) in enumerate(
-                zip_longest(cable.colors, cable.wirelabels), 1
-            ):
+            wires = list(zip_longest(cable.colors, cable.wirelabels))
+            order, group_of = cable.wire_display_order()
+            for i in order:
+                connection_color, wirelabel = wires[i - 1]
+                group = group_of.get(i)
+                if group is not None and i == cable.twisted_groups[group][0][0]:
+                    # Twisted group (upstream #3, #353): a thin solid frame
+                    # with a caption. Solid, because dashed means a shield.
+                    numbers, rate = cable.twisted_groups[group]
+                    kind = {2: "pair", 3: "triad", 4: "quad"}.get(len(numbers), "group")
+                    caption = f"Twisted {kind}" + (f": {rate}" if rate else "")
+                    wirehtml.append(
+                        '   <tr><td colspan="3" border="1" cellpadding="2">'
+                    )
+                    wirehtml.append(
+                        '    <table border="0" cellspacing="0" cellborder="0">'
+                    )
+                    wirehtml.append(
+                        f'     <tr><td colspan="3">{html_text(caption)}</td></tr>'
+                    )
                 wirehtml.append("   <tr>")
                 wirehtml.append(f"    <td><!-- {i}_in --></td>")
                 wirehtml.append(f"    <td>")
@@ -729,6 +746,10 @@ def create_graph(self) -> Graph:
                         wirehtml.append("   </td></tr>")
                         # fmt: on
 
+                if group is not None and i == cable.twisted_groups[group][0][-1]:
+                    wirehtml.append("    </table>")
+                    wirehtml.append("   </td></tr>")
+
             if cable.shield:
                 wirehtml.append("   <tr><td>&nbsp;</td></tr>")  # spacer
                 wirehtml.append("   <tr>")
diff --git a/tests/test_upstream_issues.py b/tests/test_upstream_issues.py
index bf396dab..c29e80bd 100644
--- a/tests/test_upstream_issues.py
+++ b/tests/test_upstream_issues.py
@@ -836,3 +836,58 @@ def test_issue220_untrusted_refuses_include():
             return_types="harness",
             untrusted=True,
         )
+
+
+# ===========================================================================
+# Batch C3 — twisted pairs (#3, #353)
+# ===========================================================================
+
+TWISTED = """
+connectors:
+  X1: {pincount: 4}
+  X2: {pincount: 4}
+cables:
+  W1:
+    colors: [RD, BK, WH, BU]
+    twisted: [[RD, BK], {wires: [3, 4], rate: 20/m}]
+connections:
+  - - X1: [1-4]
+    - W1: [1-4]
+    - X2: [1-4]
+"""
+
+
+@pytest.mark.parametrize("untrusted", [False, True])
+def test_issue3_twisted_pairs_render(untrusted: bool):
+    h = parse(TWISTED, return_types="harness", untrusted=untrusted)
+    assert h.cables["W1"].twisted_groups == [([1, 2], None), ([3, 4], "20/m")]
+    source = h.graph.source
+    assert "Twisted pair</td>" in source and "Twisted pair: 20/m" in source
+    for i in range(1, 5):
+        assert f'port="w{i}"' in source
+    assert "<svg" in h.svg
+
+
+def test_issue3_twisted_group_rows_are_contiguous():
+    src = TWISTED.replace(
+        "twisted: [[RD, BK], {wires: [3, 4], rate: 20/m}]", "twisted: [[1, 3, 4]]"
+    )
+    h = parse(src, return_types="harness")
+    assert h.cables["W1"].wire_display_order()[0] == [1, 3, 4, 2]
+    assert "Twisted triad" in h.graph.source
+
+
+@pytest.mark.parametrize(
+    "twisted, message",
+    [
+        ("[[1]]", "2 or more wires"),
+        ("[[1, 2], [2, 3]]", "more than one twisted group"),
+        ("[[1, 9]]", "wire 9 not found"),
+        ("[[RD, GN]]", "wire GN not found"),
+        ("[{wires: [1, 2], twist: left}]", "only wires and rate"),
+    ],
+)
+def test_issue3_twisted_errors(twisted: str, message: str):
+    src = TWISTED.replace("[[RD, BK], {wires: [3, 4], rate: 20/m}]", twisted)
+    with pytest.raises((ValueError, TypeError), match=message):
+        parse(src, return_types="harness")

From ba3318ced7090d4a8790862e4907657d8220f817 Mon Sep 17 00:00:00 2001
From: Cole Gentry <peapod2007@gmail.com>
Date: Fri, 2 Oct 2026 16:18:21 -0400
Subject: [PATCH 05/11] =?UTF-8?q?feat(shorts):=20internal=20shorts=20/=20j?=
 =?UTF-8?q?umpers=20in=20the=20connector=20pin=20table=20=E2=80=94=20#350?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Connector shorts: [[1, 2, 3], {YE: [N, AUX]}] draws each short as a
solid bar column next to the ports, with a dot at every shorted pin
(pins by number or label, optional color). Shorted pins are activated,
so they stay visible with hide_disconnected_pins and count as populated.
Plain HTML table cells; no gvpr/neato post-processing.
---
 docs/CHANGELOG.md             |  1 +
 docs/syntax.md                |  5 ++++
 src/wireviz/DataClasses.py    | 32 ++++++++++++++++++++
 src/wireviz/Harness.py        | 24 +++++++++++++++
 tests/test_upstream_issues.py | 55 +++++++++++++++++++++++++++++++++++
 5 files changed, 117 insertions(+)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 2310a197..62d1bb47 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -30,6 +30,7 @@ Fixes for open issues in the original [wireviz/WireViz](https://github.com/wirev
 
 ### New features
 
+- Connector `shorts: [[1, 2, 3], {YE: [N, AUX]}]` shows internal shorts and jumpers as a bar in the pin table; shorted pins count as populated ([#350](https://github.com/wireviz/WireViz/issues/350)).
 - Cable `twisted: [[RD, BK], {wires: [3, 4], rate: 20/m}]` shows twisted pairs, triads and groups as framed groups in the cable box ([#3](https://github.com/wireviz/WireViz/issues/3), [#353](https://github.com/wireviz/WireViz/issues/353)).
 - `include:` merges shared connector/cable libraries from other files; `-I/--include-path` adds search directories ([#220](https://github.com/wireviz/WireViz/issues/220)). Not allowed in untrusted mode.
 - A cable with no `wirecount` or `colors` takes its wire count from the wire numbers used in the connections ([#508](https://github.com/wireviz/WireViz/issues/508)).
diff --git a/docs/syntax.md b/docs/syntax.md
index b726b46c..183295bb 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -91,6 +91,11 @@ tweak:  # optional tweaking of .gv output
                  # pins may be given by number or by pin label, e.g. [VCC, SENSE];
                  # give a loop a wire color with a one-key mapping: {RD: [VCC, SENSE]}
 
+  # internal shorts / jumpers, e.g. on terminal blocks: each a list of 2+ pins
+  # (numbers or labels); optional color as a one-key mapping: {RD: [5, 6]}.
+  # Shorted pins count as populated and are always shown.
+  shorts: <List>
+
   # stripping lengths at this connector (shown in the diagram)
   strip:
     sleeve: <int/float/str>      # numbers are taken as mm, e.g. 10 or '0.4 in'
diff --git a/src/wireviz/DataClasses.py b/src/wireviz/DataClasses.py
index 0f5e9b7a..beb1427c 100644
--- a/src/wireviz/DataClasses.py
+++ b/src/wireviz/DataClasses.py
@@ -274,6 +274,8 @@ class Connector:
     show_pincount: Optional[bool] = None
     hide_disconnected_pins: bool = False
     loops: List[List[Pin]] = field(default_factory=list)
+    # Internal shorts / jumpers (upstream #350): [[1, 2, 3], {RD: [5, 6]}]
+    shorts: List = field(default_factory=list)
     ignore_in_bom: bool = False
     additional_components: List[AdditionalComponent] = field(default_factory=list)
     tweak: Optional[Tweak] = None
@@ -363,6 +365,36 @@ def __post_init__(self) -> None:
             self.loop_colors.append(color)
         self.loops = resolved_loops
 
+        # (pins, color) per short; shorted pins are populated and visible
+        self.short_groups: List[Tuple[List[Pin], Optional[Color]]] = []
+        if not isinstance(self.shorts, list):
+            raise TypeError(
+                f"Connector {self.name}: shorts must be a list of pin groups"
+            )
+        shorted = set()
+        for short in self.shorts:
+            color = None
+            if isinstance(short, dict) and len(short) == 1:
+                color, short = next(iter(short.items()))
+                if not isinstance(color, str):
+                    raise ValueError(
+                        f"Connector {self.name}: a short color must be a color "
+                        f"name such as RD, not {color!r}"
+                    )
+            if not isinstance(short, list) or len(short) < 2:
+                raise ValueError(
+                    f"Connector {self.name}: each short needs a list of 2 or more pins"
+                )
+            pins = [self.resolve_pin(pin) for pin in short]
+            for pin in pins:
+                if pin in shorted:
+                    raise ValueError(
+                        f"Connector {self.name}: pin {pin} is in more than one short"
+                    )
+                shorted.add(pin)
+                self.activate_pin(pin, None)
+            self.short_groups.append((pins, color))
+
         for i, item in enumerate(self.additional_components):
             if isinstance(item, dict):
                 self.additional_components[i] = AdditionalComponent(**item)
diff --git a/src/wireviz/Harness.py b/src/wireviz/Harness.py
index a04f8c24..6aee42f4 100644
--- a/src/wireviz/Harness.py
+++ b/src/wireviz/Harness.py
@@ -213,6 +213,27 @@ def _dot_attr_value(value: str) -> str:
     return '"' + re.sub(r'(?<!\\)"', r'\\"', value) + '"'
 
 
+def short_cells(connector: Connector, pinindex: int) -> List[str]:
+    """Return one table cell per short (upstream #350) for the pin row at
+    ``pinindex``: a solid bar from the first to the last shorted pin, with
+    a dot at each shorted pin."""
+    cells = []
+    for pins, color in connector.short_groups:
+        rows = [connector.pins.index(pin) for pin in pins]
+        hex_color = get_color_hex(color)[0] if color else "#000000"
+        if pinindex in rows:
+            r, g, b = (int(hex_color[i : i + 2], 16) for i in (1, 3, 5))
+            dot = "#000000" if (0.299 * r + 0.587 * g + 0.114 * b) > 150 else "#ffffff"
+            cells.append(
+                f'    <td border="0" bgcolor="{hex_color}"><font color="{dot}">&#9679;</font></td>'
+            )
+        elif min(rows) < pinindex < max(rows):
+            cells.append(f'    <td border="0" bgcolor="{hex_color}"></td>')
+        else:
+            cells.append('    <td border="0"></td>')
+    return cells
+
+
 def _edge(dot: Graph, tail: tuple, head: tuple, **attrs) -> None:
     """Add an edge between two ``(node, port, compass)`` endpoints.
 
@@ -529,6 +550,9 @@ def create_graph(self) -> Graph:
                         pinhtml.append(
                             f'    <td port="p{pinindex+1}l">{html_text(pinname)}</td>'
                         )
+                    # Shorts sit next to the left ports (or first): every row
+                    # has those cells, so the short columns line up.
+                    pinhtml.extend(short_cells(connector, pinindex))
                     if pinlabel:
                         pinhtml.append(f"    <td>{html_text(pinlabel)}</td>")
                     if connector.pincolors:
diff --git a/tests/test_upstream_issues.py b/tests/test_upstream_issues.py
index c29e80bd..c6489486 100644
--- a/tests/test_upstream_issues.py
+++ b/tests/test_upstream_issues.py
@@ -891,3 +891,58 @@ def test_issue3_twisted_errors(twisted: str, message: str):
     src = TWISTED.replace("[[RD, BK], {wires: [3, 4], rate: 20/m}]", twisted)
     with pytest.raises((ValueError, TypeError), match=message):
         parse(src, return_types="harness")
+
+
+# ===========================================================================
+# Batch C4 — internal shorts / jumpers (#350)
+# ===========================================================================
+
+SHORTS = """
+connectors:
+  TB1:
+    pinlabels: [L1, L2, L3, N, PE, AUX]
+    hide_disconnected_pins: true
+    shorts: [[L1, L2, L3], {YE: [N, AUX]}]
+    additional_components:
+      - {type: Ferrule, qty_multiplier: populated}
+  X2: {pincount: 6}
+cables:
+  W1: {wirecount: 2}
+connections:
+  - - TB1: [1, 4]
+    - W1: [1, 2]
+    - X2: [1, 4]
+"""
+
+
+@pytest.mark.parametrize("untrusted", [False, True])
+def test_issue350_shorts_render(untrusted: bool):
+    h = parse(SHORTS, return_types="harness", untrusted=untrusted)
+    tb1 = h.connectors["TB1"]
+    assert tb1.short_groups == [([1, 2, 3], None), ([4, 6], "YE")]
+    source = h.graph.source
+    assert source.count("&#9679;") == 5  # one dot per shorted pin
+    assert 'bgcolor="#ffff00"' in source  # YE bar
+    assert "<svg" in h.svg
+
+
+def test_issue350_shorted_pins_are_populated_and_visible():
+    h = parse(SHORTS, return_types="harness")
+    tb1 = h.connectors["TB1"]
+    assert set(tb1.visible_pins) == {1, 2, 3, 4, 6}  # PE (5) stays hidden
+    assert tb1.get_qty_multiplier("populated") == 5
+
+
+@pytest.mark.parametrize(
+    "shorts, message",
+    [
+        ("[[1]]", "2 or more pins"),
+        ("[[1, 2], [2, 3]]", "more than one short"),
+        ("[[1, NOPE]]", "TB1:NOPE not found"),
+        ("[{5: [1, 2]}]", "short color must be"),
+    ],
+)
+def test_issue350_short_errors(shorts: str, message: str):
+    src = SHORTS.replace("[[L1, L2, L3], {YE: [N, AUX]}]", shorts)
+    with pytest.raises((ValueError, TypeError, Exception), match=message):
+        parse(src, return_types="harness")

From c554f622e6c23e911144e12866f6c705aebbb112 Mon Sep 17 00:00:00 2001
From: Cole Gentry <peapod2007@gmail.com>
Date: Fri, 2 Oct 2026 16:22:58 -0400
Subject: [PATCH 06/11] =?UTF-8?q?feat(sheet):=20print-ready=20sheet=20PDF?=
 =?UTF-8?q?=20output=20(-f=20D)=20with=20WeasyPrint=20=E2=80=94=20#32,=20#?=
 =?UTF-8?q?304?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- new output format sheet (-f D, <name>.sheet.pdf): the HTML page
  rendered to one PDF page at the template's sheet size; optional extra
  wireviz[pdf] (WeasyPrint); its URL fetcher refuses every URL
- din-6771 template: flex layout so the diagram scales into the space
  above the BOM and title block (no overlap), named @page per sheet size
  (A4 portrait, A3/A2 landscape), A4 when sheetsize is not set
- simple template: print CSS fits the diagram to the page
- new <!-- %date% --> placeholder; -f P is unchanged (diagram-only PDF)
- CI installs Pango and wireviz[pdf] so the sheet tests run
---
 .github/workflows/tests.yml         |   3 +-
 CLAUDE.md                           |   1 +
 docs/CHANGELOG.md                   |   1 +
 docs/README.md                      |  10 +++
 setup.py                            |   4 ++
 src/wireviz/Harness.py              |  16 +++--
 src/wireviz/templates/README.md     | 108 ++++++++++++++--------------
 src/wireviz/templates/din-6771.html |  81 +++++++++++----------
 src/wireviz/templates/simple.html   |   6 ++
 src/wireviz/wireviz.py              |   2 +
 src/wireviz/wv_cli.py               |   1 +
 src/wireviz/wv_html.py              |   6 +-
 src/wireviz/wv_sheet.py             |  32 +++++++++
 tests/test_upstream_issues.py       |  71 ++++++++++++++++++
 14 files changed, 245 insertions(+), 97 deletions(-)
 create mode 100644 src/wireviz/wv_sheet.py

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 9d9963cb..c628e894 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -23,7 +23,8 @@ jobs:
       - name: Install package + test dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install .
+          sudo apt-get install -y libpango-1.0-0 libpangoft2-1.0-0
+          pip install ".[pdf]"
           pip install pytest
       - name: Run pytest
         run: pytest -v
diff --git a/CLAUDE.md b/CLAUDE.md
index 60c6ba75..d47f60fe 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -98,6 +98,7 @@ The pipeline is **YAML → Harness object graph → GraphViz `.gv` → rendered
 - **`svgembed.py`** — inlines referenced raster images into the SVG so the SVG/HTML output is self-contained.
 - **`wv_bom.py`** — BOM aggregation/dedup logic (`mini_bom_mode`, part-number handling, additional components). Reused for both the standalone `.bom.tsv` and the BOM table embedded in HTML.
 - **`wv_colors.py`** — IEC 60757 color codes, color-scheme generators (DIN 47100, 25-pair, TIA/EIA 568), `ColorMode` (SHORT / FULL / HEX, upper/lower).
+- **`wv_sheet.py`** — `sheet` output (`-f D`): the HTML page rendered to PDF with WeasyPrint (optional extra `wireviz[pdf]`, needs Pango). Its `url_fetcher` refuses every URL; everything in the HTML is inline. Page size comes from the template's named `@page` rules (`din-6771.html`: `.page_A3 { page: A3 }` etc.).
 - **`wv_include.py`** — top-level `include:` (upstream #220): dict-level merge of `connectors`/`cables`/`additional_bom_items` from other files; main file wins, a duplicate between includes is an error; relative image paths are made absolute per included file. `parse()` refuses `include` when `untrusted=True` (it reads files).
 - **`wv_images.py`** — turns `data:image/...;base64` URIs and `.webp` files into PNG files in the harness's private temp dir (`Harness.temp_dir()`, removed when the Harness is garbage-collected). Graphviz needs a file in a format its build can read.
 - **`wv_helper.py`** — shared utilities: `awg_equiv`/`mm2_equiv` gauge conversion, `expand` (range syntax), `tuplelist2tsv`, `smart_file_resolve` (image-path resolution against the input dir + `--prepend` dirs).
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 62d1bb47..9a11661d 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -30,6 +30,7 @@ Fixes for open issues in the original [wireviz/WireViz](https://github.com/wirev
 
 ### New features
 
+- Print-ready sheet PDF: `-f D` / `output_formats="sheet"` writes `<name>.sheet.pdf`, the HTML page (frame, diagram, BOM, title block) on one page at the template's sheet size. Needs `pip install "wireviz[pdf]"` (WeasyPrint). The `din-6771` template no longer lets the diagram overlap the BOM and title block, prints at the right page size, and defaults to A4; the simple template fits the diagram to the page when printed. New `<!-- %date% -->` placeholder ([#32](https://github.com/wireviz/WireViz/issues/32), [#304](https://github.com/wireviz/WireViz/issues/304)).
 - Connector `shorts: [[1, 2, 3], {YE: [N, AUX]}]` shows internal shorts and jumpers as a bar in the pin table; shorted pins count as populated ([#350](https://github.com/wireviz/WireViz/issues/350)).
 - Cable `twisted: [[RD, BK], {wires: [3, 4], rate: 20/m}]` shows twisted pairs, triads and groups as framed groups in the cable box ([#3](https://github.com/wireviz/WireViz/issues/3), [#353](https://github.com/wireviz/WireViz/issues/353)).
 - `include:` merges shared connector/cable libraries from other files; `-I/--include-path` adds search directories ([#220](https://github.com/wireviz/WireViz/issues/220)). Not allowed in untrusted mode.
diff --git a/docs/README.md b/docs/README.md
index 472d2a65..f00afb54 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -142,6 +142,16 @@ Wildcards in the file path are also supported to process multiple files at once,
 $ wireviz ~/path/to/files/*.yml
 ```
 
+### Print-ready PDF sheet
+
+`wireviz -f D harness.yml` writes `harness.sheet.pdf`: the HTML page (diagram, BOM and, with the `din-6771` template, frame and title block) as a one-page PDF at the template's sheet size (`metadata.template.sheetsize`: A4, A3 or A2). It needs WeasyPrint:
+
+```
+$ pip install "wireviz[pdf]"
+```
+
+WeasyPrint also needs the Pango library (`apt install libpango-1.0-0 libpangoft2-1.0-0` on Debian/Ubuntu, `brew install pango` on macOS; if Python then cannot find it on macOS, set `DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib`). `-f P` still writes the diagram alone as PDF, without this dependency.
+
 To see how to specify the output formats, as well as additional options, run:
 
 ```
diff --git a/setup.py b/setup.py
index 3931de12..90f5a754 100644
--- a/setup.py
+++ b/setup.py
@@ -24,6 +24,10 @@
         "pillow>=10.3",  # CVE-2023-4863, CVE-2023-44271, CVE-2024-28219
         "graphviz>=0.20",
     ],
+    extras_require={
+        # print-ready sheet PDF (-f D); also needs the Pango system library
+        "pdf": ["weasyprint>=62"],
+    },
     license="GPLv3",
     keywords="cable connector hardware harness wiring wiring-diagram wiring-harness",
     url=APP_URL,
diff --git a/src/wireviz/Harness.py b/src/wireviz/Harness.py
index 6aee42f4..27b5412f 100644
--- a/src/wireviz/Harness.py
+++ b/src/wireviz/Harness.py
@@ -68,6 +68,7 @@
     check_html_label,
     sanitize_svg,
 )
+from wireviz.wv_sheet import html_to_pdf
 
 OLD_CONNECTOR_ATTR = {
     "pinout": "was renamed to 'pinlabels' in v0.2",
@@ -1173,7 +1174,7 @@ def output(
                 out.flush()
             return
 
-        suffix_map = {"tsv": "bom.tsv", "csv": "bom.csv"}
+        suffix_map = {"tsv": "bom.tsv", "csv": "bom.csv", "sheet": "sheet.pdf"}
         Path(filename).parent.mkdir(parents=True, exist_ok=True)
         for f, content in outputs.items():
             ext = suffix_map.get(f, f)
@@ -1223,7 +1224,7 @@ def _render(
         outputs: Dict[str, Union[str, bytes]] = {}
 
         svg_str: Optional[str] = None
-        if "svg" in fmt or "html" in fmt:
+        if "svg" in fmt or "html" in fmt or "sheet" in fmt:
             # Resolve relative <image src=...> references against the YAML
             # source's directory when known; fall back to cwd. (In practice
             # wireviz.parse() rewrites relative image paths to absolute
@@ -1255,13 +1256,13 @@ def _render(
         if "gv" in fmt:
             outputs["gv"] = graph.source
 
-        if "tsv" in fmt or "csv" in fmt or "html" in fmt:
+        if "tsv" in fmt or "csv" in fmt or "html" in fmt or "sheet" in fmt:
             bomlist = bom_list(self.bom())
             if "tsv" in fmt:
                 outputs["tsv"] = tuplelist2tsv(bomlist)
             if "csv" in fmt:
                 outputs["csv"] = tuplelist2csv(bomlist)
-            if "html" in fmt:
+            if "html" in fmt or "sheet" in fmt:
                 # Inline PNG as base64 in the HTML only when the PNG was
                 # rendered in this same call; otherwise let the template
                 # fall back to reading {output_dir}/{output_name}.png.
@@ -1270,7 +1271,7 @@ def _render(
                     if png_bytes is not None
                     else None
                 )
-                outputs["html"] = generate_html_output(
+                html_page = generate_html_output(
                     svg_str,
                     bomlist,
                     self.metadata,
@@ -1282,6 +1283,11 @@ def _render(
                     template_dir=template_dir,
                     untrusted=self.untrusted,
                 )
+                if "html" in fmt:
+                    outputs["html"] = html_page
+                if "sheet" in fmt:
+                    # print-ready PDF of the HTML page (upstream #32, #304)
+                    outputs["sheet"] = html_to_pdf(html_page)
 
         return outputs
 
diff --git a/src/wireviz/templates/README.md b/src/wireviz/templates/README.md
index e9b4692b..5006c64b 100644
--- a/src/wireviz/templates/README.md
+++ b/src/wireviz/templates/README.md
@@ -1,53 +1,55 @@
-# HTML Output Templates
-
-This is the standard folder where WireViz looks for an HTML output template file.
-
-## Which HTML Output Template File is Used?
-
-A named HTML output template can optionally be specified as
-`metadata.template.name` in the YAML input:
-```yaml
-metadata:
-  template:
-    name: din-6771
-```
-In the case above, WireViz will search for a template file named
-`din-6771.html` in these folders:
-1. In the same folder as the YAML input file.
-2. In this standard template folder.
-
-If no HTML output template is specified, the `simple` template is assumed
-(i.e. filename `simple.html`, and in this case,
-only the standard template folder is searched).
-
-## Placeholders in HTML Output Templates
-
-HTML output template files might contain placeholders that will be replaced by
-generated text by WireViz when producing HTML output based on such a template.
-A placeholder starts with `<!-- %`, followed by a keyword, and finally `% -->`.
-Note that there must be one single space between `--` and `%` at both ends.
-
-| Placeholder | Replaced by |
-| --- | --- |
-| `<!-- %generator% -->` | The application name, version, and URL |
-| `<!-- %fontname% -->`  | The value of `options.fontname` |
-| `<!-- %bgcolor% -->`   | The HEX color translation of `options.bgcolor` |
-| `<!-- %filename% -->`  | The output path and filename without extension |
-| `<!-- %filename_stem% -->` | The output filename without path nor extension |
-| `<!-- %bom% -->`           | BOM as HTML table with headers at top |
-| `<!-- %bom_reversed% -->`  | Reversed BOM as HTML table with headers at bottom |
-| `<!-- %sheet_current% -->` | `1` (multi-page documents not yet supported) |
-| `<!-- %sheet_total% -->`   | `1` (multi-page documents not yet supported) |
-| `<!-- %diagram% -->`       | Embedded SVG diagram as valid HTML |
-| `<!-- %diagram_png_b64% -->`  | Embedded base64 encoded PNG diagram as URI |
-| `<!-- %revision% -->`         | Name (key) of the last entry in `metadata.revisions`, or empty string |
-| `<!-- %{item}% -->`           | String or numeric value of `metadata.{item}` |
-| `<!-- %{item}_{i}% -->`       | Category number `{i}` within dict value of `metadata.{item}` |
-| `<!-- %{item}_{i}_{key}% -->` | Value of `metadata.{item}.{category}.{key}` |
-| `<!-- %template_sheetsize% -->` | Value of `metadata.template.sheetsize` |
-
-Note that `{item}`, `{category}` and `{key}` in the description above can be
-any valid YAML key, and `{i}` is an integer representing the 1-based index of
-category entries in a dict `metadata.{item}` entry.
-The `{` and `}` characters are not literally part of the syntax, just used in
-this documentation to enclose the variable parts of the keywords.
+# HTML Output Templates
+
+This is the standard folder where WireViz looks for an HTML output template file.
+
+## Which HTML Output Template File is Used?
+
+A named HTML output template can optionally be specified as
+`metadata.template.name` in the YAML input:
+```yaml
+metadata:
+  template:
+    name: din-6771
+```
+In the case above, WireViz will search for a template file named
+`din-6771.html` in these folders:
+1. In the same folder as the YAML input file.
+2. In this standard template folder.
+
+If no HTML output template is specified, the `simple` template is assumed
+(i.e. filename `simple.html`, and in this case,
+only the standard template folder is searched).
+
+## Placeholders in HTML Output Templates
+
+HTML output template files might contain placeholders that will be replaced by
+generated text by WireViz when producing HTML output based on such a template.
+A placeholder starts with `<!-- %`, followed by a keyword, and finally `% -->`.
+Note that there must be one single space between `--` and `%` at both ends.
+
+| Placeholder | Replaced by |
+| --- | --- |
+| `<!-- %generator% -->` | The application name, version, and URL |
+| `<!-- %fontname% -->`  | The value of `options.fontname` |
+| `<!-- %bgcolor% -->`   | The HEX color translation of `options.bgcolor` |
+| `<!-- %filename% -->`  | The output path and filename without extension |
+| `<!-- %filename_stem% -->` | The output filename without path nor extension |
+| `<!-- %bom% -->`           | BOM as HTML table with headers at top |
+| `<!-- %bom_reversed% -->`  | Reversed BOM as HTML table with headers at bottom |
+| `<!-- %sheet_current% -->` | `1` (multi-page documents not yet supported) |
+| `<!-- %sheet_total% -->`   | `1` (multi-page documents not yet supported) |
+| `<!-- %diagram% -->`       | Embedded SVG diagram as valid HTML |
+| `<!-- %diagram_png_b64% -->`  | Embedded base64 encoded PNG diagram as URI |
+| `<!-- %revision% -->`         | Name (key) of the last entry in `metadata.revisions`, or empty string |
+| `<!-- %date% -->`             | Today's date, `YYYY-MM-DD` |
+| `<!-- %template_sheetsize% -->` | `metadata.template.sheetsize` (`A4` when not set) |
+| `<!-- %{item}% -->`           | String or numeric value of `metadata.{item}` |
+| `<!-- %{item}_{i}% -->`       | Category number `{i}` within dict value of `metadata.{item}` |
+| `<!-- %{item}_{i}_{key}% -->` | Value of `metadata.{item}.{category}.{key}` |
+| `<!-- %template_sheetsize% -->` | Value of `metadata.template.sheetsize` |
+
+Note that `{item}`, `{category}` and `{key}` in the description above can be
+any valid YAML key, and `{i}` is an integer representing the 1-based index of
+category entries in a dict `metadata.{item}` entry.
+The `{` and `}` characters are not literally part of the syntax, just used in
+this documentation to enclose the variable parts of the keywords.
diff --git a/src/wireviz/templates/din-6771.html b/src/wireviz/templates/din-6771.html
index 1aab000d..1fa41578 100644
--- a/src/wireviz/templates/din-6771.html
+++ b/src/wireviz/templates/din-6771.html
@@ -34,8 +34,13 @@
 
     /* Canvas size based on DIN 823 / DIN 6771 / EN ISO 5457 */
 
+    /* The frame is a column: the diagram takes the space left above the
+       footer (BOM + title block), so the diagram never overlaps them. */
     #frame {
       position: relative;
+      display: flex;
+      flex-direction: column;
+      box-sizing: border-box;
     }
 
     .A4, .sheetsize_default { /* portrait */
@@ -54,29 +59,37 @@
     }
 
     #diagram {
-      position: relative;
-      top: 0;
-      left: 0;
-      max-width: 100%;
-      height: calc(100% - 13 * 4.25mm);
-      /* TODO: auto-adapt to height of title block + BOM table;
-               BOM table might be above (A4) or to the left (A3 and larger) of the title block */
+      flex: 1 1 auto;
+      min-height: 0;
+      display: flex;
+      flex-direction: column;
       text-align: center;
-      vertical-align: middle;
     }
 
-    #diagram svg, #diagram img {
-      max-width: 95%;
-      max-height: 100%;
-      position: relative;
-      top: 50%;
-      transform: translateY(-50%);
+    #drawing {
+      flex: 1 1 auto;
+      min-height: 0;
+      padding: 3mm;
+    }
+
+    #drawing svg, #drawing img {
+      width: 100%;
+      height: 100%;
+      object-fit: contain;
+    }
+
+    /* A4: BOM on top of the title block; A3 and larger: BOM to its left */
+    #footer {
+      flex: 0 0 auto;
+      display: flex;
+      flex-direction: column;
+      align-items: flex-end;
     }
 
-    #titleblock {
-      position: absolute;
-      bottom: 0mm;
-      right: -0mm;
+    .A3 #footer, .A2 #footer {
+      flex-direction: row;
+      justify-content: space-between;
+      align-items: flex-end;
     }
 
     #titleblock table {
@@ -88,18 +101,6 @@
       height: 4.25mm;
     }
 
-    .A4 #bom { /* BOM on top of title block */
-      position: absolute;
-      bottom: 38.25mm;
-      right: 0;
-    }
-
-    .A3 #bom, .A2 #bom { /* BOM to the left of title block */
-      position: absolute;
-      bottom: 0mm;
-      left: 0mm;
-    }
-
     #bom table {
       width:180mm;
     }
@@ -164,12 +165,14 @@
   </style>
   <style type="text/css" media="print">
 
-    @page {
-      size: auto;
-      margin: 0;
-    }
+    /* One named page per sheet size, so a browser and WeasyPrint print
+       exactly one sheet: frame + 20 mm filing margin left, 10 mm elsewhere. */
+    @page { size: A4 portrait; margin: 0; }
+    @page A3 { size: A3 landscape; margin: 0; }
+    @page A2 { size: A2 landscape; margin: 0; }
+    .page_A3 { page: A3; }
+    .page_A2 { page: A2; }
 
-    /* TODO: auto-adjust based on portrait (larger margin on left) or landscape (larger margin on top) */
     #page {
       margin: 10mm;
       margin-left: 20mm;
@@ -178,7 +181,7 @@
   </style>
 </head>
 <body>
-  <div id="page">
+  <div id="page" class="page_<!-- %template_sheetsize% -->">
     <div id="frame" class="<!-- %template_sheetsize% -->">
 
       <div id="diagram">
@@ -187,7 +190,9 @@
           <!-- %description% -->
         </div>
 
-        <!-- %diagram% -->
+        <div id="drawing">
+          <!-- %diagram% -->
+        </div>
 
         <div id="notes">
           <!-- %notes% -->
@@ -195,6 +200,7 @@
 
       </div>
 
+      <div id="footer">
       <div id="bom">
         <!-- %bom_reversed% -->
       </div>
@@ -279,6 +285,7 @@
           </tr>
         </table>
       </div> <!-- /titleblock -->
+      </div> <!-- /footer -->
 
     </div> <!-- /frame -->
   </div> <!-- /page -->
diff --git a/src/wireviz/templates/simple.html b/src/wireviz/templates/simple.html
index cbb44659..a45037dd 100644
--- a/src/wireviz/templates/simple.html
+++ b/src/wireviz/templates/simple.html
@@ -20,6 +20,12 @@
     }
 
   </style>
+  <style media="print">
+    /* Fit the diagram to the page width when printed or rendered as a
+       sheet PDF (-f D). */
+    @page { size: A4 portrait; margin: 15mm; }
+    svg, img { max-width: 100%; height: auto; }
+  </style>
 </head><body style="font-family:<!-- %fontname% -->;background-color:<!-- %bgcolor% -->">
 <h1><!-- %title% --></h1>
 <h2>Diagram</h2>
diff --git a/src/wireviz/wireviz.py b/src/wireviz/wireviz.py
index 23ea43db..f41e7e86 100755
--- a/src/wireviz/wireviz.py
+++ b/src/wireviz/wireviz.py
@@ -64,6 +64,8 @@ def parse(
         * "html": the diagram and (depending on the template) the BOM, as a HTML file
         * "png":  the diagram, as a PNG raster image
         * "pdf":  the diagram, as a PDF document (no BOM — see "html" for that)
+        * "sheet": the HTML page (frame, diagram, BOM, title block) as a
+          print-ready PDF; needs ``pip install "wireviz[pdf]"``
         * "svg":  the diagram, as a SVG vector image
         * "tsv":  the BOM, as a tab-separated text file
 
diff --git a/src/wireviz/wv_cli.py b/src/wireviz/wv_cli.py
index f0a44c8b..b18e66eb 100644
--- a/src/wireviz/wv_cli.py
+++ b/src/wireviz/wv_cli.py
@@ -21,6 +21,7 @@
     "h": "html",
     "p": "png",
     "P": "pdf",
+    "D": "sheet",
     "s": "svg",
     "t": "tsv",
 }
diff --git a/src/wireviz/wv_html.py b/src/wireviz/wv_html.py
index f7c6d85d..c7106ab4 100644
--- a/src/wireviz/wv_html.py
+++ b/src/wireviz/wv_html.py
@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 
 import re
+from datetime import date
 from html import escape
 from pathlib import Path
 from typing import Callable, Dict, List, Union
@@ -16,6 +17,7 @@
 )
 from wireviz.wv_safety import check_template_name, sanitize_html_fragment
 
+
 def _latest_revision(metadata: Metadata) -> str:
     """Return the key of the most recently added entry in
     ``metadata.revisions`` when revisions is a dict or list, or the
@@ -139,9 +141,11 @@ def svgdata() -> str:
         "<!-- %bom_reversed% -->": bom_html_reversed,
         "<!-- %sheet_current% -->": "1",  # TODO: handle multi-page documents
         "<!-- %sheet_total% -->": "1",  # TODO: handle multi-page documents
+        # A4 when not set, so the DIN 6771 frame always has a size
         "<!-- %template_sheetsize% -->": clean(
-            (metadata.get("template") or {}).get("sheetsize", "")
+            (metadata.get("template") or {}).get("sheetsize") or "A4"
         ),
+        "<!-- %date% -->": date.today().isoformat(),
         "<!-- %revision% -->": clean(_latest_revision(metadata)),
     }
 
diff --git a/src/wireviz/wv_sheet.py b/src/wireviz/wv_sheet.py
new file mode 100644
index 00000000..b637bbd7
--- /dev/null
+++ b/src/wireviz/wv_sheet.py
@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+"""Print-ready sheet PDF: the HTML output rendered to PDF (upstream #32, #304).
+
+Uses WeasyPrint, an optional dependency: ``pip install "wireviz[pdf]"``.
+WeasyPrint also needs the Pango system library (on macOS with Homebrew,
+``brew install pango`` and, if Python cannot find it,
+``DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib``).
+
+The HTML already holds everything inline (SVG diagram, data-URI images),
+so WeasyPrint gets a URL fetcher that refuses every URL: rendering a
+sheet never reads a file or the network.
+"""
+
+
+class SheetPdfUnavailable(RuntimeError):
+    """WeasyPrint is not installed or cannot load its system libraries."""
+
+
+def _refuse_urls(url, *args, **kwargs):
+    raise ValueError(f"sheet PDF: external resources are not loaded ({url[:60]})")
+
+
+def html_to_pdf(html: str) -> bytes:
+    """Render the WireViz HTML output to a PDF document."""
+    try:
+        import weasyprint
+    except Exception as exc:  # ImportError, or OSError for missing Pango
+        raise SheetPdfUnavailable(
+            'The sheet PDF format needs WeasyPrint: pip install "wireviz[pdf]" '
+            f"(and the Pango library). Import failed: {exc}"
+        ) from exc
+    return weasyprint.HTML(string=html, url_fetcher=_refuse_urls).write_pdf()
diff --git a/tests/test_upstream_issues.py b/tests/test_upstream_issues.py
index c6489486..988dfd50 100644
--- a/tests/test_upstream_issues.py
+++ b/tests/test_upstream_issues.py
@@ -946,3 +946,74 @@ def test_issue350_short_errors(shorts: str, message: str):
     src = SHORTS.replace("[[L1, L2, L3], {YE: [N, AUX]}]", shorts)
     with pytest.raises((ValueError, TypeError, Exception), match=message):
         parse(src, return_types="harness")
+
+
+# ===========================================================================
+# Batch C5 — print-ready sheet PDF (#32, #304)
+# ===========================================================================
+
+
+def _weasyprint_available() -> bool:
+    try:
+        import weasyprint  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+needs_weasyprint = pytest.mark.skipif(
+    not _weasyprint_available(), reason="WeasyPrint (wireviz[pdf]) not available"
+)
+
+
+@needs_weasyprint
+@pytest.mark.parametrize("sheetsize", ["A4", "A3", "A2"])
+def test_issue32_sheet_pdf_page_size(tmp_path: Path, sheetsize: str):
+    """One page at the template's sheet size (frame + margins)."""
+    import weasyprint
+
+    src = (
+        f"metadata:\n  title: Sheet\n  template: {{name: din-6771, sheetsize: {sheetsize}}}\n"
+        + MINIMAL
+    )
+    parse(src, output_formats=("sheet",), output_dir=tmp_path, output_name="h")
+    assert (tmp_path / "h.sheet.pdf").read_bytes().startswith(b"%PDF")
+    html = parse(src, return_types="harness")._render(("html",))["html"]
+    pages = weasyprint.HTML(string=html).render().pages
+    assert len(pages) == 1
+    mm = 25.4 / 96  # CSS px -> mm
+    size = (round(pages[0].width * mm), round(pages[0].height * mm))
+    assert size == {"A4": (210, 297), "A3": (420, 297), "A2": (594, 420)}[sheetsize]
+
+
+@needs_weasyprint
+def test_issue32_sheet_pdf_untrusted_and_no_external_fetch():
+    src = (
+        "metadata:\n  title: '<img src=\"http://example.invalid/x.png\">T'\n" + MINIMAL
+    )
+    h = parse(src, return_types="harness", untrusted=True)
+    assert h._render(("sheet",))["sheet"].startswith(b"%PDF")
+
+
+def test_issue32_sheet_pdf_without_weasyprint(monkeypatch):
+    import builtins
+
+    from wireviz.wv_sheet import SheetPdfUnavailable
+
+    real_import = builtins.__import__
+
+    def fake_import(name, *args, **kwargs):
+        if name == "weasyprint":
+            raise ImportError("no weasyprint")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+    h = parse(MINIMAL, return_types="harness")
+    with pytest.raises(SheetPdfUnavailable, match=r'pip install "wireviz\[pdf\]"'):
+        h._render(("sheet",))
+
+
+def test_issue32_sheet_cli_code():
+    from wireviz.wv_cli import format_codes
+
+    assert format_codes["D"] == "sheet" and format_codes["P"] == "pdf"

From 866ed35ab27330bbce83187b2c83f8cf27855609 Mon Sep 17 00:00:00 2001
From: Cole Gentry <peapod2007@gmail.com>
Date: Fri, 2 Oct 2026 16:43:07 -0400
Subject: [PATCH 07/11] fix: address batch C review round 1 feedback

- sheet PDF: WeasyPrint gets a URLFetcher that allows data: URLs only
  (the refuse-all function dropped every inline image and, on 70, raised
  for any URL); requires weasyprint>=70; untrusted mode renders in a
  child process with the render timeout
- shorts: at most 64 per connector; spans computed once per connector
  (was O(pins^2 x shorts)); short colors must resolve to #rrggbb
- include: a file reached through two includes (diamond) is merged once;
  conflicts name the defining files; non-UTF-8 includes name the file;
  symlinked includes resolve relative paths next to the link
- #508: bare references to named template instances use wires 1..n and
  feed the wire-count pre-pass; out-of-range errors for a bare cable
  explain the change; the pre-pass skips malformed entries so the main
  loop reports them with context
- errors: only ValueError/TypeError/plain Exception get connection-set
  context (other exceptions are bugs and pass through); the CLI prints
  input and environment errors (incl. missing WeasyPrint or Graphviz) as
  one line
- warnings when shorts (style: simple) or twisted (show_box: false) are
  not shown; metadata.date wins over the built-in date placeholder;
  simple template prints at the browser's page size
- tests: sheet images and no-fetch, untrusted sheet timeout, WeasyPrint
  probed per test, not at collection
---
 docs/CHANGELOG.md                 |   2 +-
 docs/syntax.md                    |   5 +-
 setup.py                          |   2 +-
 src/wireviz/DataClasses.py        |  20 +++-
 src/wireviz/Harness.py            |  41 +++++--
 src/wireviz/templates/simple.html |   2 +-
 src/wireviz/wireviz.py            | 121 ++++++++++++++------
 src/wireviz/wv_cli.py             |  15 ++-
 src/wireviz/wv_html.py            |   4 +-
 src/wireviz/wv_include.py         |  46 +++++---
 src/wireviz/wv_sheet.py           |  68 +++++++++--
 tests/test_upstream_issues.py     | 180 +++++++++++++++++++++++++++---
 12 files changed, 412 insertions(+), 94 deletions(-)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 9a11661d..ce22fec0 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -30,7 +30,7 @@ Fixes for open issues in the original [wireviz/WireViz](https://github.com/wirev
 
 ### New features
 
-- Print-ready sheet PDF: `-f D` / `output_formats="sheet"` writes `<name>.sheet.pdf`, the HTML page (frame, diagram, BOM, title block) on one page at the template's sheet size. Needs `pip install "wireviz[pdf]"` (WeasyPrint). The `din-6771` template no longer lets the diagram overlap the BOM and title block, prints at the right page size, and defaults to A4; the simple template fits the diagram to the page when printed. New `<!-- %date% -->` placeholder ([#32](https://github.com/wireviz/WireViz/issues/32), [#304](https://github.com/wireviz/WireViz/issues/304)).
+- Print-ready sheet PDF: `-f D` / `output_formats="sheet"` writes `<name>.sheet.pdf`, the HTML page (frame, diagram, BOM, title block) on one page at the template's sheet size. Needs `pip install "wireviz[pdf]"` (WeasyPrint 70 or later); WeasyPrint may load only the inline `data:` images, never a file or URL, and in untrusted mode it runs in a child process with the render timeout. The `din-6771` template no longer lets the diagram overlap the BOM and title block, prints at the right page size, and defaults to A4; the simple template fits the diagram to the page when printed. New `<!-- %date% -->` placeholder ([#32](https://github.com/wireviz/WireViz/issues/32), [#304](https://github.com/wireviz/WireViz/issues/304)).
 - Connector `shorts: [[1, 2, 3], {YE: [N, AUX]}]` shows internal shorts and jumpers as a bar in the pin table; shorted pins count as populated ([#350](https://github.com/wireviz/WireViz/issues/350)).
 - Cable `twisted: [[RD, BK], {wires: [3, 4], rate: 20/m}]` shows twisted pairs, triads and groups as framed groups in the cable box ([#3](https://github.com/wireviz/WireViz/issues/3), [#353](https://github.com/wireviz/WireViz/issues/353)).
 - `include:` merges shared connector/cable libraries from other files; `-I/--include-path` adds search directories ([#220](https://github.com/wireviz/WireViz/issues/220)). Not allowed in untrusted mode.
diff --git a/docs/syntax.md b/docs/syntax.md
index 183295bb..33f72561 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -93,7 +93,8 @@ tweak:  # optional tweaking of .gv output
 
   # internal shorts / jumpers, e.g. on terminal blocks: each a list of 2+ pins
   # (numbers or labels); optional color as a one-key mapping: {RD: [5, 6]}.
-  # Shorted pins count as populated and are always shown.
+  # Shorted pins count as populated and are always shown. At most 64 shorts
+  # per connector; not shown for style: simple.
   shorts: <List>
 
   # stripping lengths at this connector (shown in the diagram)
@@ -388,7 +389,7 @@ include:              # a file name or a list of file names
   - lib/cables.yml
 ```
 
-- Paths are relative to the including file. The CLI option `-I/--include-path <dir>` (or `parse(include_paths=...)`) adds directories to search after that.
+- Paths are relative to the including file (for stdin or string input without a source path: to the working directory). The CLI option `-I/--include-path <dir>` (or `parse(include_paths=...)`) adds directories to search after that.
 - `connectors` and `cables` are merged by name. A definition in the including file wins over the same name in an included file. The same name in two included files is an error that names both files.
 - `additional_bom_items` from included files are added.
 - `metadata`, `options`, `tweak` and `connections` are allowed only in the main file.
diff --git a/setup.py b/setup.py
index 90f5a754..ce9e0c41 100644
--- a/setup.py
+++ b/setup.py
@@ -26,7 +26,7 @@
     ],
     extras_require={
         # print-ready sheet PDF (-f D); also needs the Pango system library
-        "pdf": ["weasyprint>=62"],
+        "pdf": ["weasyprint>=70"],
     },
     license="GPLv3",
     keywords="cable connector hardware harness wiring wiring-diagram wiring-harness",
diff --git a/src/wireviz/DataClasses.py b/src/wireviz/DataClasses.py
index beb1427c..1daebc09 100644
--- a/src/wireviz/DataClasses.py
+++ b/src/wireviz/DataClasses.py
@@ -6,7 +6,14 @@
 from pathlib import Path
 from typing import Dict, List, Optional, Set, Tuple, Union
 
-from wireviz.wv_colors import COLOR_CODES, Color, ColorMode, Colors, ColorScheme
+from wireviz.wv_colors import (
+    COLOR_CODES,
+    Color,
+    ColorMode,
+    Colors,
+    ColorScheme,
+    get_color_hex,
+)
 from wireviz.wv_helper import aspect_ratio, int2tuple, yaml11_bool
 from wireviz.wv_safety import check_count, check_fontname
 
@@ -47,6 +54,10 @@
 
 _BOOL_TYPES = (bool, Optional[bool], Union[bool, Color])
 
+# Most shorts (jumpers) on one connector. Each short is a table column
+# across every pin row, so this bounds the label size.
+MAX_SHORTS = 64
+
 
 def _coerce_bools(obj) -> None:
     """Turn yes/no/on/off strings into booleans in the boolean fields of
@@ -371,6 +382,8 @@ def __post_init__(self) -> None:
             raise TypeError(
                 f"Connector {self.name}: shorts must be a list of pin groups"
             )
+        if len(self.shorts) > MAX_SHORTS:
+            raise ValueError(f"Connector {self.name}: more than {MAX_SHORTS} shorts")
         shorted = set()
         for short in self.shorts:
             color = None
@@ -385,6 +398,11 @@ def __post_init__(self) -> None:
                 raise ValueError(
                     f"Connector {self.name}: each short needs a list of 2 or more pins"
                 )
+            if color is not None and any(len(h) != 7 for h in get_color_hex(color)):
+                raise ValueError(
+                    f"Connector {self.name}: short color {color!r} is not a color "
+                    "name or a #rrggbb value"
+                )
             pins = [self.resolve_pin(pin) for pin in short]
             for pin in pins:
                 if pin in shorted:
diff --git a/src/wireviz/Harness.py b/src/wireviz/Harness.py
index 27b5412f..33cf6f5a 100644
--- a/src/wireviz/Harness.py
+++ b/src/wireviz/Harness.py
@@ -214,21 +214,30 @@ def _dot_attr_value(value: str) -> str:
     return '"' + re.sub(r'(?<!\\)"', r'\\"', value) + '"'
 
 
-def short_cells(connector: Connector, pinindex: int) -> List[str]:
-    """Return one table cell per short (upstream #350) for the pin row at
-    ``pinindex``: a solid bar from the first to the last shorted pin, with
-    a dot at each shorted pin."""
-    cells = []
+def short_spans(connector: Connector) -> List[tuple]:
+    """Return (member rows, first row, last row, hex color) for each short
+    of ``connector`` (upstream #350); computed once per connector."""
+    spans = []
     for pins, color in connector.short_groups:
-        rows = [connector.pins.index(pin) for pin in pins]
+        rows = {connector.pins.index(pin) for pin in pins}
         hex_color = get_color_hex(color)[0] if color else "#000000"
+        spans.append((rows, min(rows), max(rows), hex_color))
+    return spans
+
+
+def short_cells(spans: List[tuple], pinindex: int) -> List[str]:
+    """Return one table cell per short for the pin row at ``pinindex``: a
+    solid bar from the first to the last shorted pin, with a dot at each
+    shorted pin."""
+    cells = []
+    for rows, first, last, hex_color in spans:
         if pinindex in rows:
             r, g, b = (int(hex_color[i : i + 2], 16) for i in (1, 3, 5))
             dot = "#000000" if (0.299 * r + 0.587 * g + 0.114 * b) > 150 else "#ffffff"
             cells.append(
                 f'    <td border="0" bgcolor="{hex_color}"><font color="{dot}">&#9679;</font></td>'
             )
-        elif min(rows) < pinindex < max(rows):
+        elif first < pinindex < last:
             cells.append(f'    <td border="0" bgcolor="{hex_color}"></td>')
         else:
             cells.append('    <td border="0"></td>')
@@ -498,6 +507,11 @@ def create_graph(self) -> Graph:
         )
 
         for connector in self.connectors.values():
+            if connector.style == "simple" and connector.short_groups:
+                sys.stderr.write(
+                    f"Warning: Connector {connector.name}: shorts are not shown "
+                    "for style: simple\n"
+                )
             # If no wires connected (except maybe loop wires)?
             if not (connector.ports_left or connector.ports_right):
                 connector.ports_left = True  # Use left side pins.
@@ -531,6 +545,7 @@ def create_graph(self) -> Graph:
 
             if connector.style != "simple":
                 pinhtml = []
+                spans = short_spans(connector)
                 pinhtml.append(
                     '<table border="0" cellspacing="0" cellpadding="3" cellborder="1">'
                 )
@@ -553,7 +568,7 @@ def create_graph(self) -> Graph:
                         )
                     # Shorts sit next to the left ports (or first): every row
                     # has those cells, so the short columns line up.
-                    pinhtml.extend(short_cells(connector, pinindex))
+                    pinhtml.extend(short_cells(spans, pinindex))
                     if pinlabel:
                         pinhtml.append(f"    <td>{html_text(pinlabel)}</td>")
                     if connector.pincolors:
@@ -910,6 +925,11 @@ def create_graph(self) -> Graph:
             html = "\n".join(html)
             if self.untrusted and cable.show_box:
                 check_html_label(html, f"Cable {cable.name}")
+            if not cable.show_box and cable.twisted_groups:
+                sys.stderr.write(
+                    f"Warning: Cable {cable.name}: twisted groups are not shown "
+                    "with show_box: false\n"
+                )
             if cable.show_box:
                 dot.node(
                     nohtml(cable.name),
@@ -1287,7 +1307,10 @@ def _render(
                     outputs["html"] = html_page
                 if "sheet" in fmt:
                     # print-ready PDF of the HTML page (upstream #32, #304)
-                    outputs["sheet"] = html_to_pdf(html_page)
+                    outputs["sheet"] = html_to_pdf(
+                        html_page,
+                        timeout=UNTRUSTED_RENDER_TIMEOUT if self.untrusted else None,
+                    )
 
         return outputs
 
diff --git a/src/wireviz/templates/simple.html b/src/wireviz/templates/simple.html
index a45037dd..6bc724dd 100644
--- a/src/wireviz/templates/simple.html
+++ b/src/wireviz/templates/simple.html
@@ -23,7 +23,7 @@
   <style media="print">
     /* Fit the diagram to the page width when printed or rendered as a
        sheet PDF (-f D). */
-    @page { size: A4 portrait; margin: 15mm; }
+    @page { size: auto; margin: 15mm; }
     svg, img { max-width: 100%; height: auto; }
   </style>
 </head><body style="font-family:<!-- %fontname% -->;background-color:<!-- %bgcolor% -->">
diff --git a/src/wireviz/wireviz.py b/src/wireviz/wireviz.py
index f41e7e86..baabcaf0 100755
--- a/src/wireviz/wireviz.py
+++ b/src/wireviz/wireviz.py
@@ -142,6 +142,7 @@ def parse(
     return_types = tuple(t.lower() for t in return_types or ())
 
     yaml_data, yaml_file, yaml_str = _get_yaml_data_and_path(inp, untrusted)
+    include_snapshot = None
     if yaml_data is None:
         raise ValueError("The input is empty: it holds no YAML content")
     if not isinstance(yaml_data, dict):
@@ -163,8 +164,8 @@ def parse(
         resolve_includes(
             yaml_data, base.parent if base else Path.cwd(), list(include_paths or [])
         )
-        # A PNG must be self-contained: embed the merged YAML.
-        yaml_str = _yaml_source(yaml_data, None)
+        # A PNG must be self-contained: it embeds the merged YAML.
+        include_snapshot = copy.deepcopy(yaml_data)
     if disable_keys:
         _disable_keys(yaml_data, disable_keys)
     # When inp was a Path, derive source_path automatically so callers
@@ -292,7 +293,7 @@ def parse(
                 yaml_data[sec] = []
 
     connection_sets = yaml_data["connections"]
-    implied_wirecounts = _implied_wirecounts(
+    implied_wirecounts, cable_instances = _implied_wirecounts(
         connection_sets, template_cables, harness.options.template_separator
     )
 
@@ -347,6 +348,7 @@ def alternate_type():  # flip between connector and cable/arrow
 
     for set_number, connection_set in enumerate(connection_sets, start=1):
         set_label = _describe_set(connection_set)  # before the set is rewritten
+        bare_cables = set()  # cables named alone in this set (#508)
         try:
             # The steps below rewrite the set in place. A YAML alias (*name)
             # makes several sets share one list, so work on a private copy.
@@ -387,9 +389,11 @@ def alternate_type():  # flip between connector and cable/arrow
                     template_name, sep, designator_name = entry.partition(
                         template_separator_char
                     )
-                    if template_name in template_cables and (
-                        not sep or designator_name
-                    ):
+                    if (
+                        template_name in template_cables
+                        and (not sep or designator_name)
+                    ) or (not sep and entry in cable_instances):
+                        bare_cables.add(designator_name or entry)
                         # a bare named cable uses wires 1..n (upstream #508)
                         connection_set[index] = {
                             entry: list(range(1, connectioncount + 1))
@@ -535,15 +539,27 @@ def alternate_type():  # flip between connector and cable/arrow
                             harness.add_mate_component(from_name, to_name, designator)
         except Exception as exc:
             # Name the connection set (upstream #505, #207). Input errors
-            # keep their class; anything else becomes a WireVizError.
-            context = f"connection set {set_number} ({set_label})"
-            cls = (
-                type(exc) if isinstance(exc, (ValueError, TypeError)) else WireVizError
-            )
+            # (ValueError, TypeError, plain Exception) get the context and
+            # keep their class (plain Exception becomes WireVizError);
+            # anything else is a bug and passes through unchanged.
+            if (
+                not isinstance(exc, (ValueError, TypeError))
+                and type(exc) is not Exception
+            ):
+                raise
+            message = f"connection set {set_number} ({set_label}): {exc}"
+            if "out of range" in str(exc) and any(
+                str(exc).startswith(f"{c}:") for c in bare_cables
+            ):
+                message += (
+                    " (a cable named alone uses wires 1..n since #508; "
+                    "list the wires, e.g. W1: [1, 1, 1], for the old meaning)"
+                )
+            cls = WireVizError if type(exc) is Exception else type(exc)
             try:
-                error = cls(f"{context}: {exc}")
+                error = cls(message)
             except Exception:  # an exception class with a special signature
-                error = WireVizError(f"{context}: {exc}")
+                error = WireVizError(message)
             raise error from exc
 
     # Auto-instantiate any declared connector that has loops but was not
@@ -593,7 +609,13 @@ def alternate_type():  # flip between connector and cable/arrow
     # Only build the YAML text for the PNG chunk when a PNG is produced.
     wants_png = "png" in (output_formats or ()) or "png" in return_types
     yaml_source_for_png = (
-        _yaml_source(inp, yaml_str) if embed_yaml and wants_png else None
+        (
+            _yaml_source(include_snapshot, None)
+            if include_snapshot is not None
+            else _yaml_source(inp, yaml_str)
+        )
+        if embed_yaml and wants_png
+        else None
     )
     if output_formats:
         if write_to_stdout:
@@ -649,12 +671,37 @@ def _describe_set(connection_set) -> str:
     return " → ".join(names)
 
 
-def _implied_wirecounts(connection_sets, template_cables: Dict, separator: str) -> Dict:
-    """Return {cable designator: wire count} for cables that have neither
-    wirecount nor colors, from the wire numbers used for them (upstream
-    #508). A bare named cable in a set of n connections uses wires 1..n.
-    Autogenerated instances (``W.``) are counted where they are created."""
-    implied = {}
+def _implied_wirecounts(connection_sets, template_cables: Dict, separator: str):
+    """Return ({cable designator: wire count}, {instance designator:
+    template}) for cables that have neither wirecount nor colors (upstream
+    #508): the count is the highest wire number used for the designator,
+    or n for a cable named alone in a set of n connections. Autogenerated
+    instances (``W.``) are counted where they are created. Malformed
+    entries are skipped here; the main loop reports them with context."""
+    sets = [s for s in connection_sets if isinstance(s, list)]
+
+    # every named cable instance (T.D) -> its template, over all sets
+    instances = {}
+    for connection_set in sets:
+        for entry in connection_set:
+            names = (
+                [entry]
+                if isinstance(entry, str)
+                else (
+                    list(entry)
+                    if isinstance(entry, dict)
+                    else (
+                        [e for e in entry if isinstance(e, str)]
+                        if isinstance(entry, list)
+                        else []
+                    )
+                )
+            )
+            for name in names:
+                if isinstance(name, str) and separator in name:
+                    template, _, designator = name.partition(separator)
+                    if designator and template in template_cables:
+                        instances[designator] = template
 
     def designator_of(name):
         if not isinstance(name, str):
@@ -662,36 +709,42 @@ def designator_of(name):
         if separator in name:
             template, _, designator = name.partition(separator)
             return (template, designator) if designator else (None, None)
-        return name, name
+        if name in template_cables:
+            return name, name
+        return instances.get(name), name
 
-    for connection_set in connection_sets:
-        if not isinstance(connection_set, list):
+    implied = {}
+    for connection_set in sets:
+        try:
+            counts = [
+                len(e) if isinstance(e, list) else len(expand(list(e.values())[0]))
+                for e in connection_set
+                if isinstance(e, (list, dict)) and e
+            ]
+        except (ValueError, TypeError):
             continue
-        counts = [
-            len(e) if isinstance(e, list) else len(expand(list(e.values())[0]))
-            for e in connection_set
-            if isinstance(e, (list, dict)) and e
-        ]
         n = max(counts) if counts else 1
         for entry in connection_set:
             if isinstance(entry, str):
-                template, designator, wires = *designator_of(entry), list(
-                    range(1, n + 1)
-                )
+                template, designator = designator_of(entry)
+                wires = list(range(1, n + 1))
             elif isinstance(entry, dict) and len(entry) == 1:
                 key, value = next(iter(entry.items()))
                 template, designator = designator_of(key)
-                wires = [w for w in expand(value) if isinstance(w, int)]
+                try:
+                    wires = [w for w in expand(value) if isinstance(w, int)]
+                except (ValueError, TypeError):
+                    continue
             else:
                 continue
             attribs = template_cables.get(template)
-            if designator is None or attribs is None:
+            if designator is None or not isinstance(attribs, dict):
                 continue
             if attribs.get("wirecount") or attribs.get("colors"):
                 continue
             if wires:
                 implied[designator] = max(implied.get(designator, 0), max(wires))
-    return implied
+    return implied, instances
 
 
 def _disable_keys(yaml_data: Dict, keys) -> None:
diff --git a/src/wireviz/wv_cli.py b/src/wireviz/wv_cli.py
index b18e66eb..327636cd 100644
--- a/src/wireviz/wv_cli.py
+++ b/src/wireviz/wv_cli.py
@@ -280,9 +280,18 @@ def wireviz(
                 disable_keys=disable_keys,
                 include_paths=list(include_paths),
             )
-        except (ValueError, TypeError, yaml.YAMLError, FileNotFoundError) as exc:
-            # An error in the input: one clear line, no traceback (#505).
-            if debug:
+        except Exception as exc:
+            # An error in the input or the environment (missing Graphviz or
+            # WeasyPrint): one clear line, no traceback (#505). Anything
+            # else is a bug and keeps its traceback.
+            known = (
+                ValueError,
+                TypeError,
+                yaml.YAMLError,
+                FileNotFoundError,
+                RuntimeError,
+            )
+            if debug or not (isinstance(exc, known) or type(exc) is Exception):
                 raise
             raise click.ClickException(f"{file}: {exc}") from exc
 
diff --git a/src/wireviz/wv_html.py b/src/wireviz/wv_html.py
index c7106ab4..7f6d1104 100644
--- a/src/wireviz/wv_html.py
+++ b/src/wireviz/wv_html.py
@@ -145,10 +145,12 @@ def svgdata() -> str:
         "<!-- %template_sheetsize% -->": clean(
             (metadata.get("template") or {}).get("sheetsize") or "A4"
         ),
-        "<!-- %date% -->": date.today().isoformat(),
         "<!-- %revision% -->": clean(_latest_revision(metadata)),
     }
 
+    if not (metadata and "date" in metadata):  # metadata.date wins
+        replacements["<!-- %date% -->"] = date.today().isoformat()
+
     def replacement_if_used(key: str, func: Callable[[], str]) -> None:
         """Append replacement only if used in html."""
         if key in html:
diff --git a/src/wireviz/wv_include.py b/src/wireviz/wv_include.py
index 0c151beb..2802353e 100644
--- a/src/wireviz/wv_include.py
+++ b/src/wireviz/wv_include.py
@@ -18,6 +18,7 @@
 YAML anchors and ``<<:`` do not cross files.
 """
 
+import os
 from pathlib import Path
 from typing import Dict, List, Optional, Sequence, Union
 
@@ -33,13 +34,16 @@ def resolve_includes(
     base_dir: Path,
     include_paths: Sequence[Union[str, Path]] = (),
     _stack: Optional[List[Path]] = None,
-) -> List[Path]:
+) -> Dict[tuple, Path]:
     """Merge the files named in ``yaml_data["include"]`` into ``yaml_data``
-    (in place) and return every file that was read."""
+    (in place). Return {(section, key): file that defines it} for every
+    merged entry, so the caller can tell a real conflict from the same
+    file reached twice (a "diamond": a.yml and b.yml both include
+    common.yml)."""
     stack = _stack or []
     includes = yaml_data.pop("include", None)
     if includes is None:
-        return []
+        return {}
     if isinstance(includes, str):
         includes = [includes]
     if not isinstance(includes, list) or not all(isinstance(i, str) for i in includes):
@@ -49,17 +53,22 @@ def resolve_includes(
             f"include: nesting is deeper than {MAX_INCLUDE_DEPTH} levels ({stack[-1]})"
         )
 
+    seen_files = set()
     main_keys = {
         section: set(yaml_data.get(section) or {}) for section in MERGED_SECTIONS
     }
-    origin = {section: {} for section in MERGED_SECTIONS}  # key -> included file
-    read = []
+    origin: Dict[tuple, Path] = {}  # (section, key) -> defining file
     for name in includes:
         path = _find(name, base_dir, include_paths)
-        if path in stack:
-            chain = " -> ".join(str(p) for p in [*stack, path])
+        real = path.resolve()
+        if real in stack:
+            chain = " -> ".join(str(p) for p in [*stack, real])
             raise ValueError(f"include: cycle {chain}")
-        data = yaml_load(file_read_text(path))
+        try:
+            text = file_read_text(path)
+        except UnicodeDecodeError as exc:
+            raise ValueError(f"include {path}: not a UTF-8 YAML file") from exc
+        data = yaml_load(text)
         if data is None:
             data = {}
         if not isinstance(data, dict):
@@ -69,8 +78,7 @@ def resolve_includes(
                 raise ValueError(
                     f"include {path}: {section} is allowed only in the main file"
                 )
-        read.append(path)
-        read += resolve_includes(data, path.parent, include_paths, [*stack, path])
+        nested = resolve_includes(data, path.parent, include_paths, [*stack, real])
         _absolute_images(data, path.parent)
 
         for section in MERGED_SECTIONS:
@@ -83,19 +91,25 @@ def resolve_includes(
             for key, attribs in entries.items():
                 if key in main_keys[section]:
                     continue  # the including file wins
-                if key in origin[section]:
+                defined_in = nested.get((section, key), real)
+                if (section, key) in origin:
+                    if origin[(section, key)] == defined_in:
+                        continue  # the same file reached twice
                     raise ValueError(
                         f"include: {section}.{key} is defined in both "
-                        f"{origin[section][key]} and {path}"
+                        f"{origin[(section, key)]} and {defined_in}"
                     )
-                origin[section][key] = path
+                origin[(section, key)] = defined_in
                 target[key] = attribs
         extra = data.get("additional_bom_items") or []
+        if real in seen_files:
+            extra = []  # a file reached twice adds its BOM items once
+        seen_files.add(real)
         if extra:
             yaml_data["additional_bom_items"] = list(
                 yaml_data.get("additional_bom_items") or []
             ) + list(extra)
-    return read
+    return origin
 
 
 def _find(name: str, base_dir: Path, include_paths) -> Path:
@@ -108,7 +122,9 @@ def _find(name: str, base_dir: Path, include_paths) -> Path:
         ]
     for path in roots:
         if path.is_file():
-            return path.resolve()
+            # absolute, but not resolved: relative paths inside a symlinked
+            # file stay relative to the link's directory
+            return Path(os.path.abspath(path))
     searched = "\n".join(str(p) for p in roots)
     raise FileNotFoundError(f"include {name} was not found. Searched:\n{searched}")
 
diff --git a/src/wireviz/wv_sheet.py b/src/wireviz/wv_sheet.py
index b637bbd7..172282da 100644
--- a/src/wireviz/wv_sheet.py
+++ b/src/wireviz/wv_sheet.py
@@ -1,32 +1,76 @@
 # -*- coding: utf-8 -*-
 """Print-ready sheet PDF: the HTML output rendered to PDF (upstream #32, #304).
 
-Uses WeasyPrint, an optional dependency: ``pip install "wireviz[pdf]"``.
+Uses WeasyPrint (>= 70), an optional dependency: ``pip install "wireviz[pdf]"``.
 WeasyPrint also needs the Pango system library (on macOS with Homebrew,
 ``brew install pango`` and, if Python cannot find it,
 ``DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib``).
 
-The HTML already holds everything inline (SVG diagram, data-URI images),
-so WeasyPrint gets a URL fetcher that refuses every URL: rendering a
-sheet never reads a file or the network.
+Everything the HTML needs is inline (SVG diagram, ``data:`` images), so
+WeasyPrint may fetch ``data:`` URLs only: rendering a sheet never reads a
+file or the network. With ``timeout`` set (untrusted mode), WeasyPrint
+runs in a child process that is stopped after ``timeout`` seconds.
 """
 
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
 
 class SheetPdfUnavailable(RuntimeError):
     """WeasyPrint is not installed or cannot load its system libraries."""
 
 
-def _refuse_urls(url, *args, **kwargs):
-    raise ValueError(f"sheet PDF: external resources are not loaded ({url[:60]})")
-
-
-def html_to_pdf(html: str) -> bytes:
-    """Render the WireViz HTML output to a PDF document."""
+def _weasyprint():
     try:
         import weasyprint
+        from weasyprint.urls import URLFetcher
     except Exception as exc:  # ImportError, or OSError for missing Pango
         raise SheetPdfUnavailable(
-            'The sheet PDF format needs WeasyPrint: pip install "wireviz[pdf]" '
+            'The sheet PDF format needs WeasyPrint 70 or later: pip install "wireviz[pdf]" '
             f"(and the Pango library). Import failed: {exc}"
         ) from exc
-    return weasyprint.HTML(string=html, url_fetcher=_refuse_urls).write_pdf()
+    return weasyprint, URLFetcher
+
+
+def _render(html: str) -> bytes:
+    weasyprint, URLFetcher = _weasyprint()
+    fetcher = URLFetcher(allowed_protocols={"data"}, allow_redirects=False)
+    return weasyprint.HTML(string=html, url_fetcher=fetcher).write_pdf()
+
+
+def html_to_pdf(html: str, timeout: Optional[float] = None) -> bytes:
+    """Render the WireViz HTML output to a PDF document."""
+    if timeout is None:
+        return _render(html)
+    _weasyprint()  # fail early, with the install hint, in this process
+    # The child must import this same wireviz package.
+    package_root = str(Path(__file__).resolve().parent.parent)
+    env = {
+        **os.environ,
+        "PYTHONPATH": os.pathsep.join(
+            p for p in (package_root, os.environ.get("PYTHONPATH")) if p
+        ),
+    }
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "wireviz.wv_sheet"],
+            input=html.encode("utf-8"),
+            capture_output=True,
+            timeout=timeout,
+            env=env,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError(f"The sheet PDF did not finish within {timeout} s") from exc
+    if result.returncode != 0:
+        detail = result.stderr.decode("utf-8", "replace").strip().splitlines()
+        raise RuntimeError(
+            "The sheet PDF failed" + (f": {detail[-1]}" if detail else "")
+        )
+    return result.stdout
+
+
+if __name__ == "__main__":  # child process for html_to_pdf(timeout=...)
+    sys.stdout.buffer.write(_render(sys.stdin.buffer.read().decode("utf-8")))
diff --git a/tests/test_upstream_issues.py b/tests/test_upstream_issues.py
index 988dfd50..b4ca7be1 100644
--- a/tests/test_upstream_issues.py
+++ b/tests/test_upstream_issues.py
@@ -944,7 +944,7 @@ def test_issue350_shorted_pins_are_populated_and_visible():
 )
 def test_issue350_short_errors(shorts: str, message: str):
     src = SHORTS.replace("[[L1, L2, L3], {YE: [N, AUX]}]", shorts)
-    with pytest.raises((ValueError, TypeError, Exception), match=message):
+    with pytest.raises((ValueError, TypeError), match=message):
         parse(src, return_types="harness")
 
 
@@ -953,22 +953,18 @@ def test_issue350_short_errors(shorts: str, message: str):
 # ===========================================================================
 
 
-def _weasyprint_available() -> bool:
+@pytest.fixture
+def weasyprint_ok():
+    """Skip unless WeasyPrint and Pango load. Imported in the test, not at
+    collection, so a broken import cannot affect other tests."""
     try:
         import weasyprint  # noqa: F401
-    except Exception:
-        return False
-    return True
-
+    except Exception as exc:
+        pytest.skip(f"WeasyPrint (wireviz[pdf]) not available: {exc}")
 
-needs_weasyprint = pytest.mark.skipif(
-    not _weasyprint_available(), reason="WeasyPrint (wireviz[pdf]) not available"
-)
 
-
-@needs_weasyprint
 @pytest.mark.parametrize("sheetsize", ["A4", "A3", "A2"])
-def test_issue32_sheet_pdf_page_size(tmp_path: Path, sheetsize: str):
+def test_issue32_sheet_pdf_page_size(tmp_path: Path, sheetsize: str, weasyprint_ok):
     """One page at the template's sheet size (frame + margins)."""
     import weasyprint
 
@@ -986,8 +982,7 @@ def test_issue32_sheet_pdf_page_size(tmp_path: Path, sheetsize: str):
     assert size == {"A4": (210, 297), "A3": (420, 297), "A2": (594, 420)}[sheetsize]
 
 
-@needs_weasyprint
-def test_issue32_sheet_pdf_untrusted_and_no_external_fetch():
+def test_issue32_sheet_pdf_untrusted_and_no_external_fetch(weasyprint_ok):
     src = (
         "metadata:\n  title: '<img src=\"http://example.invalid/x.png\">T'\n" + MINIMAL
     )
@@ -1017,3 +1012,160 @@ def test_issue32_sheet_cli_code():
     from wireviz.wv_cli import format_codes
 
     assert format_codes["D"] == "sheet" and format_codes["P"] == "pdf"
+
+
+# ---------------------------------------------------------------------------
+# Batch C review round 1
+# ---------------------------------------------------------------------------
+
+
+def test_review_c_sheet_keeps_inline_images(weasyprint_ok, tmp_path: Path):
+    """data: images inside the SVG must reach the PDF (the fetcher used to
+    refuse them and WeasyPrint dropped the rest of the diagram)."""
+    import weasyprint
+
+    from wireviz.wv_sheet import html_to_pdf
+
+    (tmp_path / "pic.png").write_bytes(TRS.read_bytes())
+    src = "connectors:\n  X1: {pincount: 1, image: pic.png}\nconnections: [[X1]]\n"
+    html = parse(src, return_types="harness", image_paths=[tmp_path])._render(
+        ("html",)
+    )["html"]
+    assert html_to_pdf(html).startswith(b"%PDF")
+    images = []
+    page = weasyprint.HTML(string=html).render().pages[0]
+
+    def walk(box):
+        if type(box).__name__ in ("InlineReplacedBox", "BlockReplacedBox"):
+            images.append(box)
+        for child in getattr(box, "children", []) or []:
+            walk(child)
+
+    walk(page._page_box)
+    assert images  # the SVG is laid out as a replaced box
+    from weasyprint.urls import URLFetcher
+
+    fetched = []
+    original = URLFetcher.fetch
+
+    def spy(self, url, *a, **k):
+        fetched.append(url[:10])
+        return original(self, url, *a, **k)
+
+    import unittest.mock as mock
+
+    with mock.patch.object(URLFetcher, "fetch", spy):
+        html_to_pdf(html)
+    assert fetched and all(u.startswith("data:") for u in fetched)
+
+
+def test_review_c_sheet_never_fetches_files(weasyprint_ok, monkeypatch):
+    import urllib.request
+
+    from wireviz.wv_sheet import html_to_pdf
+
+    def refuse(*a, **k):
+        raise AssertionError("WeasyPrint tried to open a URL")
+
+    monkeypatch.setattr(urllib.request, "urlopen", refuse)
+    html = '<html><body><img src="file:///etc/hosts"><img src="http://example.invalid/x.png"></body></html>'
+    assert html_to_pdf(html).startswith(b"%PDF")
+
+
+def test_review_c_untrusted_sheet_runs_with_timeout(weasyprint_ok, monkeypatch):
+    import wireviz.Harness as H
+
+    h = parse(MINIMAL, return_types="harness", untrusted=True)
+    assert h._render(("sheet",))["sheet"].startswith(b"%PDF")
+    monkeypatch.setattr(H, "UNTRUSTED_RENDER_TIMEOUT", 0.000001)
+    with pytest.raises(RuntimeError, match="did not finish"):
+        parse(MINIMAL, return_types="harness", untrusted=True)._render(("sheet",))
+
+
+def test_review_c_shorts_cap_and_color():
+    many = ", ".join(f"[{2 * i + 1}, {2 * i + 2}]" for i in range(65))
+    src = (
+        f"connectors:\n  X1: {{pincount: 130, shorts: [{many}]}}\nconnections: [[X1]]\n"
+    )
+    with pytest.raises(ValueError, match="more than 64 shorts"):
+        parse(src, return_types="harness")
+    src = "connectors:\n  X1: {pincount: 2, shorts: [{'#abc': [1, 2]}]}\nconnections: [[X1]]\n"
+    with pytest.raises(ValueError, match="not a color name or a #rrggbb"):
+        parse(src, return_types="harness")
+
+
+def test_review_c_diamond_include(tmp_path: Path):
+    _write(tmp_path / "common.yml", "connectors:\n  TERM: {pincount: 1}\n")
+    _write(
+        tmp_path / "a.yml", "include: [common.yml]\nconnectors:\n  XA: {pincount: 1}\n"
+    )
+    _write(
+        tmp_path / "b.yml", "include: [common.yml]\nconnectors:\n  XB: {pincount: 1}\n"
+    )
+    main = _write(
+        tmp_path / "m.yml",
+        "include: [a.yml, b.yml]\nconnections: [[TERM], [XA], [XB]]\n",
+    )
+    assert set(parse(main, return_types="harness").connectors) == {"TERM", "XA", "XB"}
+    _write(tmp_path / "c.yml", "connectors:\n  TERM: {pincount: 2}\n")
+    clash = _write(tmp_path / "n.yml", "include: [a.yml, c.yml]\nconnections: []\n")
+    with pytest.raises(ValueError, match=r"defined in both .*common\.yml and .*c\.yml"):
+        parse(clash, return_types="harness")
+
+
+def test_review_c_include_non_utf8_names_the_file(tmp_path: Path):
+    (tmp_path / "lib.yml").write_bytes(b"\x89PNG\r\n\x1a\n\xff\xfe")
+    main = _write(tmp_path / "m.yml", "include: [lib.yml]\n")
+    with pytest.raises(ValueError, match="lib.yml: not a UTF-8"):
+        parse(main, return_types="harness")
+
+
+def test_review_c_bare_reference_to_template_instance():
+    src = """
+connectors: {X1: {pincount: 5}, X2: {pincount: 5}}
+cables: {W: {}}
+connections:
+  - - X1: [1-2]
+    - W.W1
+    - X2: [1-2]
+  - - X1: [5]
+    - W1: [5]
+    - X2: [5]
+"""
+    h = parse(src, return_types="harness")
+    assert h.cables["W1"].wirecount == 5
+
+
+def test_review_c_bare_cable_hint_and_prepass_context():
+    src = """
+connectors: {X1: {pincount: 3}, X2: {pincount: 3}}
+cables: {W1: {colors: [RD, BK]}}
+connections:
+  - - X1: [1-3]
+    - W1
+    - X2: [1-3]
+"""
+    with pytest.raises(ValueError, match="cable named alone uses wires 1..n"):
+        parse(src, return_types="harness")
+    bad = "connectors: {X1: {pincount: 1}}\ncables: {W1: {}}\nconnections:\n  - - X1: {a: 1}\n    - W1\n"
+    with pytest.raises(Exception, match="connection set 1"):
+        parse(bad, return_types="harness")
+
+
+def test_review_c_cli_one_line_for_missing_weasyprint(
+    runner, tmp_path: Path, monkeypatch
+):
+    import wireviz.wv_sheet as ws
+    from wireviz.wv_cli import wireviz as cli
+
+    def missing():
+        raise ws.SheetPdfUnavailable('needs WeasyPrint: pip install "wireviz[pdf]"')
+
+    monkeypatch.setattr(ws, "_weasyprint", missing)
+    f = _write(tmp_path / "h.yml", MINIMAL)
+    result = runner.invoke(cli, ["-f", "D", str(f)])
+    assert result.exit_code == 1
+    assert (
+        'pip install "wireviz[pdf]"' in result.stderr
+        and "Traceback" not in result.stderr
+    )

From 8932e9fed693ae4ff2d78c7f7acfe5d24b5903e8 Mon Sep 17 00:00:00 2001
From: Cole Gentry <peapod2007@gmail.com>
Date: Fri, 2 Oct 2026 16:53:35 -0400
Subject: [PATCH 08/11] fix(security): address batch C review round 2 feedback

- sheet PDF child: runs with -c and sys.path[0] set to this package's
  root ('python -m' imported a 'wireviz' from the working directory);
  memory limited on POSIX; failures raise WireVizRenderError
- connection sets: a set that is not a list, an empty mapping or an
  empty list is a clear input error with set context (was IndexError /
  RuntimeError without context)
- shorts: pins x shorts over all connectors is capped (100 000 cells),
  so YAML aliases cannot multiply the label size
- include: a file reached twice adds its BOM items once (shared set
  through the recursion)
- CLI: catches WireVizRenderError and graphviz.ExecutableNotFound, not
  every RuntimeError
- %date%: an unquoted YAML date works; null or no metadata.date falls
  back to today
- the #508 hint names the real cable; tests spy the WeasyPrint fetcher
  and cover the cwd package, malformed sets, diamond BOM items
---
 docs/syntax.md                |   2 +-
 src/wireviz/Harness.py        |  20 +++++-
 src/wireviz/wireviz.py        |  17 +++--
 src/wireviz/wv_cli.py         |   6 +-
 src/wireviz/wv_errors.py      |   4 ++
 src/wireviz/wv_html.py        |   8 ++-
 src/wireviz/wv_include.py     |  14 ++--
 src/wireviz/wv_sheet.py       |  39 +++++++----
 tests/test_upstream_issues.py | 121 ++++++++++++++++++++++++++++++++--
 9 files changed, 196 insertions(+), 35 deletions(-)

diff --git a/docs/syntax.md b/docs/syntax.md
index 33f72561..72d29bf3 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -393,7 +393,7 @@ include:              # a file name or a list of file names
 - `connectors` and `cables` are merged by name. A definition in the including file wins over the same name in an included file. The same name in two included files is an error that names both files.
 - `additional_bom_items` from included files are added.
 - `metadata`, `options`, `tweak` and `connections` are allowed only in the main file.
-- Included files may include other files. A loop of includes is an error.
+- Included files may include other files. A loop of includes is an error. A file reached through two includes is merged once. If one included file overrides a name from a shared file that another include also uses, that is a conflict: move the override to the main file.
 - A relative `image: src:` in an included file is relative to that file.
 - Each file is read on its own, so YAML anchors (`&name`, `*name`, `<<:`) do not work across files.
 - A PNG output embeds the merged YAML, so it does not depend on the library files.
diff --git a/src/wireviz/Harness.py b/src/wireviz/Harness.py
index 33cf6f5a..17f8c12b 100644
--- a/src/wireviz/Harness.py
+++ b/src/wireviz/Harness.py
@@ -39,6 +39,7 @@
     pn_info_string,
 )
 from wireviz.wv_colors import get_color_hex, translate_color
+from wireviz.wv_errors import WireVizRenderError
 from wireviz.wv_gv_html import (
     html_bgcolor,
     html_bgcolor_attr,
@@ -214,6 +215,12 @@ def _dot_attr_value(value: str) -> str:
     return '"' + re.sub(r'(?<!\\)"', r'\\"', value) + '"'
 
 
+# Upper bound for pins x shorts summed over all connectors: each short adds
+# a table cell to every pin row, so YAML aliases could otherwise multiply a
+# few hundred bytes into hundreds of MB of DOT source.
+MAX_SHORT_CELLS = 100_000
+
+
 def short_spans(connector: Connector) -> List[tuple]:
     """Return (member rows, first row, last row, hex color) for each short
     of ``connector`` (upstream #350); computed once per connector."""
@@ -506,6 +513,15 @@ def create_graph(self) -> Graph:
             for colorstr in cable.colors
         )
 
+        short_cells_total = sum(
+            len(c.pins) * len(c.short_groups) for c in self.connectors.values()
+        )
+        if short_cells_total > MAX_SHORT_CELLS:
+            # each short is a column over every pin row (#350)
+            raise ValueError(
+                f"shorts: pins x shorts over all connectors is {short_cells_total}; "
+                f"the limit is {MAX_SHORT_CELLS}"
+            )
         for connector in self.connectors.values():
             if connector.style == "simple" and connector.short_groups:
                 sys.stderr.write(
@@ -1080,11 +1096,11 @@ def _pipe(self, fmt: str) -> bytes:
                 timeout=UNTRUSTED_RENDER_TIMEOUT,
             )
         except subprocess.TimeoutExpired as exc:
-            raise RuntimeError(
+            raise WireVizRenderError(
                 f"Graphviz did not finish within {UNTRUSTED_RENDER_TIMEOUT} s"
             ) from exc
         if result.returncode != 0:
-            raise RuntimeError(
+            raise WireVizRenderError(
                 "Graphviz failed: " + result.stderr.decode("utf-8", "replace").strip()
             )
         return result.stdout
diff --git a/src/wireviz/wireviz.py b/src/wireviz/wireviz.py
index baabcaf0..235634ca 100755
--- a/src/wireviz/wireviz.py
+++ b/src/wireviz/wireviz.py
@@ -350,6 +350,16 @@ def alternate_type():  # flip between connector and cable/arrow
         set_label = _describe_set(connection_set)  # before the set is rewritten
         bare_cables = set()  # cables named alone in this set (#508)
         try:
+            if not isinstance(connection_set, list):
+                raise ValueError("a connection set must be a list")
+            for entry in connection_set:
+                if isinstance(entry, dict) and len(entry) != 1:
+                    raise ValueError(
+                        "each mapping in a connection set needs exactly one "
+                        f"designator, not {len(entry)}"
+                    )
+                if isinstance(entry, list) and not entry:
+                    raise ValueError("a connection set entry is an empty list")
             # The steps below rewrite the set in place. A YAML alias (*name)
             # makes several sets share one list, so work on a private copy.
             connection_set = copy.deepcopy(connection_set)
@@ -548,12 +558,11 @@ def alternate_type():  # flip between connector and cable/arrow
             ):
                 raise
             message = f"connection set {set_number} ({set_label}): {exc}"
-            if "out of range" in str(exc) and any(
-                str(exc).startswith(f"{c}:") for c in bare_cables
-            ):
+            bare = [c for c in bare_cables if str(exc).startswith(f"{c}:")]
+            if "out of range" in str(exc) and bare:
                 message += (
                     " (a cable named alone uses wires 1..n since #508; "
-                    "list the wires, e.g. W1: [1, 1, 1], for the old meaning)"
+                    f"list the wires, e.g. {bare[0]}: [1, 1, 1], for the old meaning)"
                 )
             cls = WireVizError if type(exc) is Exception else type(exc)
             try:
diff --git a/src/wireviz/wv_cli.py b/src/wireviz/wv_cli.py
index 327636cd..02fca335 100644
--- a/src/wireviz/wv_cli.py
+++ b/src/wireviz/wv_cli.py
@@ -10,9 +10,12 @@
 if __name__ == "__main__":
     sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 
+from graphviz import ExecutableNotFound
+
 import wireviz.wireviz as wv
 from wireviz import APP_NAME, __version__
 from wireviz.Harness import read_yaml_from_png
+from wireviz.wv_errors import WireVizRenderError
 from wireviz.wv_helper import file_read_text
 
 format_codes = {
@@ -289,7 +292,8 @@ def wireviz(
                 TypeError,
                 yaml.YAMLError,
                 FileNotFoundError,
-                RuntimeError,
+                WireVizRenderError,  # Graphviz/WeasyPrint failed or is missing
+                ExecutableNotFound,  # Graphviz not installed
             )
             if debug or not (isinstance(exc, known) or type(exc) is Exception):
                 raise
diff --git a/src/wireviz/wv_errors.py b/src/wireviz/wv_errors.py
index fb3ea81f..6373fa44 100644
--- a/src/wireviz/wv_errors.py
+++ b/src/wireviz/wv_errors.py
@@ -9,3 +9,7 @@ class WireVizError(ValueError):
     Input errors that are already a ValueError or TypeError keep their
     class; the connection-set context is added to their message.
     """
+
+
+class WireVizRenderError(RuntimeError):
+    """An external renderer (Graphviz, WeasyPrint) failed or timed out."""
diff --git a/src/wireviz/wv_html.py b/src/wireviz/wv_html.py
index 7f6d1104..7d42097a 100644
--- a/src/wireviz/wv_html.py
+++ b/src/wireviz/wv_html.py
@@ -148,9 +148,6 @@ def svgdata() -> str:
         "<!-- %revision% -->": clean(_latest_revision(metadata)),
     }
 
-    if not (metadata and "date" in metadata):  # metadata.date wins
-        replacements["<!-- %date% -->"] = date.today().isoformat()
-
     def replacement_if_used(key: str, func: Callable[[], str]) -> None:
         """Append replacement only if used in html."""
         if key in html:
@@ -173,6 +170,8 @@ def replacement_if_used(key: str, func: Callable[[], str]) -> None:
             # attribute or style contexts in the templates.
             if untrusted and f"<!-- %{item}% -->" in replacements:
                 continue
+            if isinstance(contents, date):  # an unquoted YAML date
+                contents = contents.isoformat()
             if isinstance(contents, (str, int, float)):
                 replacements[f"<!-- %{item}% -->"] = clean(
                     html_line_breaks(str(contents))
@@ -190,6 +189,9 @@ def replacement_if_used(key: str, func: Callable[[], str]) -> None:
                     elif isinstance(entry, (str, int, float)):
                         pass  # TODO?: replacements[f"<!-- %{item}_{category}% -->"] = html_line_breaks(str(entry))
 
+    # metadata.date (if it gave a value) wins over today's date
+    replacements.setdefault("<!-- %date% -->", date.today().isoformat())
+
     # perform replacements
     # regex replacement adapted from:
     # https://gist.github.com/bgusach/a967e0587d6e01e889fd1d776c5f3729
diff --git a/src/wireviz/wv_include.py b/src/wireviz/wv_include.py
index 2802353e..7343a773 100644
--- a/src/wireviz/wv_include.py
+++ b/src/wireviz/wv_include.py
@@ -34,6 +34,7 @@ def resolve_includes(
     base_dir: Path,
     include_paths: Sequence[Union[str, Path]] = (),
     _stack: Optional[List[Path]] = None,
+    _seen: Optional[set] = None,
 ) -> Dict[tuple, Path]:
     """Merge the files named in ``yaml_data["include"]`` into ``yaml_data``
     (in place). Return {(section, key): file that defines it} for every
@@ -53,7 +54,7 @@ def resolve_includes(
             f"include: nesting is deeper than {MAX_INCLUDE_DEPTH} levels ({stack[-1]})"
         )
 
-    seen_files = set()
+    seen = _seen if _seen is not None else set()  # files whose BOM items are in
     main_keys = {
         section: set(yaml_data.get(section) or {}) for section in MERGED_SECTIONS
     }
@@ -69,6 +70,10 @@ def resolve_includes(
         except UnicodeDecodeError as exc:
             raise ValueError(f"include {path}: not a UTF-8 YAML file") from exc
         data = yaml_load(text)
+        if isinstance(data, dict) and real in seen:
+            # reached before (a diamond): its BOM items are already in
+            data["additional_bom_items"] = []
+        seen.add(real)
         if data is None:
             data = {}
         if not isinstance(data, dict):
@@ -78,7 +83,9 @@ def resolve_includes(
                 raise ValueError(
                     f"include {path}: {section} is allowed only in the main file"
                 )
-        nested = resolve_includes(data, path.parent, include_paths, [*stack, real])
+        nested = resolve_includes(
+            data, path.parent, include_paths, [*stack, real], seen
+        )
         _absolute_images(data, path.parent)
 
         for section in MERGED_SECTIONS:
@@ -102,9 +109,6 @@ def resolve_includes(
                 origin[(section, key)] = defined_in
                 target[key] = attribs
         extra = data.get("additional_bom_items") or []
-        if real in seen_files:
-            extra = []  # a file reached twice adds its BOM items once
-        seen_files.add(real)
         if extra:
             yaml_data["additional_bom_items"] = list(
                 yaml_data.get("additional_bom_items") or []
diff --git a/src/wireviz/wv_sheet.py b/src/wireviz/wv_sheet.py
index 172282da..e8494d26 100644
--- a/src/wireviz/wv_sheet.py
+++ b/src/wireviz/wv_sheet.py
@@ -18,8 +18,10 @@
 from pathlib import Path
 from typing import Optional
 
+from wireviz.wv_errors import WireVizRenderError
 
-class SheetPdfUnavailable(RuntimeError):
+
+class SheetPdfUnavailable(WireVizRenderError):
     """WeasyPrint is not installed or cannot load its system libraries."""
 
 
@@ -41,36 +43,47 @@ def _render(html: str) -> bytes:
     return weasyprint.HTML(string=html, url_fetcher=fetcher).write_pdf()
 
 
+def _limit_memory() -> None:  # runs in the child before exec (POSIX)
+    try:
+        import resource
+
+        limit = 2 * 1024**3
+        resource.setrlimit(resource.RLIMIT_AS, (limit, limit))
+    except Exception:
+        pass  # not supported on this platform (e.g. macOS); timeout still applies
+
+
 def html_to_pdf(html: str, timeout: Optional[float] = None) -> bytes:
     """Render the WireViz HTML output to a PDF document."""
     if timeout is None:
         return _render(html)
     _weasyprint()  # fail early, with the install hint, in this process
-    # The child must import this same wireviz package.
+    # -c, with sys.path[0] set to this package's root: "python -m" would put
+    # the working directory first and could import a different "wireviz".
     package_root = str(Path(__file__).resolve().parent.parent)
-    env = {
-        **os.environ,
-        "PYTHONPATH": os.pathsep.join(
-            p for p in (package_root, os.environ.get("PYTHONPATH")) if p
-        ),
-    }
+    code = (
+        "import sys; sys.path[0] = " + repr(package_root) + "; "
+        "from wireviz.wv_sheet import _main; _main()"
+    )
     try:
         result = subprocess.run(
-            [sys.executable, "-m", "wireviz.wv_sheet"],
+            [sys.executable, "-c", code],
             input=html.encode("utf-8"),
             capture_output=True,
             timeout=timeout,
-            env=env,
+            preexec_fn=_limit_memory if os.name == "posix" else None,
         )
     except subprocess.TimeoutExpired as exc:
-        raise RuntimeError(f"The sheet PDF did not finish within {timeout} s") from exc
+        raise WireVizRenderError(
+            f"The sheet PDF did not finish within {timeout} s"
+        ) from exc
     if result.returncode != 0:
         detail = result.stderr.decode("utf-8", "replace").strip().splitlines()
-        raise RuntimeError(
+        raise WireVizRenderError(
             "The sheet PDF failed" + (f": {detail[-1]}" if detail else "")
         )
     return result.stdout
 
 
-if __name__ == "__main__":  # child process for html_to_pdf(timeout=...)
+def _main() -> None:  # child process for html_to_pdf(timeout=...)
     sys.stdout.buffer.write(_render(sys.stdin.buffer.read().decode("utf-8")))
diff --git a/tests/test_upstream_issues.py b/tests/test_upstream_issues.py
index b4ca7be1..8185ae50 100644
--- a/tests/test_upstream_issues.py
+++ b/tests/test_upstream_issues.py
@@ -1059,17 +1059,32 @@ def spy(self, url, *a, **k):
     assert fetched and all(u.startswith("data:") for u in fetched)
 
 
-def test_review_c_sheet_never_fetches_files(weasyprint_ok, monkeypatch):
-    import urllib.request
+def test_review_c_sheet_never_fetches_files(weasyprint_ok):
+    """Only data: URLs may be fetched; file: and http: are refused by the
+    fetcher itself (spied, not inferred from the output)."""
+    import unittest.mock as mock
+
+    from weasyprint.urls import URLFetcher
 
     from wireviz.wv_sheet import html_to_pdf
 
-    def refuse(*a, **k):
-        raise AssertionError("WeasyPrint tried to open a URL")
+    calls = []
+    original = URLFetcher.fetch
+
+    def spy(self, url, *a, **k):
+        try:
+            result = original(self, url, *a, **k)
+        except Exception:
+            calls.append((url.split(":")[0], "refused"))
+            raise
+        calls.append((url.split(":")[0], "fetched"))
+        return result
 
-    monkeypatch.setattr(urllib.request, "urlopen", refuse)
     html = '<html><body><img src="file:///etc/hosts"><img src="http://example.invalid/x.png"></body></html>'
-    assert html_to_pdf(html).startswith(b"%PDF")
+    with mock.patch.object(URLFetcher, "fetch", spy):
+        assert html_to_pdf(html).startswith(b"%PDF")
+    assert ("file", "fetched") not in calls and ("http", "fetched") not in calls
+    assert ("file", "refused") in calls
 
 
 def test_review_c_untrusted_sheet_runs_with_timeout(weasyprint_ok, monkeypatch):
@@ -1169,3 +1184,97 @@ def missing():
         'pip install "wireviz[pdf]"' in result.stderr
         and "Traceback" not in result.stderr
     )
+
+
+# ---------------------------------------------------------------------------
+# Batch C review round 2
+# ---------------------------------------------------------------------------
+
+
+def test_review_c2_sheet_child_ignores_cwd_package(
+    weasyprint_ok, tmp_path: Path, monkeypatch
+):
+    """The untrusted sheet child must import this wireviz, not a package
+    named wireviz in the working directory."""
+    fake = tmp_path / "wireviz"
+    fake.mkdir()
+    (fake / "__init__.py").write_text("")
+    (fake / "wv_sheet.py").write_text(
+        "import sys\ndef _main():\n    sys.stdout.write('%PDF-fake')\n"
+    )
+    monkeypatch.chdir(tmp_path)
+    h = parse(MINIMAL, return_types="harness", untrusted=True)
+    pdf = h._render(("sheet",))["sheet"]
+    assert pdf.startswith(b"%PDF-1") and b"fake" not in pdf
+
+
+@pytest.mark.parametrize(
+    "connections, message",
+    [
+        ("[[X1: [1], {}, X2: [1]]]", "exactly one designator"),
+        ("[{X1: [1]}]", "a connection set must be a list"),
+        ("[[X1: [1], [], X2: [1]]]", "empty list"),
+    ],
+)
+def test_review_c2_malformed_connection_sets(connections: str, message: str):
+    src = f"connectors: {{X1: {{pincount: 1}}, X2: {{pincount: 1}}}}\nconnections: {connections}\n"
+    with pytest.raises(ValueError, match=f"connection set 1 .*{message}"):
+        parse(src, return_types="harness")
+
+
+def test_review_c2_shorts_cell_budget():
+    shorts = ", ".join(f"[{2 * i + 1}, {2 * i + 2}]" for i in range(64))
+    entries = "\n".join(f"  X{i}: *c" for i in range(2, 10))
+    src = (
+        f"connectors:\n  X1: &c {{pincount: 2000, shorts: [{shorts}]}}\n{entries}\n"
+        "connections: [[X1]]\n"
+    )
+    h = parse(src, return_types="harness")
+    with pytest.raises(ValueError, match="pins x shorts"):
+        h.graph
+
+
+def test_review_c2_diamond_include_bom_items_once(tmp_path: Path):
+    _write(
+        tmp_path / "common.yml",
+        "additional_bom_items:\n  - {description: Common item, qty: 1}\n",
+    )
+    _write(tmp_path / "b.yml", "include: [common.yml]\n")
+    _write(tmp_path / "c.yml", "include: [common.yml]\n")
+    main = _write(
+        tmp_path / "m.yml",
+        "include: [b.yml, c.yml]\nconnectors: {X1: {pincount: 1}}\nconnections: [[X1]]\n",
+    )
+    h = parse(main, return_types="harness")
+    assert [i["description"] for i in h.additional_bom_items] == ["Common item"]
+
+
+def test_review_c2_bare_string_instance_reference():
+    src = """
+connectors: {X1: {pincount: 3}, X2: {pincount: 3}}
+cables: {K: {}}
+connections:
+  - - X1: [1]
+    - K.K1: [1]
+    - X2: [1]
+  - - X1: [1-3]
+    - K1
+    - X2: [1-3]
+"""
+    h = parse(src, return_types="harness")
+    assert h.cables["K1"].wirecount == 3
+    assert [c.via_port for c in h.cables["K1"].connections] == [1, 1, 2, 3]
+
+
+@pytest.mark.parametrize(
+    "value, shown", [("2024-01-02", "2024-01-02"), ("'v2'", "v2"), ("null", None)]
+)
+def test_review_c2_date_placeholder(tmp_path: Path, value: str, shown):
+    from datetime import date
+
+    (tmp_path / "t.html").write_text("<html><body>[<!-- %date% -->]</body></html>")
+    src = f"metadata: {{date: {value}, template: {{name: t}}}}\nconnectors: {{X1: {{pincount: 1}}}}\nconnections: [[X1]]\n"
+    page = parse(src, return_types="harness", source_path=tmp_path / "x.yml")._render(
+        ("html",), template_dir=tmp_path
+    )["html"]
+    assert f"[{shown or date.today().isoformat()}]" in page

From 627ecebfc684190effd41aa6df37d24c033c5d2d Mon Sep 17 00:00:00 2001
From: Cole Gentry <peapod2007@gmail.com>
Date: Fri, 2 Oct 2026 18:50:41 -0400
Subject: [PATCH 09/11] =?UTF-8?q?fix(deps):=20wireviz[pdf]=20needs=20Pytho?=
 =?UTF-8?q?n=203.10+=20(WeasyPrint=2070)=20=E2=80=94=20fixes=20CI=20on=203?=
 =?UTF-8?q?.9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/CHANGELOG.md | 2 +-
 docs/README.md    | 2 +-
 setup.py          | 3 ++-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index ce22fec0..8b5e296c 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -30,7 +30,7 @@ Fixes for open issues in the original [wireviz/WireViz](https://github.com/wirev
 
 ### New features
 
-- Print-ready sheet PDF: `-f D` / `output_formats="sheet"` writes `<name>.sheet.pdf`, the HTML page (frame, diagram, BOM, title block) on one page at the template's sheet size. Needs `pip install "wireviz[pdf]"` (WeasyPrint 70 or later); WeasyPrint may load only the inline `data:` images, never a file or URL, and in untrusted mode it runs in a child process with the render timeout. The `din-6771` template no longer lets the diagram overlap the BOM and title block, prints at the right page size, and defaults to A4; the simple template fits the diagram to the page when printed. New `<!-- %date% -->` placeholder ([#32](https://github.com/wireviz/WireViz/issues/32), [#304](https://github.com/wireviz/WireViz/issues/304)).
+- Print-ready sheet PDF: `-f D` / `output_formats="sheet"` writes `<name>.sheet.pdf`, the HTML page (frame, diagram, BOM, title block) on one page at the template's sheet size. Needs `pip install "wireviz[pdf]"` (WeasyPrint 70 or later, Python 3.10 or later); WeasyPrint may load only the inline `data:` images, never a file or URL, and in untrusted mode it runs in a child process with the render timeout. The `din-6771` template no longer lets the diagram overlap the BOM and title block, prints at the right page size, and defaults to A4; the simple template fits the diagram to the page when printed. New `<!-- %date% -->` placeholder ([#32](https://github.com/wireviz/WireViz/issues/32), [#304](https://github.com/wireviz/WireViz/issues/304)).
 - Connector `shorts: [[1, 2, 3], {YE: [N, AUX]}]` shows internal shorts and jumpers as a bar in the pin table; shorted pins count as populated ([#350](https://github.com/wireviz/WireViz/issues/350)).
 - Cable `twisted: [[RD, BK], {wires: [3, 4], rate: 20/m}]` shows twisted pairs, triads and groups as framed groups in the cable box ([#3](https://github.com/wireviz/WireViz/issues/3), [#353](https://github.com/wireviz/WireViz/issues/353)).
 - `include:` merges shared connector/cable libraries from other files; `-I/--include-path` adds search directories ([#220](https://github.com/wireviz/WireViz/issues/220)). Not allowed in untrusted mode.
diff --git a/docs/README.md b/docs/README.md
index f00afb54..54777730 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -144,7 +144,7 @@ $ wireviz ~/path/to/files/*.yml
 
 ### Print-ready PDF sheet
 
-`wireviz -f D harness.yml` writes `harness.sheet.pdf`: the HTML page (diagram, BOM and, with the `din-6771` template, frame and title block) as a one-page PDF at the template's sheet size (`metadata.template.sheetsize`: A4, A3 or A2). It needs WeasyPrint:
+`wireviz -f D harness.yml` writes `harness.sheet.pdf`: the HTML page (diagram, BOM and, with the `din-6771` template, frame and title block) as a one-page PDF at the template's sheet size (`metadata.template.sheetsize`: A4, A3 or A2). It needs Python 3.10 or later and WeasyPrint:
 
 ```
 $ pip install "wireviz[pdf]"
diff --git a/setup.py b/setup.py
index ce9e0c41..4b42ab7c 100644
--- a/setup.py
+++ b/setup.py
@@ -26,7 +26,8 @@
     ],
     extras_require={
         # print-ready sheet PDF (-f D); also needs the Pango system library
-        "pdf": ["weasyprint>=70"],
+        # (WeasyPrint 70 needs Python 3.10 or later)
+        "pdf": ["weasyprint>=70; python_version >= '3.10'"],
     },
     license="GPLv3",
     keywords="cable connector hardware harness wiring wiring-diagram wiring-harness",

From a38a1a838f4d72ae218ca1f511059457b86ce1c5 Mon Sep 17 00:00:00 2001
From: Cole Gentry <peapod2007@gmail.com>
Date: Fri, 2 Oct 2026 19:43:56 -0400
Subject: [PATCH 10/11] ci: install libharfbuzz-subset0 and require the sheet
 PDF tests on Python 3.10+

WeasyPrint installed but did not load on the runner, so all 8 sheet tests
were skipped. CI now installs the missing library and sets
WIREVIZ_REQUIRE_PDF, which turns that skip into a failure with the
reason (pytest -rs).
---
 .github/workflows/tests.yml   | 8 ++++++--
 tests/test_upstream_issues.py | 3 +++
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index c628e894..7d7982cf 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -23,8 +23,12 @@ jobs:
       - name: Install package + test dependencies
         run: |
           python -m pip install --upgrade pip
-          sudo apt-get install -y libpango-1.0-0 libpangoft2-1.0-0
+          sudo apt-get install -y libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0
           pip install ".[pdf]"
           pip install pytest
       - name: Run pytest
-        run: pytest -v
+        # WeasyPrint 70 needs Python 3.10+: there, the sheet PDF tests must
+        # run, not skip (a library missing on the runner fails them).
+        env:
+          WIREVIZ_REQUIRE_PDF: ${{ matrix.python-version != '3.9' && '1' || '' }}
+        run: pytest -v -rs
diff --git a/tests/test_upstream_issues.py b/tests/test_upstream_issues.py
index 8185ae50..4bba2dd6 100644
--- a/tests/test_upstream_issues.py
+++ b/tests/test_upstream_issues.py
@@ -5,6 +5,7 @@
 upstream issues is in ``docs/plans/2026-10-02-upstream-issue-triage.md``.
 """
 
+import os
 from pathlib import Path
 
 import pytest
@@ -960,6 +961,8 @@ def weasyprint_ok():
     try:
         import weasyprint  # noqa: F401
     except Exception as exc:
+        if os.environ.get("WIREVIZ_REQUIRE_PDF"):
+            pytest.fail(f"WIREVIZ_REQUIRE_PDF is set, but WeasyPrint does not load: {exc}")
         pytest.skip(f"WeasyPrint (wireviz[pdf]) not available: {exc}")
 
 

From f46785835c7d9ed378b1f10e8b026856466d2b07 Mon Sep 17 00:00:00 2001
From: Cole Gentry <peapod2007@gmail.com>
Date: Fri, 2 Oct 2026 19:44:05 -0400
Subject: [PATCH 11/11] chore(release): version 1.1.0

---
 docs/CHANGELOG.md       | 2 +-
 src/wireviz/__init__.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 8b5e296c..615258c0 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## [Unreleased]
+## [1.1.0] (2026-10-02)
 
 Fixes for open issues in the original [wireviz/WireViz](https://github.com/wireviz/WireViz) repository. Triage: [docs/plans/2026-10-02-upstream-issue-triage.md](plans/2026-10-02-upstream-issue-triage.md).
 
diff --git a/src/wireviz/__init__.py b/src/wireviz/__init__.py
index 05aa22fe..d1a01bf3 100644
--- a/src/wireviz/__init__.py
+++ b/src/wireviz/__init__.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # Please don't import anything in this file to avoid issues when it is imported in setup.py
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 
 CMD_NAME = "wireviz"  # Lower case command and module name
 APP_NAME = "WireViz"  # Application name in texts meant to be human readable