auth-yes/tasks/new/2026-0825.01.jul.story.arch.ui-decomposition-roadmap-2300.md

TASK METADATA

• Target Files: ui/components/SessionsPage.tsx, ui/components/AdminInvitesPage.tsx, ui/components/AdminUserDetailsPage.tsx, ui/components/AdminRolesPage.tsx, ui/components/AdminAppsPage.tsx, ui/components/PasskeysPage.tsx, ui/components/RegisterPage.tsx, ui/components/AuthenticatedLayout.tsx, ui/public/ui/utils/bip39_wordlist.ts, ui/utils/bip39_wordlist.ts
• Core Objective: Conduct a deep architectural investigation of the ui/ directory and draft a comprehensive, phased UI Component Decomposition & Client Script Modularization Roadmap to eliminate remaining monoliths (> 350 lines).
• Dependencies: None.
• Additional Important Notes:
  • Strictly 100% pure Hono SSR JSX (zero React or virtual DOM).
  • Client scripts must be extracted as pure SSR JSX script components (e.g., rendering <script dangerouslySetInnerHTML={{ __html: ... }}>) to prevent static asset race conditions and maintain testability.
  • Must preserve all existing HTML DOM IDs, CSS classes, and form bindings.
  • Must pass all quality gates (deno fmt, deno task lint, deno task check, and ui/ui_scripts.test.ts).

---

Architectural Considerations & Risks

• Risks:

  • DOM Binding Breakage: Extracting structural components (e.g., Drawers, Navbars) alongside their corresponding Vanilla JS controller scripts carries a high risk of breaking DOM IDs, CSS class selectors, or form bindings if not done synchronously.
  • Script Scope Leaks & Reference Errors: Since ui_scripts.test.ts validates syntax in-memory, extracting monolithic scripts into modular SSR JSX script blocks could introduce undeclared variables if inter-script dependencies are broken.
  • Validation Collision: In zero-framework forms (especially in tabs or drawers), ensuring distinct HTML5 <form> elements are preserved during extraction is critical to avoid 'required' field validation collisions.

• Alternatives:

  • Instead of extracting .js as static HTTP assets (which could improve caching but introduce loading race conditions and break ui_scripts.test.ts), we deliberately chose SSR JSX Script Components. This approach encapsulates the vanilla JS alongside the component, preserving hermetic testing capability and avoiding external browser network overhead.

Proposed Implementation

Phase 1: Sessions & Layout Extraction (Targeting AuthenticatedLayout.tsx and SessionsPage.tsx)

• Layout Componentization:
  • Create ui/components/layout/Navbar.tsx.
  • Create ui/components/layout/MobileSidebar.tsx.
  • Create ui/components/layout/UserMenu.tsx.
  • Refactor AuthenticatedLayout.tsx to compose these modular components.
• Sessions Componentization:
  • Create ui/components/sessions/ directory.
  • Extract the active session table and deck rendering logic into distinct subcomponents (e.g., SessionTable.tsx, SessionDeck.tsx).
  • Extract the embedded Vanilla JS block from SessionsPage.tsx into ui/components/sessions/SessionsScript.tsx using the dangerouslySetInnerHTML pattern.

Phase 2: Admin Drawers Modularization (Targeting Admin*Page.tsx)

• Drawer Componentization:
  • Create ui/components/admin/drawers/ directory.
  • Extract InviteDrawer.tsx from AdminInvitesPage.tsx.
  • Extract GrantDrawer.tsx from AdminUserDetailsPage.tsx.
  • Extract RoleEditorDrawer.tsx from AdminRolesPage.tsx.
  • Extract AppDrawer.tsx from AdminAppsPage.tsx.
• Script Modularization:
  • Extract the embedded client scripts from each admin page into dedicated SSR JSX script components (e.g., AdminInvitesScript.tsx, AdminAppsScript.tsx) within ui/components/admin/.

Phase 3: WebAuthn Client Scripts & Asset Deduplication (Targeting PasskeysPage.tsx, RegisterPage.tsx, and assets)

• WebAuthn Script Extraction:
  • Create ui/components/auth/ directory.
  • Consolidate and extract the shared WebAuthn client ceremony helper scripts (webauthn.client.js equivalent) from both PasskeysPage.tsx and RegisterPage.tsx into ui/components/auth/WebAuthnScript.tsx.
  • Move related structural subcomponents (like a PasskeyTable.tsx) to ui/components/auth/ as needed.
• Wordlist Asset Deduplication:
  • Delete ui/public/ui/utils/bip39_wordlist.ts.
  • Update any import statements referencing the deleted file to point to the canonical ui/utils/bip39_wordlist.ts.
  • Verify that deno task check and deno test still pass to ensure all references are correctly updated.