LorenEteval_Furious/Furious/Widget/AGENTS.md

Reusable widget guidance

Inherit the root and package guides; consult Furious/Qt/AGENTS.md for shared lifetime/presentation contracts. This scope covers reusable controls and model/view adapters below page composition. Persistent widgets currently host some service owners; that construction detail does not make every view an independent workflow authority.

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. Map the resolved current object 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.

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.
• Models, delegates, headers, menus, actions, animations, spinners, WebEngine/map objects, timers, workers, and replies each need one owner. Persistent widgets connect once and refresh state; visibility may pause rendering/animation, not application-level log draining, traffic collection, or other service ownership.
• Model notifications describe the real source mutation. Structural replacement may legitimately use a model reset; metadata-only test results should update the exact cell. Do not use resets/full repaints to mask broken mapping or missing identity restoration. 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.
• 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.