added AGENTS.md & DOCS

Author: dg

.gitattributes

@@ -1,8 +1,10 @@
 .gitattributes  export-ignore
 .github/        export-ignore
 .gitignore      export-ignore
+AGENTS.md       export-ignore
 ncs.*           export-ignore
 phpstan*.neon   export-ignore
+docs/           export-ignore
 tests/          export-ignore
 
 *.php*          diff=php

AGENTS.md

@@ -0,0 +1,59 @@
+# To My Agents!
+
+It is my fervent wish that this file guide every AI coding agent working with code in this repository.
+
+## Documentation
+
+Any distilled, agent-facing documentation for this package - how it works
+internally and the rationale behind key design decisions - lives in `docs/`.
+Consult it before non-trivial changes; it is the source of truth from which the
+public manual is distilled.
+
+Five small files, but a genuinely tricky core (tree + monitoring + lookup +
+cloning). Almost all the value is in `Component::refreshMonitors` and the cloning
+handshake - read `docs/internals.md` before touching them.
+
+## Project Overview
+
+**nette/component-model** is the foundational component architecture for the Nette
+Framework: a hierarchical system where components nest inside containers, are
+monitored for attach/detach events, and are addressed through a path-based lookup.
+Consumed by Forms and Application, not usually used directly.
+
+- **PHP Version**: 8.3 - 8.5
+- **Package**: `nette/component-model`
+
+## Essential Commands
+
+```bash
+# Run all tests
+composer tester        # or: vendor/bin/tester tests -s
+
+# Run a single test file
+php tests/ComponentModel/Container.getComponents.phpt
+
+# Static analysis (PHPStan level 8)
+composer phpstan
+```
+
+## Conventions
+
+- Every file starts with `declare(strict_types=1);`; Nette Coding Standard.
+- Tests are Nette Tester `.phpt` files; they usually define minimal component
+  classes (Button, ComponentX) inline. `tests/bootstrap.php` sets up autoloading
+  and provides a `Notes` helper for recording lifecycle events during a test.
+
+## Working in this repo
+
+- **Monitoring is a single-pass, live-mutation-safe walk with a precise order:**
+  `attached` fires top-down (ancestor→descendant), `detached` fires bottom-up, and
+  detach is depth-gated. The `$monitors` array is a per-type cache holding *both*
+  the `lookup()` result and the registered callbacks. This is the sharp edge -
+  see `docs/internals.md` and the ADR it references before changing it.
+- **Cloning re-homes children via a cross-instance handshake** (`Container::$cloning`
+  / `_isCloning()`), not a parameter. Standalone-cloning a child detaches it.
+- **A component name cannot contain `-`** (`#^[a-zA-Z0-9_]+$#`) because `-` is the
+  path separator; `getComponent('a-b-c')` descends into sub-containers.
+- **Components cannot be serialized** (`__serialize` throws by design).
+- **`getComponent()` return-type inference lives in `nette/phpstan-rules`**
+  (`GetComponentReturnTypeExtension`), not in phpDoc here - look there for types.

docs/decisions/2025-12-26 top-down-monitor-notifications.md

@@ -0,0 +1,72 @@
+# monitor() notifications fire top-down (ancestor → descendant)
+
+Status: accepted · 2025-12-26 (commit `b4e82e1`) · BC break in 4.0
+
+## Context
+
+Callbacks registered via `monitor()` were historically invoked bottom-up on
+attach: descendants first, then their ancestors. The old algorithm also worked
+in two phases - it first walked the tree collecting the callbacks to run, and
+only then fired them.
+
+That had two flaws:
+
+1. **Callbacks fired even for components no longer in the tree.** If an earlier
+   callback (typically an ancestor's) had meanwhile removed a component from the
+   tree, its already-collected callback still ran, referencing an ancestor the
+   component was not actually attached to.
+2. **An ancestor could not "prepare the ground" for its descendants.**
+   Descendants were notified before the ancestor, so they could not rely on the
+   ancestor having finished its own initialization against a shared ancestor
+   (e.g. a Presenter).
+
+## Decision
+
+Notifications fire **top-down** (ancestor to descendant), and the algorithm
+works **live**, without a collection phase. The implementation in
+`Component::refreshMonitors()` explicitly handles tree mutation during listener
+execution:
+
+- a listener may modify the tree (remove itself, siblings, or ancestors);
+- before processing a descendant, it is re-checked that it is still attached to
+  the same parent (`$component->getParent() === $this`), so a removed descendant
+  is not notified;
+- deduplication: the same pair (callback + specific ancestor object) fires
+  exactly once, even if the component moves during the operation;
+- an `spl_object_id()` guard prevents re-entry and infinite loops.
+
+## Detach order is the reverse (descendant → ancestor)
+
+The decision above concerns **attach**. On **detach**, notifications fire the
+other way, bottom-up: `refreshMonitors()` first descends into descendants and
+only then processes its own `detached` callbacks. A subtree being detached is
+torn down in the reverse order it was assembled.
+
+This is deliberate and symmetric to attach. A callback always fires while the
+tree above it is still intact: on attach a descendant is guaranteed the ancestor
+has finished initializing; on detach it is guaranteed the ancestor is only about
+to relinquish its own ancestor, so it can still rely on the whole path upward
+during cleanup.
+
+The behavior is pinned by tests: for a tree `A > B > C` where both `B` and `C`
+monitor `A`, removing `B` always yields `detached(C)` first, then `detached(B)`.
+
+## Consequences
+
+- An ancestor is notified first and can "stop" a descendant: if it removes the
+  descendant in its own callback, the descendant's callback never fires.
+- The BC break is rare in practice. It only breaks code where two components
+  coordinate through callbacks and rely on the old order, or code depending on
+  the old bug (a callback firing after removal from the tree). A survey of
+  libraries built on the component model found no real breakage.
+- A typical `attached` callback only looks upward at its ancestor and handles
+  itself; it does not depend on sibling/descendant order.
+
+## Rejected alternatives
+
+- **Keep bottom-up order and just add a check for removed components.** This
+  would fix flaw #1, but an ancestor still could not influence its descendants'
+  notifications or prepare their environment; the two-phase collection would
+  remain a source of further edge cases.
+- **Configurable order.** Needless API complexity for a scenario that does not
+  occur in practice.

docs/internals.md

@@ -0,0 +1,114 @@
+# ComponentModel internals
+
+Five small files, but a genuinely tricky core — the classic "small package,
+sharp edges". This is one coherent mechanism (tree + monitoring + lookup +
+cloning), so one file. The value is almost entirely in `Component::refreshMonitors`
+and the cloning handshake; the rest of the API is readable from its signatures.
+
+## The `$monitors` array is a triple-purpose, per-type cache
+
+`Component::$monitors` is keyed by **type** — a `class-string` **or `''`** (the
+key used for the "find the root" / null-type case; `lookup()` does `$type ??= ''`)
+— and each entry is a 4-tuple:
+
+```
+$monitors[$type] = [foundAncestor, depthToAncestor, pathToAncestor, [attachedCbs, detachedCbs]]
+```
+
+So a single structure holds **both** the cached `lookup()` result (`[0..2]`) **and**
+the registered `monitor()` callbacks (`[3]`). `lookup()` fills the cache lazily and
+walks parents to find the closest ancestor of the type (or the root when the type
+is empty), storing the path and depth. The **depth** is not decoration: detachment
+uses it (below).
+
+## Top-down attach, bottom-up detach — the central invariant
+
+`setParent()` drives `refreshMonitors()`, whose parameter `$missing` doubles as the
+mode switch: **an array means attaching, `null` means detaching.** Within one
+`refreshMonitors` call the order of the three blocks encodes the whole contract:
+
+1. **attach** processes **this node's** monitors (fires `attached`) — *before*
+   recursing;
+2. it then recurses into child components;
+3. **detach** processes this node's monitors (fires `detached`) — *after* the
+   child recursion.
+
+Therefore **attach notifications fire ancestor→descendant (top-down)** and
+**detach fires descendant→ancestor (bottom-up)** — symmetric, and emergent only
+from that block ordering. (The rationale is the promoted ADR
+`docs/decisions/2025-12-26 top-down-monitor-notifications.md`; this file states the
+*what*, the ADR the *why*.)
+
+Three properties of this live, single-pass algorithm are the traps:
+
+- **No collection phase — listeners may mutate the tree mid-walk.** The recursion
+  guards against it: `$processed` (keyed by `spl_object_id`) prevents re-entry, and
+  each child is re-checked with **`$component->getParent() === $this`** because a
+  previous sibling's listener may already have removed it.
+- **Callbacks are deduplicated by `[callback, spl_object_id($ancestor)]`** (the
+  `$called` accumulator), so the same handler fires **once per ancestor object**
+  even if reached by multiple routes.
+- **Detach is depth-gated.** Only monitors whose cached ancestor was **deeper than
+  the detachment point** (`$inDepth > $depth`) fire `detached` — an ancestor
+  shallower than where the subtree was cut is still reachable and must **not**
+  notify. This is why `lookup()` caches the depth.
+
+`monitor()` itself fires `attached` **immediately** if the ancestor already exists
+at registration time, and dedups the attach callback on registration.
+
+## Cloning: the container flags itself, children re-home to the clone
+
+Cloning a subtree must re-parent every cloned child onto the cloned container, and
+it is done with a cross-instance handshake rather than a parameter:
+
+- **`Container::__clone`** takes the original container (`reset($components)->getParent()`),
+  sets **`$original->cloning = $this`** (the new clone), clones each child, then
+  clears the flag. The flag lives on **`Container`** (`$cloning`), read via the
+  `@internal final _isCloning()`.
+- **`Component::__clone`** of each child does `$this->parent = $this->parent->_isCloning()`
+  — if the old parent is mid-clone it re-homes to the **new** clone; if
+  `_isCloning()` returns `null` (the parent is *not* cloning, i.e. this is a
+  standalone clone of a child) it **detaches** and refreshes monitors.
+
+So the direction of the wiring is: the parent announces "I am cloning, here is my
+replacement," and each child, as PHP clones it, asks and redirects itself. The
+`cloning` flag is only valid for the duration of the child-clone loop.
+
+Components **cannot be serialized** — `__serialize` throws by design.
+
+## `getComponents()` vs `getComponentTree()`, and why names can't be a flat map
+
+- **`getComponents()` returns immediate children only.** Passing the old recursive
+  or filter arguments now throws `DeprecatedException` (checked via
+  `func_get_args`).
+- **`getComponentTree()` returns a flattened depth-first `list`** — deliberately a
+  list, not a name-keyed map, because **component names are unique only within
+  their container, not across the whole tree**, so a keyed flatten would silently
+  drop collisions.
+- **Return-type inference for `getComponent()` lives in `nette/phpstan-rules`**
+  (`GetComponentReturnTypeExtension` / `ComponentTreeResolver`), not in phpDoc
+  here — an agent chasing types should look there.
+
+## Names, paths, and the factory
+
+- **`NameSeparator` is `-`**, and a component name must match `#^[a-zA-Z0-9_]+$#`
+  — so a name **cannot contain `-`**, because `-` is the *path* separator.
+  `getComponent('a-b-c')` splits on it and descends into sub-containers.
+- **Lazy factory:** `getComponent($name)` auto-creates via a `createComponent<Ucfirst>()`
+  method, guarded so the name's case must match (a leading-uppercase `$name` will
+  not trigger it) and the reflected method name matches exactly.
+- **`addComponent` is exception-safe:** it registers the child, then calls
+  `setParent` inside a `try/catch` that **undoes the registration** if `setParent`
+  throws (e.g. a `validateParent` veto). It also walks ancestors to reject circular
+  references.
+
+## Navigation map
+
+| Concern | Where |
+|---|---|
+| Per-type lookup+callback cache | `Component::$monitors`, `lookup`, `lookupPath` |
+| Attach/detach ordering & guards | `Component::refreshMonitors` |
+| Register listeners | `Component::monitor`/`unmonitor` |
+| Clone re-homing handshake | `Container::__clone`/`_isCloning`, `Component::__clone` |
+| Immediate vs full tree | `Container::getComponents`/`getComponentTree` |
+| Factory, path descent, add safety | `Container::getComponent`/`createComponent`/`addComponent` |