Unified Studio UI prototype¶
Status: Current | Last reviewed: 2026-09-23
This page records the original combined snapshot under studio/real. New design work and exports use apps/ai-manager, which now includes the conversational preview behind the runtime flag FEATURE_CONVERSATIONAL_DESIGN. See the current rollout and export guide.
Designer handoff instructions¶
The prototype's exporter installs
prototype/designer-claude.md
as the ZIP's root CLAUDE.md, with an AGENTS.md dispatcher. This guidance
only activates in the export; main repository agent guides are unchanged.
It instructs coding agents to explain feature behavior and required inputs,
push back on unintended capability loss, propose informed alternatives, and
record backend follow-up alongside the designer's changes. See
Design prototype mode
for the export and import boundaries.
Application structure¶
The application retains the existing permission checks, service catalog, editor components and MSW prototype backend. The root redirects to /dashboard, the operational Home adapted from trueserve-dashboard.zip. Design with AI opens /studio; Insights is deferred and /dashboard/insights redirects to Home. The expanded/compact sidebar uses the dashboard's teal identity and Open Sans typography. All agent types share one Agents destination, including background agents (previously called workflows). Simulator and emulator custom sidebar entries are omitted.
See Dashboard integration and backend follow-up for the capability-preservation map, confirmed decisions and backend gaps.
| Source | Responsibility |
|---|---|
| StudioDashboard | Operational landing page, attention, portfolio, activity, favorites and Design with AI entry |
| StudioHome | Design with AI: prompt entry, use cases, saved briefs, combined prototype agent preview, manual wizard access |
| StudioRepository | Shared /agents list, type/search/favorite filters, sorting, pagination and creation/import controls |
| WorkspaceScreen | /studio/build/[briefId], persistent design state and agent creation |
| Studio styles | Identity adapted to existing HSL tokens; responsive layout |
| Brief storage | Versioned, validated localStorage records |
| Agent payload adapter | Converts an authored brief into the existing create payload |
Flow, behavior, scenario and knowledge components are adapted from studio/proto. Heavy Systems, Scenarios and Knowledge tabs load on demand. Systems reuses the existing StackStep and ToolSelector, so runtime, integration and tool identifiers come from the same sources as the manual wizard.
Shared repository¶
/agents lists all agent types together, sorted by last modification. Cards are the default presentation, with an optional compact list. Status/creation/modification filters and browser-local recent visits complement the existing type/search/favorites controls. The display taxonomy is Voice, Chat, Copilot, Translation and Background. Workflows are labeled Background agents in the list, creation wizard and management dialogs. STUDIO_AGENT_TYPES maps the display types to the existing wizard choices; agentType drives list filters, while the existing kind continues to select the API, editor route and favorite namespace. /workflows redirects to that list; /agents/[id] and /workflows/[id] retain their existing editors. Home previews the same combined data and searches every agent type, including the Background label.
useRepository loads /api/pipelines and /api/workflows concurrently, gated independently by feature flags and permissions. The list route accepts either manage permission; editor routes keep their type-specific checks. A failed source displays a retry action without hiding the other source. Type-prefixed row keys keep agent and workflow IDs distinct.
New agent offers all five types at the same level and opens the existing wizard for the selected type. Agent creation deep links (?newAgent=1&type=&template=) remain supported. Import offers conversational-agent and background-agent JSON/ZIP imports, including reference mapping. Each row's Manage button reuses the original table controls in a compact dialog for tags, cloning, export, deletion and workflow activation. Favorites retain their existing API and entity types. Search covers names, descriptions, type labels, IDs and tags.
Custom sidebar links matching emulator/simulator destinations are filtered only in the UI; fixture data is retained. In-editor preview controls remain available. Mobile navigation closes after choosing a destination.
Persistence and runtime boundary¶
Briefs use agent-studio:brief:v1:<id> localStorage entries. They hold the design conversation, flow, behavior, scenario definitions, knowledge metadata, runtime choices and created agent ID. Invalid records do not prevent the home screen from listing the remaining briefs. A save failure remains visible; Download design brief exports the current record.
Create agent draft uses buildStackInitialConfig() and POST /api/pipelines. The adapter writes the prompt to stage.config.template.inline and mirrors it into messages, matching the existing editor's prompt contract. It copies selected tool IDs onto conversational stages and supplies stack author overrides for every derived voice/chat variant. Tests pin this publish-time behavior across stack families.
Flow steps and behavior become prompt instructions. They do not create executable router nodes, enforced response guards or subagent configurations. Configure those in the existing editor. Scenarios, chat state and knowledge metadata remain outside runtime config.
After creation the brief remembers the agent ID and opens that editor on subsequent visits. Later edits to the brief do not overwrite runtime changes in the agent editor. This avoids replacing independently authored prompts, tools or pipeline structure.
The editor toolbar exposes Design brief when this browser has a brief for that agent. You can move between the two views without creating another draft.
Editing existing agents¶
Published versions remain read-only. The editor explains this beside the toolbar. Open draft navigates directly to an existing editable draft; Save As Draft creates one when needed. Once the draft is open, prompt typing, @ / {{ completion, snippet browsing and Actions dialogs use the original editor components.
The prototype's PUT /api/pipelines/:id handler now implements the real save response (isDraft, versionId), stores the draft under its versioned path, updates the list/version metadata and redirects subsequent bare-ID opens to the draft. It preserves a separate published snapshot and rejects writes to explicit published-version URLs. The loopback collaboration gateway resolves the current draft destination at each flush, including when a draft is created while the room is already open. Explicit flush requests wait for those local writes to finish.
Published mock responses inherit edit permission from the agent identity, including releases saved by older prototype builds with an incorrect canEdit:false. The editor still gates edits on draft status; this does not unlock published content or view-only identities.
Prototype limits¶
The design assistant uses the supplied category matching, quick replies and scripted text. It makes no model calls. Scenario runs are simulations. Knowledge additions retain file names or URLs; there is no ingestion or retrieval pipeline. Configure a knowledge tool through Systems or the full editor.
Scenario JSON imports parse the selected file and validate 1–500 records with situation and expectedBehavior fields. Imports receive new IDs. Sample conversations use the supplied fixtures and do not connect to customer systems.
The existing prototype fixture loader, reset control and phone loopback are unchanged. Reset data resets the prototype backend; brief records use a separate namespace and remain in browser storage.
The captured mock backend has no dedicated handlers for POST /api/pipelines/import or POST /api/workflows/import. The shared import UI retains the real API contract and reference-mapping dialogs, but rejects generic mock responses without a created ID with a clear message rather than navigating to an invalid editor.
The terminology change affects presentation only. Workflow IDs, /api/workflows contracts, storage, permissions and editor URLs retain their existing names. No API contract or generated schema changes are introduced.
Run and verify¶
cd studio/real/apps/ai-manager
npm install
npm run dev
npm run typecheck
node --import tsx --test lib/studio/agent-payload.test.ts
npx eslint components/studio lib/studio hooks/studio 'app/(main)/studio'
npx playwright test --config playwright.studio.config.ts
dev and dev:only delegate to dev:prototype, which enables the mock backend
and uses port 3100. The standalone package has no predev port-forwarding hook;
the monorepo app can continue using port 3001. If the prototype is already
running, use that instance. To change its port, stop it first and run
npm run dev -- --port 3101; both starts use the same .next-prototype directory.
Verify prompt entry → design edits → Systems selection → draft creation → full editor. Reload a brief and check its title, behavior, tools and conversation. Check both desktop and mobile layouts and check the shared repository, both editor types, tools, settings and insights. Verify type filters, search, favorites, creation/import menus, legacy /workflows redirect, retry after a source failure, and absence of simulator/emulator sidebar links.