tiptap-python-utils 0.4.0__tar.gz → 0.6.0__tar.gz

{tiptap_python_utils-0.4.0/src/tiptap_python_utils.egg-info → tiptap_python_utils-0.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: tiptap_python_utils
-Version: 0.4.0
-Summary: Python utilities for parsing, traversing, editing, and serializing TipTap JSON content.
+Version: 0.6.0
+Summary: Pure-Python utilities for processing TipTap JSON on the server side. Parse, traverse, edit, and serialize TipTap documents — no JavaScript bridge required. Zero runtime dependencies, Python 3.9+.
 Author: tiptap_python_utils contributors
 License: MIT License
         
@@ -56,23 +56,10 @@ Dynamic: license-file
 [![CI](https://github.com/tugkanpilka/tiptap-python-utils/actions/workflows/ci.yml/badge.svg)](https://github.com/tugkanpilka/tiptap-python-utils/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Python utilities for [TipTap](https://tiptap.dev) JSON content.
-
-`tiptap_python_utils` parses TipTap documents into typed, immutable Python
-nodes, preserves unknown/custom nodes for lossless round trips, and provides
-small helpers for traversal, immutable edits, visible text extraction, task
-queries, and shared-node synchronization.
-
-- **Zero runtime dependencies.** Standard library only.
-- **Python 3.9+.** Tested on 3.9, 3.10, 3.11, 3.12, 3.13.
-- **Lossless round trip.** Unknown node kinds and any extra fields are preserved.
-- **Immutable AST.** All mutations return new instances via a fluent selection API.
-
-## Install
-
-```bash
-pip install tiptap_python_utils
-```
+TipTap is a JavaScript editor. If your backend is Python and you need to
+process TipTap JSON — extract text, query tasks, sync shared nodes — this
+library does it in pure Python with zero dependencies. No JS bridge, no
+Node.js subprocess.
 
 ## Quick Start
 
@@ -94,8 +81,24 @@ raw = {
 updated = Content.require(raw).where_id("p1").leaf().text("New").dump()
 ```
 
+## Features
+
+- **Zero runtime dependencies.** Standard library only.
+- **Python 3.9+.** Tested on 3.9, 3.10, 3.11, 3.12, 3.13.
+- **Lossless round trip.** Unknown node kinds and any extra fields are preserved.
+- **Immutable AST.** All mutations return new instances via a fluent selection API.
+
+## Install
+
+```bash
+pip install tiptap_python_utils
+```
+
 ## Three Ways to Load a Document
 
+Pick a constructor by how much you trust the input — lenient, strict, or
+auto-wrapping a bare node into a `doc`.
+
 | Constructor | When to use | On invalid input |
 |---|---|---|
 | `Content.parse(raw)` | Lenient — `raw` may be `None`, a string, or a dict | Returns a `Content` with `root=None` |
@@ -104,7 +107,8 @@ updated = Content.require(raw).where_id("p1").leaf().text("New").dump()
 
 ## Lossless Round Trip
 
-Parsing never silently drops fields. Two mechanisms preserve information:
+Parsing never silently drops fields — custom nodes and unknown keys survive a
+parse-then-serialize cycle byte-for-byte. Two mechanisms preserve information:
 
 - `Node.extra` stores top-level keys that aren't part of the known schema
   (e.g. custom node attributes, vendor-specific keys).
@@ -125,7 +129,8 @@ assert Content.require(raw).to_dict() == raw  # byte-for-byte
 
 ## Typed Nodes
 
-Build typed nodes directly and serialize them back to TipTap-compatible JSON:
+Build typed nodes directly in Python and serialize them back to
+TipTap-compatible JSON.
 
 ```python
 from tiptap_python_utils import Content, Paragraph, Text
@@ -136,8 +141,8 @@ doc = Content.wrap(node.raw())
 
 ## Selection and Editing
 
-The fluent selection API is the single home for mutation. Selection methods
-return a new `Content`; the original is never mutated.
+The fluent selection API is the single home for mutation: every method returns
+a new `Content`, so the original is never mutated.
 
 ### Select by id or kind
 
@@ -149,6 +154,22 @@ content.where_id("p1")
 
 # By TipTap kind.
 content.of(kind.PARAGRAPH)
+
+# By an arbitrary predicate over every node (and its descendants).
+content.where(lambda node: getattr(node, "level", None) == 1)
+```
+
+### Generic queries
+
+`Selection` carries two predicate primitives that work for any kind, so you
+don't need a bespoke `has_heading_text`-style helper per node type:
+
+```python
+# Narrow a selection further.
+content.of(kind.HEADING).filter(lambda n: n.level == 2)
+
+# Existence check (short-circuits).
+content.of(kind.HEADING).any(lambda n: n.text.strip() == "Introduction")
 ```
 
 ### Atomic mutations
@@ -175,6 +196,11 @@ content.where_id("ul1").append({"type": "listItem", "attrs": {"id": "li-new"}, "
 # Append a node to the document root.
 content.append_root({"type": "paragraph", "attrs": {"id": "p2"}, "content": []})
 
+# Build-and-append in one call — works for any kind, stamps a fresh id when
+# none is given. Typed fields (e.g. Heading.level) hydrate correctly.
+content.append(kind.HEADING, "New section", attrs={"level": 2})
+content.append(kind.PARAGRAPH, "Body text", node_id="p3")
+
 # Replace a node by id (the replacement's attrs.id must match).
 content.replace_by_id("p1", {
     "type": "paragraph",
@@ -185,6 +211,9 @@ content.replace_by_id("p1", {
 
 ## Text Extraction
 
+Pull the visible plain text out of a document — useful for search indexing,
+word counts, or previews.
+
 ```python
 from tiptap_python_utils import Content, text_slices, visible_text, word_count
 
@@ -197,6 +226,9 @@ slices = text_slices(content, context=True)
 
 ## Tasks
 
+Query task lists in a document — find every task item or check whether any are
+still open.
+
 ```python
 from tiptap_python_utils import Content, has_open_tasks, open_tasks
 
@@ -219,6 +251,9 @@ task.shared_id          # sharedId attr, if any
 
 ## Shared-Node Synchronization
 
+Keep copies of the same logical node (linked by `sharedId`) in sync — collect
+canonical bodies, then rewrite every matching node from them.
+
 `Content.shared_families()` collects canonical bodies grouped by `sharedId` into
 a `SharedFamilies` value object. `Content.sync_shared(families)` rewrites every
 matching node in the document from those canonical bodies, preserving
@@ -257,17 +292,6 @@ Related helpers on `Content`:
 - `node.with_shared_id(sid)` — stamp a sharedId onto a node (returns a new node).
 - `new_shared_id()` — mint a fresh `shared-…` identifier.
 
-## Architecture (one paragraph)
-
-The package is layered: `contract` (key/kind/policy primitives) → `model`
-(immutable AST with a registry of node classes; unknown kinds round-trip via
-`Unknown`) → `codec` (raw I/O in `raw.py`, hydration in `reader.py`, dump in
-`writer.py`) → `walk` & `tree` (traversal + path-based replacement on the
-immutable tree) → `select` (fluent `Selection` — the single home for mutation)
-→ `content` (public facade) → `text` / `tasks` / `shared` (user-facing
-workflows built on `Content`). All nodes are `@dataclass(frozen=True)`;
-mutations return new instances.
-
 ## Public API
 
 Common imports are available from the package root:
@@ -281,6 +305,7 @@ from tiptap_python_utils import (
     Text,
     has_open_tasks,
     kind,
+    new_node_id,
     new_shared_id,
     open_tasks,
     text_slices,
@@ -289,35 +314,21 @@ from tiptap_python_utils import (
 )
 ```
 
-## Stability
-
-The project is pre-1.0; minor versions may include breaking changes. See
-[CHANGELOG.md](CHANGELOG.md) for what changed and when.
-
-## Development
-
-```bash
-python -m venv .venv
-. .venv/bin/activate
-python -m pip install -e ".[dev]"
-pytest -q
-```
-
-Build and validate a release artifact:
-
-```bash
-python -m build
-python -m twine check dist/*
-```
-
 ## Contributing
 
 Issues and pull requests are welcome. Please read
-[CONTRIBUTING.md](CONTRIBUTING.md) for the local setup and release checklist,
-and open an issue at
+[CONTRIBUTING.md](CONTRIBUTING.md) for the local setup, architecture overview,
+and release checklist, and open an issue at
 [github.com/tugkanpilka/tiptap-python-utils/issues](https://github.com/tugkanpilka/tiptap-python-utils/issues)
-before larger changes so we can align on the approach.
+before opening a pull request so we can align on the approach.
 
 ## License
 
 MIT — see [LICENSE](LICENSE).
+
+## Stability
+
+The project is pre-1.0; minor versions may include breaking changes. See
+[CHANGELOG.md](CHANGELOG.md) for what changed and when.
+</content>
+</invoke>

{tiptap_python_utils-0.4.0 → tiptap_python_utils-0.6.0}/README.md

@@ -5,23 +5,10 @@
 [![CI](https://github.com/tugkanpilka/tiptap-python-utils/actions/workflows/ci.yml/badge.svg)](https://github.com/tugkanpilka/tiptap-python-utils/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Python utilities for [TipTap](https://tiptap.dev) JSON content.
-
-`tiptap_python_utils` parses TipTap documents into typed, immutable Python
-nodes, preserves unknown/custom nodes for lossless round trips, and provides
-small helpers for traversal, immutable edits, visible text extraction, task
-queries, and shared-node synchronization.
-
-- **Zero runtime dependencies.** Standard library only.
-- **Python 3.9+.** Tested on 3.9, 3.10, 3.11, 3.12, 3.13.
-- **Lossless round trip.** Unknown node kinds and any extra fields are preserved.
-- **Immutable AST.** All mutations return new instances via a fluent selection API.
-
-## Install
-
-```bash
-pip install tiptap_python_utils
-```
+TipTap is a JavaScript editor. If your backend is Python and you need to
+process TipTap JSON — extract text, query tasks, sync shared nodes — this
+library does it in pure Python with zero dependencies. No JS bridge, no
+Node.js subprocess.
 
 ## Quick Start
 
@@ -43,8 +30,24 @@ raw = {
 updated = Content.require(raw).where_id("p1").leaf().text("New").dump()
 ```
 
+## Features
+
+- **Zero runtime dependencies.** Standard library only.
+- **Python 3.9+.** Tested on 3.9, 3.10, 3.11, 3.12, 3.13.
+- **Lossless round trip.** Unknown node kinds and any extra fields are preserved.
+- **Immutable AST.** All mutations return new instances via a fluent selection API.
+
+## Install
+
+```bash
+pip install tiptap_python_utils
+```
+
 ## Three Ways to Load a Document
 
+Pick a constructor by how much you trust the input — lenient, strict, or
+auto-wrapping a bare node into a `doc`.
+
 | Constructor | When to use | On invalid input |
 |---|---|---|
 | `Content.parse(raw)` | Lenient — `raw` may be `None`, a string, or a dict | Returns a `Content` with `root=None` |
@@ -53,7 +56,8 @@ updated = Content.require(raw).where_id("p1").leaf().text("New").dump()
 
 ## Lossless Round Trip
 
-Parsing never silently drops fields. Two mechanisms preserve information:
+Parsing never silently drops fields — custom nodes and unknown keys survive a
+parse-then-serialize cycle byte-for-byte. Two mechanisms preserve information:
 
 - `Node.extra` stores top-level keys that aren't part of the known schema
   (e.g. custom node attributes, vendor-specific keys).
@@ -74,7 +78,8 @@ assert Content.require(raw).to_dict() == raw  # byte-for-byte
 
 ## Typed Nodes
 
-Build typed nodes directly and serialize them back to TipTap-compatible JSON:
+Build typed nodes directly in Python and serialize them back to
+TipTap-compatible JSON.
 
 ```python
 from tiptap_python_utils import Content, Paragraph, Text
@@ -85,8 +90,8 @@ doc = Content.wrap(node.raw())
 
 ## Selection and Editing
 
-The fluent selection API is the single home for mutation. Selection methods
-return a new `Content`; the original is never mutated.
+The fluent selection API is the single home for mutation: every method returns
+a new `Content`, so the original is never mutated.
 
 ### Select by id or kind
 
@@ -98,6 +103,22 @@ content.where_id("p1")
 
 # By TipTap kind.
 content.of(kind.PARAGRAPH)
+
+# By an arbitrary predicate over every node (and its descendants).
+content.where(lambda node: getattr(node, "level", None) == 1)
+```
+
+### Generic queries
+
+`Selection` carries two predicate primitives that work for any kind, so you
+don't need a bespoke `has_heading_text`-style helper per node type:
+
+```python
+# Narrow a selection further.
+content.of(kind.HEADING).filter(lambda n: n.level == 2)
+
+# Existence check (short-circuits).
+content.of(kind.HEADING).any(lambda n: n.text.strip() == "Introduction")
 ```
 
 ### Atomic mutations
@@ -124,6 +145,11 @@ content.where_id("ul1").append({"type": "listItem", "attrs": {"id": "li-new"}, "
 # Append a node to the document root.
 content.append_root({"type": "paragraph", "attrs": {"id": "p2"}, "content": []})
 
+# Build-and-append in one call — works for any kind, stamps a fresh id when
+# none is given. Typed fields (e.g. Heading.level) hydrate correctly.
+content.append(kind.HEADING, "New section", attrs={"level": 2})
+content.append(kind.PARAGRAPH, "Body text", node_id="p3")
+
 # Replace a node by id (the replacement's attrs.id must match).
 content.replace_by_id("p1", {
     "type": "paragraph",
@@ -134,6 +160,9 @@ content.replace_by_id("p1", {
 
 ## Text Extraction
 
+Pull the visible plain text out of a document — useful for search indexing,
+word counts, or previews.
+
 ```python
 from tiptap_python_utils import Content, text_slices, visible_text, word_count
 
@@ -146,6 +175,9 @@ slices = text_slices(content, context=True)
 
 ## Tasks
 
+Query task lists in a document — find every task item or check whether any are
+still open.
+
 ```python
 from tiptap_python_utils import Content, has_open_tasks, open_tasks
 
@@ -168,6 +200,9 @@ task.shared_id          # sharedId attr, if any
 
 ## Shared-Node Synchronization
 
+Keep copies of the same logical node (linked by `sharedId`) in sync — collect
+canonical bodies, then rewrite every matching node from them.
+
 `Content.shared_families()` collects canonical bodies grouped by `sharedId` into
 a `SharedFamilies` value object. `Content.sync_shared(families)` rewrites every
 matching node in the document from those canonical bodies, preserving
@@ -206,17 +241,6 @@ Related helpers on `Content`:
 - `node.with_shared_id(sid)` — stamp a sharedId onto a node (returns a new node).
 - `new_shared_id()` — mint a fresh `shared-…` identifier.
 
-## Architecture (one paragraph)
-
-The package is layered: `contract` (key/kind/policy primitives) → `model`
-(immutable AST with a registry of node classes; unknown kinds round-trip via
-`Unknown`) → `codec` (raw I/O in `raw.py`, hydration in `reader.py`, dump in
-`writer.py`) → `walk` & `tree` (traversal + path-based replacement on the
-immutable tree) → `select` (fluent `Selection` — the single home for mutation)
-→ `content` (public facade) → `text` / `tasks` / `shared` (user-facing
-workflows built on `Content`). All nodes are `@dataclass(frozen=True)`;
-mutations return new instances.
-
 ## Public API
 
 Common imports are available from the package root:
@@ -230,6 +254,7 @@ from tiptap_python_utils import (
     Text,
     has_open_tasks,
     kind,
+    new_node_id,
     new_shared_id,
     open_tasks,
     text_slices,
@@ -238,35 +263,21 @@ from tiptap_python_utils import (
 )
 ```
 
-## Stability
-
-The project is pre-1.0; minor versions may include breaking changes. See
-[CHANGELOG.md](CHANGELOG.md) for what changed and when.
-
-## Development
-
-```bash
-python -m venv .venv
-. .venv/bin/activate
-python -m pip install -e ".[dev]"
-pytest -q
-```
-
-Build and validate a release artifact:
-
-```bash
-python -m build
-python -m twine check dist/*
-```
-
 ## Contributing
 
 Issues and pull requests are welcome. Please read
-[CONTRIBUTING.md](CONTRIBUTING.md) for the local setup and release checklist,
-and open an issue at
+[CONTRIBUTING.md](CONTRIBUTING.md) for the local setup, architecture overview,
+and release checklist, and open an issue at
 [github.com/tugkanpilka/tiptap-python-utils/issues](https://github.com/tugkanpilka/tiptap-python-utils/issues)
-before larger changes so we can align on the approach.
+before opening a pull request so we can align on the approach.
 
 ## License
 
 MIT — see [LICENSE](LICENSE).
+
+## Stability
+
+The project is pre-1.0; minor versions may include breaking changes. See
+[CHANGELOG.md](CHANGELOG.md) for what changed and when.
+</content>
+</invoke>

{tiptap_python_utils-0.4.0 → tiptap_python_utils-0.6.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tiptap_python_utils"
-version = "0.4.0"
-description = "Python utilities for parsing, traversing, editing, and serializing TipTap JSON content."
+version = "0.6.0"
+description = "Pure-Python utilities for processing TipTap JSON on the server side. Parse, traverse, edit, and serialize TipTap documents — no JavaScript bridge required. Zero runtime dependencies, Python 3.9+."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { file = "LICENSE" }

{tiptap_python_utils-0.4.0 → tiptap_python_utils-0.6.0}/src/tiptap_python_utils/__init__.py

@@ -1,5 +1,6 @@
 """Public API for TipTap JSON utilities."""
 
+from . import task
 from .contract import key, kind
 from .content import Content
 from .exceptions import TiptapValidationError
@@ -21,6 +22,7 @@ from .model import (
     registry,
 )
 from .contract.policy import content_id, is_parseable, node_id, tiptap_id
+from .identity import new_node_id
 from .select import Selection
 from .shared import SharedFamilies, fingerprint, new_shared_id
 from .tasks import has_open_tasks, open_tasks, syncable_tasks
@@ -58,11 +60,13 @@ __all__ = [
     "is_parseable",
     "key",
     "kind",
+    "new_node_id",
     "new_shared_id",
     "node_id",
     "open_tasks",
     "registry",
     "syncable_tasks",
+    "task",
     "text_slices",
     "tiptap_id",
     "visible_text",

{tiptap_python_utils-0.4.0 → tiptap_python_utils-0.6.0}/src/tiptap_python_utils/codec/__init__.py

@@ -8,6 +8,7 @@ from .raw import (
     require_object,
 )
 from .reader import (
+    build_node,
     read_children,
     read_doc,
     read_node,
@@ -16,6 +17,7 @@ from .reader import (
 from .writer import dump, dumps
 
 __all__ = [
+    "build_node",
     "dump",
     "dumps",
     "normalize_text",

tiptap_python_utils-0.6.0/src/tiptap_python_utils/codec/reader.py

@@ -0,0 +1,95 @@
+"""Raw TipTap JSON → typed AST hydration."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+from ..contract import key, kind
+from ..exceptions import TiptapValidationError
+from ..model import ContentTuple, Doc, Node, registry
+from ..model.payload import has_any_identity
+from .raw import require_object
+
+
+# Kinds that hold block/container children, never inline text directly.
+_TEXT_REJECTING_KINDS = frozenset(
+    {
+        kind.DOC,
+        kind.BULLET_LIST,
+        kind.ORDERED_LIST,
+        kind.TASK_LIST,
+        kind.LIST_ITEM,
+        kind.TASK_ITEM,
+        kind.BLOCKQUOTE,
+        kind.TABLE_CELL,
+    }
+)
+
+
+def read_doc(raw: Mapping[str, Any]) -> Doc | None:
+    """Read a raw TipTap document root."""
+    if raw.get(key.TYPE) != kind.DOC:
+        return None
+    parsed = read_node(raw)
+    return parsed if isinstance(parsed, Doc) else None
+
+
+def read_node(raw: Mapping[str, Any]) -> Node:
+    """Read a raw TipTap node by delegating to the registry."""
+    children = read_children(raw.get(key.CONTENT, []))
+    return registry.read(raw, children)
+
+
+def read_children(raw_children: Any) -> ContentTuple:
+    if not isinstance(raw_children, list):
+        return ()
+    return tuple(read_node(child) for child in raw_children if isinstance(child, dict))
+
+
+def build_node(
+    node_kind: str,
+    text: str = "",
+    *,
+    attrs: Optional[Dict[str, Any]] = None,
+    node_id: Optional[str] = None,
+) -> Node:
+    """Build any typed node from (kind, text, attrs) via the registry.
+
+    Constructs a minimal raw payload and hydrates it through ``read_node`` so
+    subclass-typed fields (e.g. ``Heading.level``) and ``present`` semantics
+    are derived the same way as when parsing real JSON. Pure: ``node_id`` is
+    only stamped when ``attrs`` carries no identity of its own.
+    """
+    merged = dict(attrs or {})
+    if node_id is not None and not has_any_identity(merged):
+        merged[key.ID] = node_id
+
+    raw: Dict[str, Any] = {key.TYPE: node_kind}
+    if merged:
+        raw[key.ATTRS] = merged
+    if text:
+        _attach_text(raw, node_kind, text)
+    return read_node(raw)
+
+
+def _attach_text(raw: Dict[str, Any], node_kind: str, text: str) -> None:
+    if node_kind == kind.TEXT:
+        raw[key.TEXT] = text
+    elif node_kind in _TEXT_REJECTING_KINDS:
+        raise TiptapValidationError(
+            f"Node kind '{node_kind}' cannot hold inline text content"
+        )
+    else:
+        raw[key.CONTENT] = [{key.TYPE: kind.TEXT, key.TEXT: text}]
+
+
+def read_node_input(node_or_raw: Any, *, label: str) -> Node:
+    """Read either a typed node or a raw node payload."""
+    if isinstance(node_or_raw, Node):
+        return node_or_raw
+
+    parsed = require_object(node_or_raw, label=label)
+    node = read_doc(parsed) if parsed.get(key.TYPE) == kind.DOC else read_node(parsed)
+    if node is None:
+        raise TiptapValidationError(f"{label} must be a valid TipTap node")
+    return node

{tiptap_python_utils-0.4.0 → tiptap_python_utils-0.6.0}/src/tiptap_python_utils/content.py

@@ -5,13 +5,14 @@ from __future__ import annotations
 import json
 from copy import deepcopy
 from dataclasses import dataclass
-from typing import Any, Dict, Iterator, Optional
+from typing import Any, Callable, Dict, Iterator, Optional
 
 from .exceptions import TiptapValidationError
 from .types import DocumentContent
 
 from . import codec
 from .contract import key, kind, policy
+from .identity import new_node_id
 from .model import (
     Blockquote,
     BulletList,
@@ -118,6 +119,9 @@ class Content:
             tuple(ref for ref in self.refs() if ref.node.kind == node_kind),
         )
 
+    def where(self, pred: Callable[[Node], bool]) -> Selection:
+        return Selection(self, tuple(self.refs())).filter(pred)
+
     def where_shared_id(self, shared_id: str) -> Selection:
         return Selection(
             self,
@@ -148,6 +152,19 @@ class Content:
             return self
         return Selection(self, refs).transform(families.merge)
 
+    def append(
+        self,
+        node_kind: str,
+        text: str = "",
+        *,
+        attrs: Optional[Dict[str, Any]] = None,
+        node_id: Optional[str] = None,
+    ) -> "Content":
+        node = codec.build_node(
+            node_kind, text, attrs=attrs, node_id=node_id or new_node_id()
+        )
+        return self.append_root(node)
+
     def append_root(self, node_or_raw: Any) -> "Content":
         return self.of(kind.DOC).append(node_or_raw)
 

tiptap_python_utils-0.6.0/src/tiptap_python_utils/identity.py

@@ -0,0 +1,9 @@
+"""Generic node identity primitives."""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+
+def new_node_id() -> str:
+    return uuid4().hex

{tiptap_python_utils-0.4.0 → tiptap_python_utils-0.6.0}/src/tiptap_python_utils/select/selection.py

@@ -43,6 +43,14 @@ class Selection:
         leaves = tuple(leaf for ref in self._refs for leaf in _first_text_descendant(ref))
         return Selection(self._content, leaves)
 
+    def filter(self, pred: Callable[[Node], bool]) -> "Selection":
+        """Narrow the selection to refs whose node matches ``pred``."""
+        return Selection(self._content, tuple(r for r in self._refs if pred(r.node)))
+
+    def any(self, pred: Callable[[Node], bool] = lambda _node: True) -> bool:
+        """True if any selected node matches ``pred`` (short-circuits)."""
+        return any(pred(r.node) for r in self._refs)
+
     def text(self, value: str) -> "Content":
         self._require_text_only("text")
         return self._apply(lambda node: node.with_text(value))