Skip to content

UI-ARCHITECTURE.md

Latest commit

 

History

History
169 lines (132 loc) · 7.6 KB

UI-ARCHITECTURE.md

File metadata and controls

169 lines (132 loc) · 7.6 KB
Raw

UI Architecture

This document records the intended application-shell model and the narrower slice implemented today.

1. Enduring vision, principles, and rationale

WorldSharp should feel like an application with a persistent workspace, not a collection of unrelated pages. Opening navigation, settings, or a contextual tool should preserve the active Interface and make it clear that the conversation or Scene remains open behind the secondary surface.

The interaction model retains the useful parts of LLMToy:

  • the active Interface is the primary workspace;
  • Universe navigation opens from the left;
  • settings and contextual tools open from the right;
  • modals are reserved for focused or deliberately blocking workflows;
  • changing context should not unnecessarily destroy scroll position, drafts, or active workspace state.

The browser client is Blazor WebAssembly. It uses ordinary HTTP after WebAssembly starts, so normal use does not depend on a permanent server circuit. WorldSharp.UI supplies shared presentation primitives but owns no feature routes, persistence, or orchestration.

Domain terminology

An Interface is a durable way to enter or operate in a Universe. Convo, Roleplay, Social Feed, and Game are modes with different ownership. A Scene is the bounded-session presentation of the Roleplay workspace, not a second chat surface.

A durable Roleplay is a long-running workspace. A Scene is instead a bounded Roleplay session with its own transcript range, history branch, and review lifecycle. It may launch from a Convo or directly in a Real-Time Universe. Ending it summarizes and reconstructs its precise range before commit or discard. A Roleplay must not imply that every interaction inside it is a bounded Scene.

Interface lifecycle must be explicit domain state. The UI must not infer "inactive" from age, timestamps, or message count. Personas are also a domain dimension, not a client-only grouping trick.

2. Proposed and future architecture, including alternatives

Persistent shell

The desktop Universe workspace should have three conceptual regions:

+----------------------+-----------------------------------------------+
| Universe navigation  | Interface topbar                              |
|                      +-----------------------------------------------+
| Active Interfaces    |                                               |
| Inactive Interfaces  | Active Interface workspace                    |
| World state          |                                               |
| Characters           |                                               |
+----------------------+-----------------------------------------------+

The left navigation remains visible at desktop widths and scrolls independently so a large world tree cannot push the active workspace away.

On mobile, that navigation becomes a left drawer over the mounted workspace, not a route replacement. It should have a close button and backdrop, close after selection and on Escape, manage focus accessibly, respect safe-area insets, and leave a sliver of the workspace visible where practical. Closing it should return to the same draft and scroll position.

Right-side settings and tools follow the same preservation principle.

Active, inactive, and Persona grouping

The long-term navigation model distinguishes active work from paused, completed, or archived work without treating inactive as deleted. Once Core exposes the necessary state, Interfaces may optionally be grouped by Persona:

Active
  Alex
    Main Roleplay
    Convo with Flick
  Rowan
    Political intrigue
  No Persona
    Social Feed

Inactive
  Alex
    Finished beach Scene

Users who do not use Personas should retain a flat or compact "All Personas" view. Lifecycle and Persona grouping require persistence, API, and mode support; they must not exist only as shell guesses.

Interface topbar

The shell should own placement and lifecycle of a mode-provided topbar. Typical content includes the Interface name/mode, navigation toggle, Persona indicator, mode-neutral lifecycle actions, settings, and extension tools. Buttons should be compact and icon-led while retaining accessible names and tooltips. Modes may supply status/title content without reimplementing navigation behavior.

Extension-contributed tools

Extensions may eventually contribute per-Interface tools such as notifications, a tracker, gallery, or Websim panel. A typed contribution should declare:

  • stable ID, label, icon, and ordering/group;
  • compatible mode IDs or an explicit all-modes target;
  • whether it opens a right drawer, modal, or inline panel;
  • a renderer or route-independent action;
  • Universe, Interface, and optional Persona context.

The shell owns the surface; the extension owns its contents and feature behavior. This is preferable to arbitrary extension markup reaching into the shell because it preserves accessibility, workspace state, and consistent mobile behavior.

Surface rules

Use a left drawer for switching Universes or Interfaces and browsing Personas, Characters, and world state. Use a right drawer for Interface settings, participants, Persona selection, contextual inspectors, and extension tools. Use a modal for destructive confirmations and short focused creation flows. Use a full route for global libraries, provider/system configuration, import/export, and large editors unrelated to one active Interface.

The first complete shell contract should establish persistent Universe navigation, a mobile preserving drawer, a mode-owned topbar slot, a shell-owned right-drawer slot, and a typed extension tool contribution. Persona grouping and richer lifecycle views should follow explicit Core changes.

3. Current implementation, status, and known gaps

The host serves a Blazor WebAssembly client. Interactive pages use browser-scoped HTTP and feature extensions own their routes and behavior. The base shell can enumerate registered mode descriptors but does not reimplement mode orchestration.

UniverseWorkspaceNav currently provides a persistent desktop Universe sidebar and responsive mobile left drawer on Universe management and key conversation/Roleplay workspace pages. It lists active and archived Interfaces and the world tree, with each Character Instance represented by its linked Character World Node rather than a second character list. Character rows retain their avatar identity and open the same selected-node editor used for ordinary world nodes. The global layout still uses a compact desktop rail and mobile bottom navigation. The World add-character action opens a focused card picker outside the transformed drawer; it reuses the installed Character Card browser used by the global Library so search, artwork, selection, and card presentation stay consistent.

Current domain-facing rules include:

  • archive state is explicit; closed bounded Roleplay sessions are archived;
  • conversation-backed Interfaces and bounded Roleplay sessions can select Personas;
  • Scene review is summary review followed by tracker reconstruction review;
  • imported source messages remain read-only with provenance/attachments;
  • world-tree containment and selected-node inspection are available. The selected-node editor is a centered modal on desktop and an almost full-screen, focus-trapped modal on mobile.

There is no generic shell-owned right drawer, shared mode topbar contribution contract, extension tool registry, complete active/inactive lifecycle beyond archive state, or Persona grouping/filtering for the Interface list. Drawer state is not guaranteed to survive arbitrary route changes. These remain intended architecture, not current extension APIs.