py2max 0.3.1__tar.gz → 0.3.3__tar.gz

{py2max-0.3.1 → py2max-0.3.3}/CHANGELOG.md

@@ -2,6 +2,118 @@
 
 ## [Unreleased]
 
+## [0.3.3]
+
+### Removed: `serve` and `repl` CLI subcommands
+
+- The `py2max serve` and `py2max repl` subcommands -- thin stubs that only pointed at the separate `py2max-server` package since v0.3.0 -- have been removed. The interactive live editor and remote REPL still live in `py2max-server` (`pip install py2max-server`).
+
+### Fixed: Graph layouts (`graph:*`) are overlap-free and open on-screen
+
+- `GraphLayoutManager` now runs the dimension-aware overlap sweep (`prevent_overlaps`) after placement, so constraint/force engines no longer leave large UI objects (e.g. `scope~` at 130x130) overlapping their neighbours -- matching the guarantee the grid/flow managers already gave.
+- The patcher window is grown to enclose the laid-out graph plus a margin, so `optimize_layout()` output opens with the whole graph visible instead of spilling past the default 640x480 canvas (the window never shrinks below the default).
+
+### Fixed: Clustered grid layout squashed object sizes
+
+- The connection-aware clustering path of `GridLayoutManager` (`cluster_connected=True`) still wrote the manager's uniform 66x22 size back onto every clustered object, squashing UI objects (`scope~`, `ezdac~`, `dial`, ...) to text-box size. It now preserves each object's real width/height, matching the already-fixed non-clustered path.
+
+### Fixed: Example patches use valid Max connections
+
+- The layout example scripts (`tests/examples/layout/`) and matrix-layout tests wired control objects (`metro`, `loadbang`) straight into oscillator signal inlets, which Max rejects ("error connecting outlet ... to ... inlet"). They now use the correct idiom -- a float number box sets the oscillator frequency, `metro` triggers envelopes, and envelopes modulate amplitude through a `*~` VCA -- so the generated demo patches load cleanly.
+
+### New: `kwds_filter` utility
+
+- Added `py2max.utils.kwds_filter(kwds, **elems)`: returns `kwds` merged with the `elems` whose value is not `None` (legitimate falsy values such as `0` / `""` are kept, and the input is not mutated). Lets a method keep an optional parameter in its signature but omit it from the forwarded `**kwds` when the caller leaves it unset.
+
+### Improved: Build and test-output hygiene
+
+- Coverage HTML now writes to `build/coverage-html` and the test suite writes its artifacts under `build/test-output/` -- both within the git-ignored `build/` tree -- instead of a tracked `outputs/` directory. A new `make test-outputs` target writes all test artifacts flat into `build/test-outputs/` for quick inspection.
+
+## [0.3.2]
+
+### New: Patch editing and removal API
+
+- Loading a patch (`Patcher.from_dict` / `load`) now restores all ID-generation state -- object, node, edge, and semantic-ID counters -- so `add_*` calls made after a load no longer collide with existing object IDs. This fixes the headline "edit an existing patch" round-trip, which previously emitted duplicate IDs on the first post-load add.
+- Added a removal / editing API with referential-integrity cleanup: `remove_line` / `disconnect`, `remove_box` / `remove`, and `replace`. Removing a box also prunes its dangling patchlines and clears the associated node/edge/index bookkeeping, so no orphaned lines or stale IDs are left behind.
+
+### New: Graph-layout engines as layout managers
+
+- Three optional graph-layout backends -- HOLA (`hola-graph`), COLA plus force-directed / geometric layouts (`graph-layout`), and OGDF's layered / force-directed / planar layouts (`ogdf-py`) -- are now selectable as first-class layout managers via `layout="graph:<algo>"` (e.g. `graph:hola`, `graph:cola`, `graph:ogdf-sugiyama`). Because these algorithms need the whole graph, positions are applied on `optimize_layout()` rather than as each box is added, and each box's width/height is preserved so UI objects are not squashed. Eleven algorithms are available: `hola`, `cola`, `sugiyama`, `fruchterman-reingold`, `kamada-kawai`, `spectral`, `circular`, `shell`, `ogdf-sugiyama`, `ogdf-fmmm`, `ogdf-planarization`.
+- The engines are lazy-imported inside the manager, so `import py2max` still pulls **zero runtime dependencies**; a missing backend raises a clear error naming the package to install. Install with `pip install "py2max[graph]"` -- the `graph` extra now also bundles `hola-graph` alongside `graph-layout` and `ogdf-py`. Implemented as `GraphLayoutManager` in `py2max/layout/external.py`.
+
+### New: Layout gallery generator and docs page
+
+- `scripts/gen_layout_gallery.py` (run via `make gallery`) renders every supported graph layout over one shared sample patch to transparent SVGs under `docs/assets/imgs/`, using py2max's own SVG exporter so the results are directly comparable. Backends that are not installed are skipped rather than failing the run.
+- A new published **Layout Gallery** page (`docs/user_guide/layout_gallery.md`, linked in the User Guide navigation) shows the rendered layouts and documents the `graph:<algo>` layout-manager API. The older networkx / graphviz / tsmpy experiments were dropped in favor of the three maintained backends.
+- The generator also renders py2max's **built-in** managers (grid, flow, columnar, matrix) via `optimize_layout()` -- no external dependencies -- and the **Layout Managers** guide (`docs/user_guide/layout_managers.md`) now embeds these as inline visuals so each layout strategy can be seen, not just described.
+
+### Fixed: Generation correctness
+
+- `add_coll` / `add_dict` / `add_table` no longer discard a caller-supplied `text` argument when `name` is `None` (an operator-precedence bug that let the fallback string win).
+- `add_beap` strips the `.maxpat` suffix correctly; previously `rstrip(".maxpat")` could truncate names such as `drum.maxpat` down to `dru`.
+- Parallel patchlines between the same source and destination now receive incrementing `order` values, so they spread apart in Max instead of overlapping.
+- Comments created with `comment=` are emitted on every save path (`save_as`, `to_json`, `to_dict`), not only `save()` / `optimize_layout()`.
+- Hand-typed objects that are not in the built-in defaults now get one outlet instead of zero, so they can act as a connection source.
+- Load/save round-trip no longer injects `autosave` / `dependency_cache` defaults into nested subpatchers the source patch did not have; patches containing subpatchers now round-trip faithfully.
+
+### Fixed: Layout managers
+
+- `layout="columnar"` now works; it previously raised `NotImplementedError` despite being documented.
+- Layout optimizers preserve each object's real width and height. UI objects (`scope~`, `dial`, `slider`, `function`, `live.*`, comments) are no longer squashed to text-box size by `optimize_layout()`.
+- The managers now share a single directed-graph model (`PatchGraph`) rather than re-deriving adjacency from patchlines in each manager, and object classification no longer carries contradictory category assignments (its context inference uses maxref signal typing with word-boundary matching).
+
+### Improved: maxref bundle loading (lazy and thread-safe)
+
+- In bundle mode (no local Max install), the shipped catalog is no longer eagerly materialized into the cache on first access. The name-to-source map still loads once, but each object is now built from the in-memory bundle on demand, so a single-object query no longer constructs all ~1175 entries. A bundle object whose cache slot is empty is re-materialized from the bundle rather than returning nothing.
+- The process-wide maxref cache is now thread-safe: an `RLock` guards the lazy refdict / category-map initialization and cache population, so concurrent `Box.help()` / validation lookups no longer race on first load or mutate the cache unsafely.
+
+### Fixed: maxref outlet digests and parser robustness
+
+- Outlet `<digest>` text is now extracted symmetrically with inlets. A condition bug previously required the `<outlet>` element to have leading text and then stored that text instead of the digest, so outlet descriptions were dropped for almost every object (~2000 digests across ~1093 objects). `Box.help()` / `get_info()` now report outlet descriptions. The shipped offline `bundle.json.gz` was regenerated so bundle-mode users (Linux/Windows/no-Max) get the corrected data.
+- A raw `&` in reference prose no longer drops the whole object on parse. Ampersands that do not begin a valid XML entity are escaped before parsing, hardening against `.maxref.xml` markup variations across Max versions (valid entities like `&amp;`, `&quot;`, `&#181;` are left intact).
+
+### Improved: Cross-platform maxref discovery
+
+- Reference-page resolution now honors the `PY2MAX_MAX_REFPAGES` environment override on all platforms and auto-discovers a Windows `refpages` directory, so Windows users with Max installed read live reference data instead of always falling back to the bundled snapshot. A wheel-build test now asserts the offline `bundle.json.gz` actually ships in the built artifact.
+
+### Improved: SVG preview fidelity
+
+- The SVG exporter (`Patcher.to_svg` / `py2max preview`) now renders a more faithful preview instead of a uniform grey schematic:
+  - **Box colors are honored.** Colors set via `Box.set_color` / `apply_theme` (`bgcolor`, `bordercolor`, `textcolor`) are drawn, converted from Max's `[r, g, b, a]` floats to CSS.
+  - **UI objects get recognizable affordances** rather than an identical rectangle: message boxes draw the right-edge flag notch, `toggle` an X, `button` a circle, number boxes (`flonum` / `number`) the left triangle marker, `dial` a circle with a pointer, and `slider` a thumb bar.
+  - **Ports resolve from the box's own `numinlets` / `numoutlets`** (what is written to the `.maxpat`) rather than a maxref lookup. Ports therefore render correctly for objects maxref does not know and without a Max install, and patchline endpoints line up with the ports they connect to (both use the same counts).
+- `export_svg_string` now builds the document in memory instead of round-tripping through a temporary file.
+
+### Fixed: Layout classification and overlap resolution
+
+- Object classification (matrix / columnar layouts) is now factored into a clear precedence -- curated functional intent, then maxref signal typing for the unknown audio tail, then name patterns -- with the rationale documented. Curated sets must win because functional categories do not map to raw signal I/O (even `cycle~` exposes a signal inlet, so signal typing alone would call it a processor; `adc~` is an input though it is a signal source). The dead, never-effective `_refine_column_assignments_by_flow` no-op and its call site were removed.
+- `LayoutManager.prevent_overlaps` now converges. The previous version cached each object's rect before mutating it (so pushes stopped accumulating) and clamped boxes back inside the canvas (re-introducing the overlaps it had just removed), leaving dense layouts overlapping at the 50-iteration cap. It is replaced with a monotone sweep that pushes each object clear of already-placed ones along the axis of least penetration; it converges in a few passes, early-exits when nothing overlaps, and preserves each object's real size.
+
+### Improved: Patch transformers
+
+- `run_pipeline` now delegates to `compose`, removing a duplicated apply loop and giving the previously-unused (but exported) `compose` helper a real use.
+- The `add-comment` transformer's position is now reachable from the CLI: prefix the value with `above|below|left|right:` to place the comment (e.g. `--apply "add-comment=below:tempo"`), defaulting to `above`. A leading token that is not a position is kept as comment text, so `"note: hi"` is left intact.
+- Added two transformers backed by existing APIs: `apply-theme` (apply a named color theme -- `light` / `dark` / `blue` / `high-contrast`) and `scale-positions` (scale every object's x/y position by a factor, sizes unchanged).
+
+### Fixed: Converters module cleanup
+
+- Importing `py2max.export.converters` no longer constructs a `Patcher` as an import-time side effect (which pulled in maxref, layout, etc.). The default-attribute set is now computed lazily on first use and cached. Also removed a dead `_infer_category` helper and an unreachable `NotImplementedError` guard (the caller strips subpatcher dicts before that path).
+
+### Removed: Honest CLI help for the moved `serve` / `repl` subcommands
+
+- The `serve` and `repl` subcommands (whose implementations moved to `py2max-server` in 0.3.0) no longer advertise themselves as live in `--help`; they now removed.
+
+### Removed: MaxRefDB deprecated alias methods
+
+- Removed 12 long-deprecated `MaxRefDB` aliases in favor of the canonical API: `populate_from_maxref` / `populate_all_*` -> `populate([category=...])`, `search_objects` -> `search`, `get_objects_by_category` -> `by_category`, `get_all_categories` -> `.categories`, `get_object_count` -> `.count`, and `export_to_json` / `import_from_json` -> `export` / `load`. The database module is already off the import path (lazily loaded, stdlib-only), so this only trims its API surface. Callers, tests, and docs were updated to the canonical names.
+- While updating the SQLite demo scripts, also fixed two pre-existing broken examples: `from py2max import MaxRefDB` (correct: `from py2max.maxref import MaxRefDB`) and `create_database(...)` used as a free function (it is `MaxRefDB.create_database(...)`). Both `tests/examples/db/` scripts now run.
+
+### Removed: Obsolete layout experiments and vendored editor assets
+
+- Deleted the old graph-layout experiment tests (`tests/test_layout_hola{1,2,3}`, `test_layout_hola_graph`, `test_layout_networkx{1,2}`, `test_layout_nx_graphviz`, `test_layout_nx_orthogonal`, `test_layout_nx_tsmpy`). They exercised backends that are no longer supported (raw adaptagrams, networkx, pygraphviz, tsmpy) or duplicated the new `GraphLayoutManager` coverage, and only ever skipped. The maintained path is covered by `tests/test_layout_graph_manager.py`.
+- Removed the vendored browser libraries under `docs/js/` (SVG.js, WebCola, D3) -- reference copies for the interactive editor that moved to the separate `py2max-server` package in 0.3.0 -- and the stale Sphinx build output under `docs/build/` that predated the MkDocs migration and was being copied into the published site.
+- Pruned 30 obsolete design notes from the `docs/notes/` dev journal (REPL, SSE/WebSocket live-preview server, and interactive SVG-editor implementation notes), all for features that moved to `py2max-server`. The 13 still-relevant library/journal notes were kept.
+
 ## [0.3.1]
 
 ### New: Standalone `gen.codebox~` Support

{py2max-0.3.1 → py2max-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py2max
-Version: 0.3.1
+Version: 0.3.3
 Summary: A library for offline generation of Max/MSP patcher (.maxpat) files.
 Keywords: Max,maxpat,offline
 Author: Shakeeb Alireza
@@ -21,6 +21,9 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Classifier: Typing :: Typed
+Requires-Dist: graph-layout>=0.4 ; extra == 'graph'
+Requires-Dist: ogdf-py>=0.3 ; python_full_version >= '3.10' and extra == 'graph'
+Requires-Dist: hola-graph>=0.1 ; extra == 'graph'
 Maintainer: Shakeeb Alireza
 Maintainer-email: Shakeeb Alireza <shakfu@users.noreply.github.com>
 Requires-Python: >=3.9
@@ -29,6 +32,7 @@ Project-URL: Documentation, https://github.com/shakfu/py2max#readme
 Project-URL: Repository, https://github.com/shakfu/py2max.git
 Project-URL: Issues, https://github.com/shakfu/py2max/issues
 Project-URL: Changelog, https://github.com/shakfu/py2max/blob/main/CHANGELOG.md
+Provides-Extra: graph
 Description-Content-Type: text/markdown
 
 # py2max
@@ -172,7 +176,7 @@ p.save()
 
 ### MaxRef Integration
 
-Access documentation for 1157 Max objects:
+Access documentation for 1175 Max objects:
 
 ```python
 p = Patcher('demo.maxpat')
@@ -216,10 +220,10 @@ osc = p.find_by_id('cycle_1')
 Query Max object metadata efficiently:
 
 ```python
-from py2max import MaxRefDB
+from py2max.maxref import MaxRefDB
 
 db = MaxRefDB()  # Auto-cached on first use
-print(len(db))   # 1157 objects
+print(len(db))   # 1175 objects
 
 if 'cycle~' in db:
     info = db['cycle~']

{py2max-0.3.1 → py2max-0.3.3}/README.md

@@ -139,7 +139,7 @@ p.save()
 
 ### MaxRef Integration
 
-Access documentation for 1157 Max objects:
+Access documentation for 1175 Max objects:
 
 ```python
 p = Patcher('demo.maxpat')
@@ -183,10 +183,10 @@ osc = p.find_by_id('cycle_1')
 Query Max object metadata efficiently:
 
 ```python
-from py2max import MaxRefDB
+from py2max.maxref import MaxRefDB
 
 db = MaxRefDB()  # Auto-cached on first use
-print(len(db))   # 1157 objects
+print(len(db))   # 1175 objects
 
 if 'cycle~' in db:
     info = db['cycle~']

{py2max-0.3.1 → py2max-0.3.3}/py2max/__init__.py

@@ -35,7 +35,7 @@ Example:
     >>> p.save()
 """
 
-__version__ = "0.3.1"
+__version__ = "0.3.3"
 
 from .core import Box, Patcher, Patchline
 from .exceptions import (

{py2max-0.3.1 → py2max-0.3.3}/py2max/cli.py

@@ -148,6 +148,7 @@ def _generate_test_source(name: str, data: Dict[str, Any]) -> str:
 
 
 def cmd_new(args: argparse.Namespace) -> int:
+    """Create a new, empty patcher file at the given path."""
     path = Path(args.path)
     if path.exists() and not args.force:
         print(f"Refusing to overwrite existing file: {path}", file=sys.stderr)
@@ -179,6 +180,7 @@ def cmd_new(args: argparse.Namespace) -> int:
 
 
 def cmd_info(args: argparse.Namespace) -> int:
+    """Print a summary of a patcher file (object and connection counts)."""
     path = Path(args.path)
     patcher = Patcher.from_file(path)
     _coerce_rect(patcher)
@@ -201,6 +203,7 @@ def cmd_info(args: argparse.Namespace) -> int:
 
 
 def cmd_optimize(args: argparse.Namespace) -> int:
+    """Re-run layout optimization on a patcher and write the result."""
     input_path = Path(args.input)
     save_path = Path(args.output) if args.output else input_path
 
@@ -222,6 +225,7 @@ def cmd_optimize(args: argparse.Namespace) -> int:
 
 
 def cmd_validate(args: argparse.Namespace) -> int:
+    """Validate a patcher's connections against maxref inlet/outlet metadata."""
     path = Path(args.path)
     patcher = Patcher.from_file(path)
     _coerce_rect(patcher)
@@ -272,6 +276,7 @@ def _parse_transform_spec(spec: str) -> tuple[str, str | None]:
 
 
 def cmd_transform(args: argparse.Namespace) -> int:
+    """Apply one or more transformers to a patcher (or list available ones)."""
     if args.list_transformers:
         for name, desc in available_transformers().items():
             print(f"{name}: {desc}")
@@ -316,6 +321,7 @@ def cmd_transform(args: argparse.Namespace) -> int:
 
 
 def cmd_convert(args: argparse.Namespace) -> int:
+    """Convert between formats (e.g. .maxpat to Python, maxref to SQLite)."""
     if args.mode == "maxpat-to-python":
         if not args.input or not args.output:
             print(
@@ -636,19 +642,6 @@ def cmd_db_cache(args: argparse.Namespace) -> int:
         return 1
 
 
-def cmd_serve(args: argparse.Namespace) -> int:
-    """The interactive server moved to the separate py2max-server package."""
-    target = getattr(args, "input", None) or "<patch.maxpat>"
-    print(
-        "The interactive server has moved to the separate 'py2max-server' package.\n"
-        "Install it and use its CLI instead:\n"
-        "    pip install py2max-server\n"
-        f"    py2max-server serve {target}",
-        file=sys.stderr,
-    )
-    return 1
-
-
 def cmd_preview(args: argparse.Namespace) -> int:
     """Generate SVG preview of a patcher."""
     import tempfile
@@ -695,20 +688,8 @@ def cmd_preview(args: argparse.Namespace) -> int:
         return 1
 
 
-def cmd_repl(args: argparse.Namespace) -> int:
-    """The remote REPL moved to the separate py2max-server package."""
-    target = getattr(args, "server", None) or "localhost:9000"
-    print(
-        "The remote REPL has moved to the separate 'py2max-server' package.\n"
-        "Install it and use its CLI instead:\n"
-        "    pip install py2max-server\n"
-        f"    py2max-server repl {target}",
-        file=sys.stderr,
-    )
-    return 1
-
-
 def cmd_maxref(args: argparse.Namespace) -> int:
+    """Query the Max object reference (list objects or show one's details)."""
     cache = MaxRefCache()
 
     if args.list:
@@ -783,6 +764,7 @@ def cmd_maxref(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
+    """Construct the top-level argument parser with all subcommands."""
     parser = argparse.ArgumentParser(
         prog="py2max", description="Utilities for working with Max patchers."
     )
@@ -836,33 +818,6 @@ def build_parser() -> argparse.ArgumentParser:
     val_parser.add_argument("path", help="Target .maxpat path")
     val_parser.set_defaults(func=cmd_validate)
 
-    serve_parser = subparsers.add_parser(
-        "serve", help="Start interactive server with live preview"
-    )
-    serve_parser.add_argument("input", help="Input .maxpat file")
-    serve_parser.add_argument(
-        "--port",
-        type=int,
-        default=8000,
-        help="HTTP server port (default: 8000, WebSocket on port+1)",
-    )
-    serve_parser.add_argument(
-        "--no-open", action="store_true", help="Don't automatically open browser"
-    )
-    serve_parser.add_argument(
-        "--no-save", action="store_true", help="Disable auto-save on changes"
-    )
-    serve_parser.add_argument(
-        "--repl",
-        action="store_true",
-        help="Start interactive REPL for live patch editing",
-    )
-    serve_parser.add_argument(
-        "--log-file",
-        help="Redirect server logs to file (enables single-terminal REPL mode when used with --repl)",
-    )
-    serve_parser.set_defaults(func=cmd_serve)
-
     preview_parser = subparsers.add_parser(
         "preview", help="Generate SVG preview of a patcher"
     )
@@ -1094,26 +1049,11 @@ def build_parser() -> argparse.ArgumentParser:
     )
     cache_clear.set_defaults(func=cmd_db)
 
-    # REPL client command
-    repl_parser = subparsers.add_parser("repl", help="Connect to remote REPL server")
-    repl_parser.add_argument(
-        "server",
-        nargs="?",
-        default="localhost:9000",
-        help="Server address (default: localhost:9000)",
-    )
-    repl_parser.add_argument(
-        "--token",
-        default=None,
-        help="Session token printed by the server "
-        "(or set PY2MAX_REPL_TOKEN). Required for authentication.",
-    )
-    repl_parser.set_defaults(func=cmd_repl)
-
     return parser
 
 
 def main(argv: List[str] | None = None) -> int:
+    """CLI entry point: parse ``argv`` and dispatch to the subcommand handler."""
     parser = build_parser()
     args = parser.parse_args(argv)
 

{py2max-0.3.1 → py2max-0.3.3}/py2max/core/abstract.py

@@ -60,6 +60,8 @@ class AbstractBox(ABC):
     id: Optional[str]
     maxclass: str
     patching_rect: Rect
+    numinlets: int
+    numoutlets: int
     _kwds: Dict[str, Any]
 
     @abstractmethod
@@ -135,8 +137,6 @@ class AbstractPatcher(ABC):
     _lines: list[AbstractPatchline]
     _edge_ids: list[tuple[str, str]]
     _id_counter: int = 0
-    _link_counter: int = 0
-    _last_link: Optional[tuple[str, str]]
     _reset_on_render: bool
     _flow_direction: str
     _cluster_connected: bool

{py2max-0.3.1 → py2max-0.3.3}/py2max/core/factory.py

@@ -325,14 +325,13 @@ class BoxFactoryMixin(AbstractPatcher):
                     inlet=dst_inlet,
                 )
 
-        # get order of lines between same pair of objects
-        if (src_id, dst_id) == self._last_link:
-            self._link_counter += 1
-        else:
-            self._link_counter = 0
-            self._last_link = (src_id, dst_id)
-
-        order = self._link_counter
+        # Order of lines between the same pair of objects: Max uses it to fan
+        # parallel wires apart. Derive it from the connections that currently
+        # exist for this (src, dst) pair rather than a single-slot memo of the
+        # last link -- the memo reset ``order`` to 0 whenever any other
+        # connection intervened, collapsing parallel wires (and it also could
+        # not account for lines restored from a loaded patch).
+        order = sum(1 for pl in self._lines if pl.src == src_id and pl.dst == dst_id)
         src, dst = [src_id, src_outlet], [dst_id, dst_inlet]
         patchline = Patchline(source=src, destination=dst, order=order)
         self._lines.append(patchline)
@@ -447,7 +446,11 @@ class BoxFactoryMixin(AbstractPatcher):
                 text=text,
                 maxclass=maxclass or "newobj",
                 numinlets=numinlets if numinlets is not None else 1,
-                numoutlets=numoutlets if numoutlets is not None else 0,
+                # An object with no maxref entry gets one outlet by default (not
+                # zero): a zero-outlet object cannot act as a connection source,
+                # which is wrong for the hand-typed long-tail objects that land
+                # here. Matches Box.__init__'s default.
+                numoutlets=numoutlets if numoutlets is not None else 1,
                 outlettype=outlettype if outlettype is not None else [""],
                 patching_rect=patching_rect,
                 **kwds,
@@ -1011,6 +1014,155 @@ class BoxFactoryMixin(AbstractPatcher):
         if edge in self._edge_ids:
             self._edge_ids.remove(edge)
 
+    @staticmethod
+    def _as_box_id(box: "Union[Box, str]") -> str:
+        """Resolve a Box or id string to its id."""
+        return box.id if isinstance(box, Box) else box  # type: ignore[return-value]
+
+    def remove_line(self, line: "Patchline") -> None:
+        """Remove a specific patchline connection from the patcher."""
+        self._drop_line(line)
+
+    def disconnect(
+        self,
+        src: "Union[Box, str]",
+        dst: "Union[Box, str]",
+        outlet: int = 0,
+        inlet: int = 0,
+    ) -> int:
+        """Remove connection(s) between ``src`` and ``dst``.
+
+        Removes every patchline from ``src[outlet]`` to ``dst[inlet]`` and
+        returns how many were removed (0 if none matched). ``src``/``dst`` may be
+        Box objects or their ids.
+
+        Example:
+            >>> p.add_line(osc, gain)
+            >>> p.disconnect(osc, gain)
+            1
+        """
+        src_id = self._as_box_id(src)
+        dst_id = self._as_box_id(dst)
+        matches = [
+            cast(Patchline, pl)
+            for pl in self._lines
+            if pl.src == src_id
+            and pl.dst == dst_id
+            and cast(Patchline, pl).source[1] == outlet
+            and cast(Patchline, pl).destination[1] == inlet
+        ]
+        for line in matches:
+            self._drop_line(line)
+        return len(matches)
+
+    def remove_box(self, box: "Union[Box, str]") -> Optional["Box"]:
+        """Remove a box and every patchline connected to it.
+
+        Accepts a Box or its id. Drops all incident patchlines, the box's entry
+        in the object map / node index, and any pending associated comment for
+        it. Returns the removed Box, or None if it was not present.
+
+        Example:
+            >>> osc = p.add_textbox('cycle~ 440')
+            >>> p.remove_box(osc)
+        """
+        box_id = self._as_box_id(box)
+
+        for line in [pl for pl in self._lines if pl.src == box_id or pl.dst == box_id]:
+            self._drop_line(line)
+
+        removed = self._objects.pop(box_id, None)
+        target = box if isinstance(box, Box) else removed
+        if target in self._boxes:
+            self._boxes.remove(target)
+        if box_id in self._node_ids:
+            self._node_ids.remove(box_id)
+        self._pending_comments = [
+            pc for pc in self._pending_comments if pc[0] != box_id
+        ]
+        return cast(Optional["Box"], target)
+
+    # alias for remove_box
+    remove = remove_box
+
+    def replace(
+        self,
+        old: "Union[Box, str]",
+        new: "Union[Box, str]",
+        **kwds: Any,
+    ) -> "Box":
+        """Replace a box in place, preserving its position and connections.
+
+        ``old`` (a Box or its id) is swapped for ``new`` -- either the text for a
+        replacement object (created with its Max-class defaults) or an
+        already-built Box. The replacement takes ``old``'s slot and window
+        position, and every patchline incident to ``old`` is rewired to it,
+        keeping the same outlet/inlet indices and connection order. Any pending
+        associated comment for ``old`` transfers to the replacement. Returns the
+        new Box.
+
+        Ports are preserved by index: if the replacement has fewer inlets/outlets
+        than the original, wires to the now-missing ports are kept as-is rather
+        than silently dropped here (Max drops them on load).
+
+        Example:
+            >>> osc = p.add('cycle~ 440')
+            >>> p.add_line(osc, gain)
+            >>> saw = p.replace(osc, 'saw~ 220')  # saw~ inherits osc's wiring
+        """
+        old_id = self._as_box_id(old)
+        old_box = self._objects.get(old_id)
+        if old_box is None:
+            raise KeyError(f"cannot replace unknown box {old_id!r}")
+
+        box_idx = self._boxes.index(old_box)
+        node_idx = self._node_ids.index(old_id) if old_id in self._node_ids else None
+        ox, oy, _, _ = old_box.patching_rect
+
+        # Build the replacement. add_box/add_textbox appends it at the end; it is
+        # relocated into old's slot after rewiring. Keep the replacement's own
+        # width/height but move it to old's window position.
+        if isinstance(new, Box):
+            if new.id is None:
+                new.id = self.get_id(new.maxclass)
+            _, _, nw, nh = new.patching_rect
+            new.patching_rect = Rect(ox, oy, nw, nh)
+            new_box = self.add_box(new)
+        else:
+            new_box = self.add_textbox(new, **kwds)
+            _, _, nw, nh = new_box.patching_rect
+            new_box.patching_rect = Rect(ox, oy, nw, nh)
+
+        new_id = new_box.id
+        assert new_id
+
+        # Rewire every incident patchline to the new box, preserving port indices
+        # and order, then rebuild the edge index to match.
+        for line in self._lines:
+            pl = cast(Patchline, line)
+            if pl.source and pl.source[0] == old_id:
+                pl.source = [new_id, pl.source[1]]
+            if pl.destination and pl.destination[0] == old_id:
+                pl.destination = [new_id, pl.destination[1]]
+        self._edge_ids = [(pl.src, pl.dst) for pl in self._lines]
+
+        # Transfer any pending associated comment from old to new.
+        self._pending_comments = [
+            (new_id if bid == old_id else bid, text, pos)
+            for (bid, text, pos) in self._pending_comments
+        ]
+
+        # Drop the old box and move the replacement into its original slot so
+        # ordering is preserved (add_* had appended it at the end).
+        del self._objects[old_id]
+        self._boxes.remove(new_box)  # drop the end-appended copy
+        self._boxes[box_idx] = new_box  # overwrite old_box in its slot
+        if node_idx is not None:
+            self._node_ids.remove(new_id)
+            self._node_ids[node_idx] = new_id
+
+        return new_box
+
     def encapsulate(
         self, boxes: "Iterable[Box]", text: str = "p subpatch", **kwds: Any
     ) -> "Box":
@@ -1241,9 +1393,8 @@ class BoxFactoryMixin(AbstractPatcher):
         return self.add_box(
             Box(
                 id=id or self.get_id("coll"),
-                text=text or f"coll {name} @embed {embed}"
-                if name
-                else f"coll @embed {embed}",
+                text=text
+                or (f"coll {name} @embed {embed}" if name else f"coll @embed {embed}"),
                 maxclass="newobj",
                 numinlets=1,
                 numoutlets=4,
@@ -1280,9 +1431,8 @@ class BoxFactoryMixin(AbstractPatcher):
         return self.add_box(
             Box(
                 id=id or self.get_id("dict"),
-                text=text or f"dict {name} @embed {embed}"
-                if name
-                else f"dict @embed {embed}",
+                text=text
+                or (f"dict {name} @embed {embed}" if name else f"dict @embed {embed}"),
                 maxclass="newobj",
                 numinlets=2,
                 numoutlets=4,
@@ -1329,9 +1479,12 @@ class BoxFactoryMixin(AbstractPatcher):
         return self.add_box(
             Box(
                 id=id or self.get_id(table_type),
-                text=text or f"{table_type} {name} @embed {embed}"
-                if name
-                else f"{table_type} @embed {embed}",
+                text=text
+                or (
+                    f"{table_type} {name} @embed {embed}"
+                    if name
+                    else f"{table_type} @embed {embed}"
+                ),
                 maxclass="newobj",
                 numinlets=2,
                 numoutlets=2,
@@ -1488,5 +1641,5 @@ class BoxFactoryMixin(AbstractPatcher):
     def add_beap(self, name: str, **kwds: Any) -> "Box":
         """Add a beap bpatcher object."""
 
-        _varname = name if ".maxpat" not in name else name.rstrip(".maxpat")
+        _varname = name if ".maxpat" not in name else name.removesuffix(".maxpat")
         return self.add_bpatcher(name=name, varname=_varname, extract=1, **kwds)