feat(gui): registry-based page registration with frame injection

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: olivermeyer

ATTRIBUTIONS.md

@@ -360,7 +360,7 @@ SOFTWARE.
 
 ```
 
-## aignostics-foundry-core (0.8.1) - MIT License
+## aignostics-foundry-core (0.8.2) - MIT License
 
 🏭 Foundational infrastructure for Foundry components.
 

docs/decisions/0005-gui-page-registration.md

@@ -0,0 +1,72 @@
+# 5. GUI page registration
+
+Date: 2026-04-08
+
+## Status
+
+Accepted
+
+## Context
+
+Bridge feature modules (`bridge.home`, `bridge.proscia`, `bridge.hello_world`, `bridge.papi`)
+need to register NiceGUI pages with a frame that displays a consistent header, navigation
+sidebar, and health status bar. The frame function (`bridge.system.gui._frame.frame`) depends
+on `Service().health()` from `bridge.system._service`, making it inherently a system-level
+concern.
+
+The previous implementation created `gui = GUINamespace(frame_func=frame)` in
+`bridge/system/gui/_gui.py` and exported it from `bridge.system`. Feature modules imported
+this singleton via `from bridge.system import gui`. This is a **module boundary violation**:
+feature modules should not depend on the orchestrating system module.
+
+### Alternatives considered
+
+**Option A — Deferred singleton in foundry-core**: Add `gui = GUINamespace()` to
+`aignostics_foundry_core.gui` and a `configure(frame_func=...)` method. Feature modules import
+`gui` from foundry-core; `bridge.system` calls `gui.configure(frame_func=frame)` at startup.
+Rejected: pollutes a generic library with a stateful singleton that must be mutated by the
+application layer. Complicates testing (global state to reset). Philosophically wrong: the
+singleton is bridge-specific and should not live in a general-purpose library.
+
+**Option B — New `bridge.gui` module**: Create `bridge/src/bridge/gui/` as a neutral singleton
+home, independent of `bridge.system`. Feature modules import from `bridge.gui`.
+Rejected: adds a thin wrapper module whose only content is a singleton. The module boundary
+problem is merely moved, not eliminated. No architectural gain justifies the additional module.
+
+**Option C (chosen) — Registry-based page decorators**: The standalone `page_*` decorators in
+foundry-core (`page_authenticated`, `page_public`, etc.) write to a module-level `_registry`
+instead of calling `@ui.page()` immediately. `gui_register_pages(frame_func=frame)` processes
+the registry after all `BasePageBuilder.register_pages()` calls, actualizing each entry with
+the correct `frame_func`. Feature modules import only from `aignostics_foundry_core.gui`.
+`bridge.system` provides the `frame_func` to `gui_run()`, which flows it down to
+`gui_register_pages`. The `gui` singleton in `bridge.system` is deleted entirely.
+
+## Decision
+
+Implement Option C. The standalone `page_*` decorators become pure registration decorators
+that record intent (path, title, access level, page function) to a module-level list. The
+`gui_register_pages(frame_func)` function actualizes all entries using the private
+`_actualize_*` functions. `GUINamespace` methods continue to call `_actualize_*` directly,
+bypassing the registry (preserving the existing opt-in, frame-at-construction-time API for
+any future consumers that prefer it).
+
+`gui_run()` gains a `frame_func` parameter that is forwarded to `gui_register_pages`.
+`bridge.system._service` passes `frame_func=frame` when calling `gui_run()`.
+
+## Consequences
+
+**Easier**:
+- Feature modules have zero dependency on `bridge.system` for page registration.
+- Dependency graph is clean: feature modules → `aignostics_foundry_core.gui`; `bridge.system`
+  orchestrates and provides the frame.
+- Adding a new page requires only `from aignostics_foundry_core.gui import page_authenticated`
+  — no reference to any singleton or bridge.system.
+
+**Harder / risks**:
+- Page registration is now a two-phase process (write to registry, then actualize). Code that
+  calls `page_authenticated(path)(func)` and expects the route to be live immediately (without
+  subsequently calling `gui_register_pages`) will silently not register the route.
+- `_registry` is module-level mutable state. Tests must call `clear_page_registry()` in
+  teardown to avoid cross-test contamination.
+- `GUINamespace` now calls a different set of internal functions (`_actualize_*`) than the
+  public `page_*` API, which is a maintenance surface to keep in sync.

src/aignostics_foundry_core/gui/__init__.py

@@ -9,6 +9,7 @@
 
 from .auth import (
     GUINamespace,
+    clear_page_registry,
     get_gui_user,
     gui,
     page_admin,
@@ -42,6 +43,7 @@
     "GUINamespace",
     "NavGroup",
     "NavItem",
+    "clear_page_registry",
     "get_gui_user",
     "gui",
     "gui_get_nav_groups",