Feature/component garbage collection

[janvojt]

Garbage collection of unused components within live sessions

Problem

SessionContext keeps a strong reference to every client object (component) ever rendered, for the whole lifetime of the session. In long-lived sessions that repeatedly rebuild parts of their UI (dashboards, wizards, record detail views, …), all discarded component trees accumulate on the server and on the client, since the client-side counterparts are never destroyed either. Memory usage grows monotonically until the session ends.

Solution

This PR makes the session's client-object registry weak-reference based, so components that are neither displayed nor referenced by application code get garbage collected during the session's lifetime, and their client-side counterparts are destroyed automatically.

The feature is opt-in via a new configuration flag (default off):

TeamAppsConfiguration config = new TeamAppsConfiguration();
config.setClientObjectGarbageCollectionEnabled(true);

With the flag off, behavior is unchanged: every registered client object is pinned at registration time and stays strongly referenced until the session is destroyed (exact historical behavior, covered by dedicated tests).

How it works

• Weak registry. SessionContext.clientObjectsById now holds WeakReferences (a ConcurrentHashMap keyed by component id) backed by a ReferenceQueue. Collected entries are drained opportunistically on every registerClientObject(...) call and periodically by the session manager's housekeeping loop (which also covers idle sessions). For each drained entry, a DestroyComponentCommand is sent so the client releases the DOM/state too. A two-arg remove(key, reference) guards against races with explicit unregistration — an explicitly unrendered component is never destroyed twice.
• Pinning keeps displayed UI alive. Components that are displayed without necessarily being referenced by application code are strongly referenced ("pinned") by the session context:
  • root panels (addRootPanel*) — permanently, since the client appends root panels and never removes them,
  • shown Windows, Popups and Notifications — pinned on show, unpinned on close (whether server-initiated or user-initiated on the client),
  • context menu content (Table, Tree, InfiniteItemView/2, ChatDisplay, MediaSoupV3WebRtcClient) and ToolbarButton drop-down content — retained by the owning component while the client may still display it,
  • session expired/error/terminated windows.
• Reference-counted pins. SessionContext.pinClientObject(...) / unpinClientObject(...) are public API and reference-counted, so an object pinned for multiple independent reasons stays pinned until every reason released it. Spurious unpins are no-ops (saturating at zero). Window/Popup/Notification acquire their show-pin through the new idempotent AbstractComponent.pinWhileDisplayed() / releaseDisplayPin() helpers, so racing double-releases (e.g. a server-side close() plus the client's closed event) cannot underflow another pin. Custom component authors can use the same helpers for transient components that are referenced only from the client.
• In-flight events tolerated (only when enabled). An event or query can legitimately race the collection of its target component. With GC enabled, such events are logged and ignored, and queries answer null. With GC disabled, the historical fail-fast behavior is kept: TeamAppsComponentNotFoundException destroys the session, since an unknown id then indicates a real client/server desync.
• Observability. UiSessionStats gains two values, updated by the housekeeping loop: clientObjectCount (currently registered, gauge) and collectedClientObjectCount (collected during the session's lifetime, cumulative).

Popup close-on-escape / close-on-click-outside

Popup.closeOnEscape and closeOnClickOutside existed in the API and DTO but were never implemented on the client — the flags were dead. Correct unpinning requires the server to learn about user-initiated closes, so this PR implements them: UiPopup.ts now closes on escape / click-outside (mirroring UiWindow) and fires a new closed DTO event; the server unpins and fires the new Popup.onClosed event.

Behavior changes to be aware of (even with the flag off)

1. Popups now really close on escape / click-outside when those flags are set (previously silently ignored), and Popup.onClosed is available.
2. ToolbarButton drop-down suppliers are cached: the supplier's result is reused across re-render cycles instead of being re-invoked (the client requests the content only once anyway). Use updateDropDownComponent(...) to replace displayed content.
3. SessionContext's constructor takes an additional boolean and UiSessionStats has two new methods — relevant only to code reaching into framework internals.

Adopting garbage collection in applications

Nothing is required for standard usage — the framework pins everything it displays itself. To benefit from the flag and stay safe:

1. Dispose listeners on application-scoped objects when discarding components. A shared model or application-wide Event strongly references its listeners, and a listener typically references its component — such components cannot be collected until the listener is removed (use the Disposable returned by Event.addListener(...)). This is the most common reason for collectedClientObjectCount staying near zero.
2. Audit custom components handing out createUiReference() of transient components. If the only remaining reference lives in client-side state, pin the component while it is displayed (pinWhileDisplayed() / pinClientObject(...)) and release it on close, as Window/Popup/Notification do.
3. Do not use the registry as storage. Keep server-side references to any component the application will interact with later; getClientObject(id) may return null once GC is enabled. Custom client-side components should tolerate a null query result.

Recommended rollout: enable in staging, watch the two new session stats, and exercise the main UI flows.

Testing

• New SessionContextClientObjectGcTest (22 tests): unreferenced components are collected and destroyed exactly once on the client; displayed UI (root panels, shown windows/popups/notifications) survives GC and becomes collectable after each close path (server-side and client-side); reference-counting semantics (double pin/unpin, spurious unpin, close/closed-event races); registry stays bounded under repeated content replacement; unknown-id tolerance with the flag on and fail-fast with the flag off; exact historical behavior with the flag off.
• Full teamapps-ux module: 251 tests, 0 failures.
• Note: the GC tests rely on System.gc() triggering a collection and will not work under -XX:+DisableExplicitGC.
• The UiPopup.ts changes mirror UiWindow.ts but were authored on a machine without a working frontend build — please smoke-test popup escape/click-outside closing during review.

🤖 Generated with Claude Code