Lumi/docs/lumi-ux-route-manifest.md

# Lumi UX route and state manifest

This manifest is the implementation contract for the DesignMotionHQ UX overhaul. It is maintained alongside `docs/lumi-ui.md` and must be updated whenever a rendered route, role boundary, asynchronous state, or page-owned script changes.

## Shared state contract

Every data-dependent surface distinguishes these states instead of collapsing them into a blank page or generic error:

| State | Required presentation | Recovery or next action |
|---|---|---|
| Loading | Preserve existing content where possible; otherwise use a delayed local spinner or content-shaped skeleton. | Cancel when supported; do not flash a loader for work completing in under 300 ms. |
| Empty | Explain why the collection is empty. | Offer the role-appropriate create, connect, configure, or learn-more action. |
| Partial | Keep successful content visible and name the unavailable provider, row, or widget. | Retry the failed region or review its settings. |
| Error | Anchor a specific message to the failed form/component and state what remains safe. | Retry, correct linked fields, copy diagnostics, or return to a safe view. |
| Success | Patch the smallest affected region and announce completion without moving focus. | Continue in place or follow an explicit next-step link. |
| Offline/degraded | Distinguish local Lumi availability from Twitch, Discord, YouTube, OBS, AI runtime, socket, and other provider state. | Reconnect, configure, retry, or keep using unaffected local features. |

Dirty, saving, queued, disabled, read-only, permission-denied, rate-limited, stale, reconnecting, conflict, and destructive-pending states extend this table where relevant.

## Public and member surfaces

Routes: `/`, `/commands`, `/leaderboards`, `/stats`, `/stats/:username`, `/profile`, `/feedback`, `/pages/:slug`, `/mods`, `/moderator`, `/auth/*`, `/setup`, and restricted/error/missing views.

Surface: Public discovery and member account tasks
Users/roles: anonymous visitors, members, moderators, administrators
Primary job: discover community capabilities or complete the one account/community task named by the route
Entry context: sidebar, shared link, authentication return, or a community call to action
Desired outcome: useful information or a completed account action without admin density
Primary action: search/discover, sign in/link, submit feedback, or save the current profile task
Secondary actions: filters, comparison, history, related community destinations
Tertiary/destructive actions: unlink account, revoke or delete through separated contextual confirmation
Information needed immediately: current identity/status, the main content, eligibility and prerequisites
Information deferred: raw IDs, diagnostics, uncommon account details
Worst-case path: authentication/provider failure or destructive account action; preserve input and provide a safe return
Six-state behavior: shared contract; empty and filtered-empty copy are distinct
Feedback/loading strategy: local pending control, inline result, lightweight skeleton for collections
Mobile/tablet/desktop strategy: single-column reading flow on phone; labelled list rows replace small action tables; standard/prose width
Keyboard/focus strategy: heading focus after navigation, visible search, semantic lists/tables, labelled account actions
Success exit/next step: remain in context with updated status, or return to the intended pre-auth route

## Core administration surfaces

Routes: `/admin`, `/admin/settings`, `/admin/navigation`, `/admin/theming`, `/admin/diagnostics`, `/admin/logs`, `/admin/feedback`, `/admin/commands`, `/admin/command-policies`, `/admin/privileges`, `/admin/users`, `/admin/pages`, `/admin/plugins`, `/admin/updates`, `/admin/resources`, and platform setup wizards.

Surface: Core administration workspaces
Users/roles: administrators; moderators on explicitly delegated command/user routes
Primary job: assess health, configure one domain, or manage one collection safely
Entry context: persistent administration navigation or an actionable dashboard warning
Desired outcome: a confirmed targeted update with place, filters, and draft context preserved
Primary action: domain-specific save/create/review/update action
Secondary actions: visible search, filters, preview, test, duplicate, export
Tertiary/destructive actions: advanced diagnostics, reset, uninstall, delete, rollback and manual update paths
Information needed immediately: current state, consequences, readiness, main decision fields, validation
Information deferred: raw metadata, rare provider controls, verbose diagnostics and recovery tooling
Worst-case path: partial save, invalid configuration, provider loss, destructive mutation, update/restart interruption
Six-state behavior: shared contract plus scoped dirty/saving/conflict/restart-required states
Feedback/loading strategy: enhanced response envelope, field-linked errors, local progress, persistent degraded banner
Mobile/tablet/desktop strategy: form/standard widths for settings; wide list-detail layouts; workspace widths only for editors
Keyboard/focus strategy: persistent labels, section links, table row names, non-drag reorder controls, dialog focus restoration
Success exit/next step: patch the affected section and keep focus; restart/reconnect only when explicitly required

### Core route matrix

| Surface | Representative states | Width | Form taxonomy | Primary regression risk |
|---|---|---|---|---|
| Dashboard | healthy, partial provider failure, stale, loading | standard | immediate action | duplicated configuration and non-actionable status |
| Settings/homepage | clean, dirty, invalid, partial save, restart-required | form/wide | settings | reload, lost preview, unrelated batched forms |
| Navigation builder | empty, selected, dirty, invalid upload | workspace | settings/upload | lost selection and drag-only ordering |
| Theme Studio | built-in read-only, custom draft, invalid contrast, pop-out | wide | settings/entity | draft leaking globally or preview reload |
| Commands/policies | empty, filtered-empty, selected, invalid, permission-limited | wide | entity/filter/destructive | dense schema presentation and lost filters |
| Feedback | empty queue, filtered, selected, export pending, merged | wide | entity/immediate/destructive | losing current item after mutation |
| Diagnostics/logs | idle, running, partial, degraded, paused/following | wide | immediate/settings | whole-page scrolling for bounded log data |
| Users/privileges/pages/plugins | empty, filtered, row pending, denied | wide | entity/filter/destructive/upload | unnamed row actions and forced reload |
| Updates/recovery | current, available, applying, reconnecting, failed, recovery | form/wide | immediate/upload/destructive | hiding recommended path or implicit reload |
| Resources | empty library, queue pending, partial upload, quota full, delivery error | workspace | upload/entity/filter | failed file erasing successful queue items |
| Setup wizards | prerequisites, verifying, provider error, complete | form | entity/immediate | accidental submit and lost prior steps |

## Overlay management workspace

Routes: `/admin/overlays`, `/admin/overlays/:id`, `/api/admin/overlays/*`, and privileged OBS/preview endpoints.

Surface: Overlay list, scene/source editor, events, OBS integration and diagnostics
Users/roles: administrators and users granted explicit overlay capabilities
Primary job: compose and verify what OBS renders without losing editor context
Entry context: overlay list or an OBS/integration warning
Desired outcome: a saved canonical overlay matching the live draft preview
Primary action: edit the selected scene/source and save its scoped changes
Secondary actions: switch scene, test, align, reorder, preview, copy protected URL
Tertiary/destructive actions: advanced diagnostics, token replacement, reset and delete
Information needed immediately: selected object, preview, dirty/save state, validation and OBS connection state
Information deferred: event bindings, delivery credentials, raw diagnostics and destructive operations
Worst-case path: invalid source, blocked URL, partial render, disconnected OBS/socket, revoked link, destructive deletion
Six-state behavior: loading/empty-scene/partial-source/error/success/offline plus dirty and reconnecting
Feedback/loading strategy: draft-first rendering, targeted requests, optimistic transform with rollback, live status text
Mobile/tablet/desktop strategy: document is the only main vertical scroller; preview before inspector on narrow layouts; sticky preview only when it fits
Keyboard/focus strategy: named stage, arrow movement, labelled numeric fields and ordering buttons; no forced viewport movement
Success exit/next step: selection, open inspector, focus, viewport, canvas zoom and preview remain unchanged

## Plugin surfaces

Routes: `/plugins/auto-vc`, `/plugins/birthday`, `/plugins/economy-framework`, `/plugins/economy-games`, `/plugins/expression-interaction`, `/plugins/lumi_ai`, `/plugins/lumi_ai/improvement_center`, `/plugins/moderation`, `/plugins/okf`, `/plugins/okf/admin`, `/plugins/quotes`, `/plugins/throne_wishlist`, and `/plugins/welcome_messages` plus their detail/action routes.

Surface: Plugin-owned member and administration workflows
Users/roles: members, moderators, administrators, and plugin-specific grantees
Primary job: use or configure the capability named by the plugin
Entry context: role-filtered plugin navigation, profile integration, or linked improvement task
Desired outcome: complete the plugin task with the same Lumi interaction contract as core
Primary action: plugin-specific save/create/review action
Secondary actions: search, filter, preview, test, duplicate, archive
Tertiary/destructive actions: raw diagnostics, maintenance, reset, revoke and delete
Information needed immediately: capability availability, current configuration/status, dependencies and main task
Information deferred: advanced provider/model fields, history, raw logs and maintenance
Worst-case path: missing dependency, runtime/provider offline, permission denial, partial save or destructive maintenance
Six-state behavior: shared contract with explicit unconfigured and permission states
Feedback/loading strategy: shared request/form/dialog/status services; long AI work uses progress or meaningful stages
Mobile/tablet/desktop strategy: declared form/standard/wide width; responsive list/table strategy; section navigation for dense plugins
Keyboard/focus strategy: labelled controls, contextual row actions, preserved master-detail selection and dialog return focus
Success exit/next step: patch the current domain/row and preserve filter, entry and disclosure state

### Plugin migration order and intent

| Plugin group | Primary workflow | Information architecture | Representative degraded state |
|---|---|---|---|
| Lumi AI | configure runtime/models and review improvement work | runtime, budgets, routing, context, tools, safety, improvement, diagnostics | runtime/model/search dependency unavailable |
| OKF | search knowledge or review/edit an entry | visible search plus master-detail review | entry permission changed or correction preview failed |
| Economy + games | configure currency flows and manage balances/events | currency, earning, spending, banking, limits, maintenance | platform earning source unavailable |
| Moderation | review status/actions/evidence/notes | list-detail with separated evidence and action | platform enforcement partially failed |
| Remaining plugins | configure one bounded capability | summary, main settings, entities, advanced/maintenance | integration unconfigured or provider offline |

## Standalone browser surfaces

Routes: `/overlay/:token`, fixed-scene overlay routes, `/overlay-chat/:ticket`, `/overlay-web/:ticket`, and standalone moderation status.

Surface: OBS/browser-source rendering and standalone restriction status
Users/roles: viewers of a protected browser source, OBS runtime, or sanctioned user
Primary job: render reliably without the application shell, or understand a restriction and next step
Entry context: OBS Browser Source URL or moderation redirect
Desired outcome: stable transparent media rendering or a clear restriction explanation
Primary action: normally none for OBS; follow the stated recovery/appeal action for restriction state
Secondary actions: reconnect/status only when normal browser interaction exists
Tertiary/destructive actions: none
Information needed immediately: render/status content and concise recovery information
Information deferred: technical diagnostics and protected credentials
Worst-case path: expired ticket, blocked media, CSP failure, socket loss, unavailable provider
Six-state behavior: loading, empty scene, partial module, render error, connected success, reconnecting/offline
Feedback/loading strategy: preserve last safe frame while reconnecting; never require focus or user gesture assumptions unique to tabs
Mobile/tablet/desktop strategy: transparent canvas geometry is independent of shell breakpoints; status pages use prose width
Keyboard/focus strategy: decorative render tree is hidden where appropriate; status page remains normally navigable
Success exit/next step: continue rendering; no automatic document navigation

## Baseline selectors and contracts to preserve

- Main replacement root: `main.content`; page scripts must register with `LumiPage` before opting into soft navigation.
- Settings enhancement: `form[data-lumi-settings-form]`; ordinary POST remains the no-JavaScript fallback.
- State actions: `[data-lumi-state-button]` and existing route-specific action attributes.
- Overlay editor: `[data-overlay-editor-state]`, `[data-overlay-editor]`, `[data-editor-scene]`, `[data-module-editor]`, and protected overlay capability checks.
- Dialog backdrops: `.modal-backdrop[aria-hidden]`; opening code must use `LumiDialog` or emit compatible state changes.
- Navigation: `[data-sidebar-toggle]`, `#lumi-sidebar`, `[data-sidebar-dismiss]`, `.nav-link`, and `.nav-section`.
- Enhanced response: `{ ok, message, fieldErrors, data, patch, redirect, reloadRequired }`; reload is permitted only when `reloadRequired === true`.

## Phase review record

Known baseline P0/P1 findings are the reload-based save flow, viewport-coupled overlay settings height, forced overlay scrolling, page scripts without teardown, incomplete drawer focus handling, fragmented dialogs, inconsistent labels, and duplicated generic CSS ownership. A phase cannot be closed while a changed surface retains a known P0/P1 finding.

Current migrated core surfaces include settings, overlay management, navigation builder, custom-theme editing, custom commands, command policies, and updates/recovery. Navigation changes now support pointer and labelled keyboard movement without a document reload; custom-theme saves preserve the draft preview and return canonical values. Command mutations return field-linked errors and refresh only the managed collection, while policy batches remain in place after save. Update checks, recovery actions, and cleanup settings now preserve the document, destructive recovery actions attach timed confirmation tokens, and restart flows reconnect before refreshing the workspace in place. Lumi AI settings polling is lifecycle-owned, but plugin-enabled browser-fixture coverage remains a required later gate.