Skip to content

Mockup harness

A second entry point that runs prototype screens in the app's own theme, with none of the app's boot — no log sinks, no auth, no backend.

flutter run -t lib/main_mockups.dart -d linux   # or -d macos, -d chrome, ...
flutter run -t lib/main_mockups.dart -d linux --dart-define=MOCKUP=Chat

The second form opens straight into the named mockup — on launch and after every hot restart — which is what you want while iterating on one screen.

The index lists every mockup. Opening one shows it under a toolbar with two knobs from the design-system adoption checklist:

  • Brightness — flips between the light and dark brand palettes.
  • Viewport — pins the width to Fill or to a SoliplexBreakpoints value (320 / 600 / 840). The frame overrides MediaQuery as well as the box, so layouts that read MediaQuery.sizeOf and those that use LayoutBuilder agree.

The theme is lowered from BrandTheme.soliplex() by lowerBrandTheme — the same path Flavor.build takes for the standard flavor — so what a mockup renders here is what it would render in the app. MockupApp takes a BrandTheme for prototyping on a fork's brand.

Adding a mockup

  1. Put the screen in its own widget under lib/src/mockups/. Return the whole screen, Scaffold included; it may import anything under lib/src/.
  2. Register it in lib/src/mockups/mockups.dart:
Mockup(
  name: 'Thread list',
  description: 'Grouped by day, unread dot on the left',
  build: (_) => const ThreadListMockup(),
),

Keep build a one-line constructor call and the UI in the widget's own build — hot reload then updates the mockup that is already open.

Mockups live under lib/ so they can reach the app's internal widgets and assets, but nothing here is exported from the package barrel, and CI drops lib/src/mockups/ from the coverage gate. Design-system rules in CLAUDE.md apply to mockups as to any other UI: they are drafts of app code, not throwaways. lib/src/mockups/example_mockup.dart is a starter to copy.

The chat mockup

lib/src/mockups/chat/ runs the room screen on a static backend:

File What it is
chat_screen.dart A copy of lib/src/modules/room/ui/room_screen.dart with its imports repointed. Edit it freely; the app's screen is untouched.
static_backend.dart StaticSoliplexApi answers every call the chat makes from in-memory maps; ScriptedAgUiStreamClient streams a canned reply to a send; anything unstubbed throws, naming the request.
sample_data.dart The rooms, threads, conversations and documents it opens on.
chat_mockup.dart Hosts the screen under its own GoRouter with the app's room routes, so thread and room switching work; other destinations get a placeholder page.

The copy is only the screen — the composition layer. The composer, timeline, message tiles, rail and sidebar are still imported from the app. When a mockup needs to change one of those, copy that file the same way (into chat/, imports repointed) and switch the import in chat_screen.dart.

Sending a message streams a scripted reply and appends the exchange to the thread's history, so leaving and returning shows it. Creating, renaming and deleting threads work the same way. A hot restart resets everything to sample_data.dart.

The thread panel

lib/src/mockups/chat/thread_panel/ is the first feature prototyped on the chat mockup: a floating, tabbed panel in the top-right of the chat area for everything that belongs to the thread (the rail, sidebar and header belong to the room). It collapses to a pill handle.

File What it is
panel_state.dart ThreadPanelState, a ChangeNotifier holding every stub: databases, skills, context usage, workspace draft. Each "call" is a delayed state flip.
panel_sample_data.dart The opening state.
thread_panel.dart The floating shell: tab strip, collapse, the handle.
context_tab.dart An accordion of three segments — Databases (open by default), Skills, Context usage.
workspace_tab.dart A note to colleagues: recipients as stacked avatars, title, content, embedded documents, send.

The context ring beside the send button (context_gauge.dart, context_usage.dart) is carried over from feat/server-measured-context and reads the same stubbed usage, so connecting a database or loading a skill moves it. On a viewport wide enough for both, the conversation column and composer move over to sit beside the open panel; narrower than that, the panel floats over the column. On the phone layout (below the tablet breakpoint) it cannot float at all and opens as a modal sheet from the composer's Thread panel button, sharing the same ThreadPanelState — which also holds what is open, scrolled and typed, so it is there again on reopen.

The composer's leading controls are one + menu: attach (files, images, a folder) and Filter documents, which is stubbed to a notice until its purpose (RAG scope, embeds, or both) is settled.

The datasets mockup

lib/src/mockups/datasets/ prototypes rooms as presets rather than walled gardens: a user picks from every dataset they can access, creates their own, uploads to them, and shares them once tagged. Nothing here is on the wire — the backend has no dataset entity yet — and every rule the screens apply is a working assumption to confirm, not a decision.

flutter run -t lib/main_mockups.dart -d linux --dart-define=MOCKUP=Datasets

Add --dart-define=DATASETS_ROUTE=/datasets/ops/pump-service-manuals (any of the routes below) to open straight on a screen.

Route Screen
/lobby, /lobby?view=threads, /lobby?view=datasets Room presets, every thread wherever it lives, or the dataset catalog with search and facets.
/datasets/new Create a dataset: namespace, name, level, optional tags.
/datasets/<namespace>/<name> A dataset's files and ingestion. Anyone with access uploads and marks files outdated; the owner shares and deprecates.
/datasets/<namespace>/<name>/upload Choose files, scan, review and commit.
/room/mock/<room>[/thread/<id>] The chat mockup's room screen, its panel showing the thread's datasets.
/conversations[/thread/<id>][?new] Conversations outside any room, with no room rail; ?new opens on a fresh one.

The rules it assumes:

  • Levels. A room's level is a ceiling the deployer sets. A thread may use datasets at or below it; the picker shows the rest locked.
  • Access. A dataset is listed only when the user's access reaches its level and the user is in its audience. A high enough level alone is not enough.
  • No enforcement. Nothing checks sensitivity, so uploads and shares end with an attestation and the scan's results are worded as advisory.
  • Fixed after the first message. A new thread starts from the room's defaults and can change them until its first message; after that they are fixed, and New thread with these datasets is the way out.
  • No deletion. Uploads can't be undone. A wrong or outdated file is marked outdated instead: it stays indexed and searchable, and the mark shows in the files table and the thread panel, and to the agent. A whole dataset can be deprecated, which hides it from the catalog.
  • One upload per place. The dataset page's Upload to dataset is the only way files join a dataset, and its copy sets it apart from attaching a file to a thread.
File What it is
sensitivity_levels.dart The sensitivity levels: PUBLIC, INTERNAL, CONFIDENTIAL, RESTRICTED. The only file allowed hex colors.
model.dart Datasets, files and their ingestion states, tags, principals, room presets.
store.dart DatasetsStore: the catalog query, access rule, thread trays, simulated ingestion.
upload_session.dart One upload: staged files, the simulated scan, what committing adds.
sample_data.dart The user, about 115 datasets, three room presets and their conversations.
ui/ The screens, and the panel section plugged into the chat mockup.

The chat screen takes the datasets through ThreadDatasetsSeam (chat/thread_panel/panel_section.dart): it replaces the panel's Databases segment and adds a summary row above the composer. Without one, the chat mockup is unchanged.

Conversations outside rooms

The same mockup prototypes a conversation that belongs to no room. New conversation in the lobby opens one on the conversations page: the chat screen with no room rail, its sidebar listing only conversations outside rooms, and a link back to the lobby.

The lobby's Threads view lists them beside room threads. It is a copy of the app's cross-room listing (ui/threads/) on the app's own GlobalThreadsState, adding what a listing of both kinds needs:

  • a trailing icon on each row, a door for a thread in a room and a bubble for one outside;
  • a scope filter under Show: All, In rooms, No room, set apart by a rule from Group by;
  • in:room in the search box beside @label, completed the same way, with in:none for conversations outside rooms;
  • @no-label for threads carrying no label, alone or any-of beside other labels;
  • label chips on each row, at most three and then "+N"; tapping one adds it to the search;
  • Group by: Room, with section headers and conversations outside rooms first. It groups only the pages already loaded, so a section can grow as the list scrolls.

The scope and in: filters need a room_ids parameter on GET /v1/agui/threads, any-of like label_ids. Under A the client sends the hidden room's id for "No room" and every other room's for "In rooms"; under B the parameter needs a value for no room, such as room_ids=none. @no-label is the app's own: unlabeled=true, OR-ed with label_ids. The mockup fakes the room filter with StaticSoliplexApi.roomFilter.

What a conversation outside a room assumes:

  • No preset. It starts with no datasets, picked in the thread panel and fixed after the first message, like any thread. The agent and its skills would be the installation's default; the mockup does not model them.
  • No ceiling. Its level is that of the most restrictive dataset it uses, so it rises as datasets are added, and the band follows. It can never pass the user's own access, because the catalog lists nothing beyond it.
  • Labels, not rooms, group it. It is found through the conversations page, and through the Threads view with its label and room filters.

Two backend shapes could carry it, and the mockup follows the first:

A. A hidden room B. Threads without a room
Model The installation provides one room that the room list never shows. Thread.room_id becomes nullable.
Routes None new: every /v1/rooms/{room_id}/… route (runs, uploads, labels, feedback) works as is. Roomless twins of the thread, run, upload and label routes.
Thread listing Unchanged; the client maps the hidden room's id to "No room". room_id: null in GET /v1/agui/threads.
Agent The hidden room's agent config. An installation-level default, such as a default_agent_config_id.
Frontend The room screen without its rail as the conversations page; the rail and room list hide the room. A nullable room id through ThreadInfo, ThreadKey, RoomState and the routes.
Cost A room that is not really a room: its stats and uploads mix every user's conversations. A migration and a second set of routes.

A is the cheaper first step. B is cleaner if rooms later become folders that a thread can move in and out of.

Open questions:

  • A thread's level is derived on the client from its datasets. Should the backend store it, so the thread listing and other clients can show it?
  • Can a conversation move into a room, or a room thread move out? A move would change its preset and its ceiling partway through.
  • "In rooms" under A sends every room's id. With many rooms, an exclusion parameter, or a scope parameter, would be shorter.