UndoStack

Generic undo stack with clone-on-push semantics. The PHP port of pi-tui's `UndoStack<S>`. Stores deep clones of state snapshots so the caller can mutate the working state freely without worrying that popping a past snapshot will alias to the current one. PHP has no `structuredClone()` (JS does), so deep cloning is done via `serialize()`/`unserialize()` — which handles arrays, scalars, and any serializable object. For objects that are NOT serializable (closures, resources, …) the caller should pass only POD state (arrays of primitives) to the stack, which is the expected use case for editor/input undo (text + cursor position). Pure state holder — not a renderer, not a contract. An editor or text-input key handler owns one instance, pushes a snapshot before each mutating operation, and pops on `Ctrl+Z` / `Ctrl+Y`.

public function push(?mixed $state): void

Pushes a deep clone of `$state` onto the stack.

Parameters

public function pop(): ?mixed

Pops and returns the most recent snapshot, or `null` if empty. The returned snapshot is already detached (it was cloned on push), so no re-cloning is needed.

public function clear(): void

public function length(): int

How many states the stack currently holds.