LorenEteval_Furious/Furious/Widget/AGENTS.md

Reusable widget guidance

Inherit the nearest parent guide. Widgets own controls and model/view adapters, not independent workflows. Domain identity survives sorting and deferred commands; indexes remain model-specific. Read Furious/Widget/ServerTableView.py with tests/test_qt_interactions.py; paths are relative to this source tree's root.

Presentation and identity

• Widgets present state below pages/windows. Prefer explicit controller/service/repository inputs and do not add new application-global reach-through or a duplicate state cache; existing global access is compatibility debt, not a template.
• Table/list models wrap live repository collections. Bracket mutations with correct begin/end or layout notifications, keep index/deleted compatibility fields synchronized, and map proxy indexes to source objects before acting. Stable profile/subscription IDs—not display text, object row, or current sort order—preserve selection, focus, activation, and async write-back.
• Sorting/filtering/reordering must retain logical selection and keyboard focus. Capture domain IDs before yielding to a dialog or event-loop turn; an ordinary QModelIndex/source row may become invalid or refer to another item. Resolve a multi-target confirmation independently for each captured ID: targets may move or disappear while it is open, and later selection must not change the command. Map resolved objects back through the proxy when restoring focus. Recursively scope table-owned menu shortcuts as WidgetShortcut so focused editors and other surfaces keep their own shortcut semantics. Selection identity, current keyboard index, and selection painting are separate: keeping targets highlighted while a command button/menu has focus must not change selection or steal editor focus. Exercise the button-focus interval before popup display as well as the open menu to catch highlight flicker. An action shared with a page button still resolves the table's selected domain targets when triggered; moving its presentation must not introduce another test scheduler or a second selection model.

Workflow and lifetime boundaries

• The server and subscription views share one subscription workflow owner. Subscription UI issues commands and renders sync state; it does not duplicate download, decode, reconciliation, timer, persistence, or post-commit behavior.
• ServerTableView owns selection and cell repaint for profile tests, while ProfileTestManager owns scheduling, concurrency, temporary runtimes, cancellation, stable-target validation, and latency/speed mutation. Repository or subscription changes are forwarded as invalidation boundaries; stale results never write by row.
• Persistent widgets reuse their model, delegates and signal paths during refresh; replacement needs explicit retirement of the former owned tree. Visibility may pause rendering/animation, not application-level log draining, traffic collection, or other service ownership. A view may borrow a model, delegate, or controller; installing one is not a transfer of QObject ownership. Parent newly created presentation objects to their intended owner and retire replacements at the creating boundary, while preserving explicitly shared owners. Test native owner-first teardown with wrappers retained.
• A pending confirmation whose callback mutates a view belongs to that exact view on every platform. A shared window parent can outlive the view, and an unparented prompt can outlive both. Native view destruction must end the prompt without running its mutation; test_qt_lifetime.py exercises this with the containing window still alive.
• Model notifications describe the real source mutation. Structural replacement may legitimately use a model reset; metadata-only test results should update the exact cell. Observers may run synchronously at notification boundaries: expose consistent source contents, activation, and index/deleted fields before publishing completion. A persistent model index is valid only within its model and can be invalidated by removal/reset; use domain IDs across collection/model replacement. For a non-reset update, preserve the model's persistent-index mapping as well as the view's selected IDs. Do not use resets or full repaints to mask broken mapping. Test selected identities and the current keyboard index independently.
• Bulk profile mutations validate/prepare a batch before beginning structural notifications. Resolve captured IDs again after confirmation and between deferred batches, report actual source ranges, and preserve activation before observers see completed removal. Forward bulk insert/delete operations through the model instead of replaying a single-item notification/reconciliation path for every profile. Small direct operations and deferred large ones share these identity rules; batch yields and throttled progress updates serve different responsiveness purposes. Duplication captures selected IDs, resolves surviving sources at each batch, and uses independent manual copies; cancellation preserves completed batches, and explicit table cleanup stops pending copies before service shutdown. Favorite commands use the repository's local metadata mutation and keep connection/remote ownership intact. Favorites, search, and subscription filters intersect in the existing proxy model; a favorite mark is persisted metadata, while the filter is presentation state. The profile mutation and Home workflow cases in tests/test_qt_interactions.py cover these boundaries.
• Endpoint lookup belongs to EndpointInfoService; the map renders validated results and has a no-WebEngine fallback. Optional WebEngine import failure must not prevent importing the widget/package, and hidden presentation must not retarget a queued lookup.
• Verify sorted/filtered commands, notification ranges, identity-preserving move/delete, real keyboard focus and nested shortcuts, subscription/test cancellation, hidden-page rendering, exact cell updates, optional WebEngine fallback, and repeated cleanup to baseline. Update this guide when ownership moves; never move service orchestration back into a widget just to preserve historical wording. Start with tests/test_qt_interactions.py, tests/test_profile_test_jobs.py, and tests/test_endpoint_info.py. When an event-filter callback destroys its watched target or owner, exercise actual native event delivery in an isolated child; calling the Python filter method directly cannot establish safe Qt delivery. Navigation cases live in tests/test_isolation_and_navigation.py. Outside-click navigation collapse leaves surviving targets' clicks deliverable, but consumes the event if a synchronous observer deletes its target or containing view. Native child probes cover both destruction cases.