build

class Build:
    """The page being built: its open stacks, innermost last, and its title so far."""

    _active: ClassVar[ContextVar[Build | None]] = ContextVar("page_build", default=None)

    def __init__(self) -> None:
        """A build with no stack open yet; nothing attaches until one is pushed."""
        self.stacks: list[Stack] = []
        self.title: str | None = None
        self._token: Token[Build | None] | None = None

    @classmethod
    def current(cls) -> Build:
        """The active build.

        Raises:
            RuntimeError: If no ``PageBuilder`` function is running.
        """
        build = cls._active.get()
        if build is None:
            raise RuntimeError(
                "no page is being built — open a stack or set a title inside a function "
                "decorated with @cg.ui.PageBuilder()"
            )
        return build

    @classmethod
    def attach(cls, component: Component) -> None:
        """Add a freshly built ``component`` to the innermost open stack, if one is being built."""
        build = cls._active.get()
        if build is not None and build.stacks:
            build.stacks[-1].children.append(component)

    @classmethod
    def claim(cls, stack: Stack) -> None:
        """Take ``stack``'s given children back from the open stack they attached to."""
        build = cls._active.get()
        if build is None or not build.stacks:
            return
        given = {id(child) for child in stack.children}
        siblings = build.stacks[-1].children
        siblings[:] = [child for child in siblings if id(child) not in given]

    def push(self, stack: Stack) -> None:
        """Open ``stack``: components built from now on attach to it."""
        self.stacks.append(stack)

    def pop(self, stack: Stack) -> None:
        """Close ``stack``, which must be the innermost open one.

        Raises:
            RuntimeError: If another stack is still open inside it.
        """
        if self.stacks[-1] is not stack:
            raise RuntimeError(f"{type(stack).__name__} closed while a nested stack is still open")
        self.stacks.pop()

    def __enter__(self) -> Self:
        """Make this the active build."""
        self._token = self._active.set(self)
        return self

    def __exit__(self, *exc: object) -> None:
        """Restore whatever build was active before."""
        if self._token is not None:
            self._active.reset(self._token)
            self._token = None