[set_dead] improve docs

masque/builder/builder.py

@@ -275,6 +275,10 @@ class Builder(PortList):
         Returns:
             self
 
+        Note:
+            If the builder is 'dead' (see `set_dead()`), geometry generation is
+            skipped but ports are still updated.
+
         Raises:
             `PortError` if any ports specified in `map_in` or `map_out` do not
                 exist in `self.ports` or `other_names`.
@@ -350,6 +354,10 @@ class Builder(PortList):
         Returns:
             self
 
+        Note:
+            If the builder is 'dead' (see `set_dead()`), geometry generation is
+            skipped but ports are still updated.
+
         Raises:
             `PortError` if any ports specified in `map_in` or `map_out` do not
                 exist in `self.ports` or `other.ports`.
@@ -425,13 +433,18 @@ class Builder(PortList):
 
     def set_dead(self) -> Self:
         """
-        Disallows further changes through `plug()` or `place()`.
+        Suppresses geometry generation for subsequent `plug()` and `place()`
+        operations. Unlike a complete skip, the port state is still tracked
+        and updated, using 'best-effort' fallbacks for impossible transforms.
+        This allows a layout script to execute through problematic sections
+        while maintaining valid port references for downstream code.
+
         This is meant for debugging:
         ```
             dev.plug(a, ...)
             dev.set_dead()      # added for debug purposes
-            dev.plug(b, ...)    # usually raises an error, but now skipped
+            dev.plug(b, ...)    # usually raises an error, but now uses fallback port update
-            dev.plug(c, ...)    # also skipped
+            dev.plug(c, ...)    # also updated via fallback
             dev.pattern.visualize()     # shows the device as of the set_dead() call
         ```
 

masque/builder/pather.py

@@ -285,6 +285,12 @@ class Pather(Builder, PatherMixin):
         Returns:
             self
 
+        Note:
+            If the builder is 'dead', this operation will still attempt to update
+            the target port's location. If the pathing tool fails (e.g. due to an
+            impossible length), a dummy linear extension is used to maintain port
+            consistency for downstream operations.
+
         Raises:
             BuildError if `distance` is too small to fit the bend (if a bend is present).
             LibraryError if no valid name could be picked for the pattern.
@@ -359,6 +365,12 @@ class Pather(Builder, PatherMixin):
         Returns:
             self
 
+        Note:
+            If the builder is 'dead', this operation will still attempt to update
+            the target port's location. If the pathing tool fails (e.g. due to an
+            impossible length), a dummy linear extension is used to maintain port
+            consistency for downstream operations.
+
         Raises:
             BuildError if `distance` is too small to fit the s-bend (for nonzero jog).
             LibraryError if no valid name could be picked for the pattern.

masque/builder/renderpather.py

@@ -408,6 +408,12 @@ class RenderPather(PatherMixin):
         Returns:
             self
 
+        Note:
+            If the builder is 'dead', this operation will still attempt to update
+            the target port's location. If the pathing tool fails (e.g. due to an
+            impossible length), a dummy linear extension is used to maintain port
+            consistency for downstream operations.
+
         Raises:
             BuildError if `distance` is too small to fit the bend (if a bend is present).
             LibraryError if no valid name could be picked for the pattern.
@@ -486,6 +492,12 @@ class RenderPather(PatherMixin):
         Returns:
             self
 
+        Note:
+            If the builder is 'dead', this operation will still attempt to update
+            the target port's location. If the pathing tool fails (e.g. due to an
+            impossible length), a dummy linear extension is used to maintain port
+            consistency for downstream operations.
+
         Raises:
             BuildError if `distance` is too small to fit the s-bend (for nonzero jog).
             LibraryError if no valid name could be picked for the pattern.

masque/pattern.py

@@ -1133,7 +1133,10 @@ class Pattern(PortList, AnnotatableImpl, Mirrorable):
             append: If `True`, `other` is appended instead of being referenced.
                 Note that this does not flatten  `other`, so its refs will still
                 be refs (now inside `self`).
-            skip_geometry: If `True`, only ports are added; geometry is skipped.
+            skip_geometry: If `True`, the operation only updates the port list and
+                skips adding any geometry (shapes, labels, or references). This
+                allows the pattern assembly to proceed for port-tracking purposes
+                even when layout generation is suppressed.
 
         Returns:
             self
@@ -1282,7 +1285,11 @@ class Pattern(PortList, AnnotatableImpl, Mirrorable):
                 any other ptypte. Non-allowed ptype connections will emit a
                 warning. Order is ignored, i.e. `(a, b)` is equivalent to
                 `(b, a)`.
-            skip_geometry: If `True`, only ports are updated; geometry is skipped.
+            skip_geometry: If `True`, only ports are updated and geometry is
+                skipped. If a valid transform cannot be found (e.g. due to
+                misaligned ports), a 'best-effort' dummy transform is used
+                to ensure new ports are still added at approximate locations,
+                allowing downstream routing to continue.
 
         Returns:
             self