Skip to content

[docs] Draft playground workspace PRD and initial RFC - #6775

Open
mmabrouk wants to merge 3 commits into
mainfrom
agent/playground-workspace-design
Open

mmabrouk wants to merge 3 commits into
mainfrom
agent/playground-workspace-design

Conversation

@mmabrouk

@mmabrouk mmabrouk commented Sep 11, 2026

Copy link
Copy Markdown
Member

The agent playground currently combines session tabs with dedicated configuration and file panes. This proposes one or two panes with movable tabs so a user can keep a conversation beside a file, another session, or an internal app.

Try the interactive mockup

Includes a draft PRD, a rough initial RFC, and a standalone React mockup for frontend discussion. The mockup imports Agenta's actual Button, Tabs, SplitPane, and theme tokens. Try moving tabs, resizing or collapsing panes, preserving a conversation draft, and using the example board beside chat.

Playground workspace concept

How to review

  1. Read docs/design/playground-workspace/prd.md for the experience and proposed first scope.
  2. Read docs/design/playground-workspace/rfc.md for state ownership, runtime preservation, performance, library options, and open decisions.
  3. Use docs/design/playground-workspace/mockup/README.md for the walkthrough, component reuse, and local build instructions.

Related to #6529: this proposal supplies the tab host for workspace-backed HTML apps. #6529 owns Run mode, file-access grants, and the iframe bridge. The example board uses local sample data; it does not implement that bridge. Website and computer views are placeholders. No production application behavior changes.

Validation

  • TypeScript check and Vite production build passed.
  • Hosted Chromium checks passed for tab movement by drag and button, draft preservation across move/collapse/reload, keyboard resizing, adding/closing tabs, and board updates reflected in Files.
  • Inspected light/dark screenshots; no JavaScript errors in the exercised flows.
  • Markdown links and git diff --check verified.

This demonstrates the idea; it does not validate production streaming performance or backend behavior.

@vercel

vercel Bot commented Sep 11, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
agenta-documentation Ready Ready Preview Sep 11, 2026 9:55am UTC

Request Review

@github-actions

github-actions Bot commented Sep 11, 2026

Copy link
Copy Markdown
Contributor

📘 Docs preview

Status ✅ Ready
Preview https://pr-6775-agenta-docs-preview.mahmoud-637.workers.dev/docs
Inspect Actions run
Commit ce32e8baf0df7492a7e05bcf595b0f99c572bcc5

This comment updates in place on every push.

@coderabbitai

coderabbitai Bot commented Sep 11, 2026

Copy link
Copy Markdown
Contributor

Review Change StackReview Change Stack

📝 Summary

Summary by CodeRabbit

  • Documentation
    • Added draft design documentation for a playground workspace experience.
    • Describes a one- or two-pane layout with movable tabs for conversations, files, explorers, and applications.
    • Defines proposed product requirements, user behaviors, success criteria, glossary terms, and open decisions.
    • Documents the proposed architecture, layout policies, persistence, performance considerations, and implementation questions.
    • Added an interactive mockup demonstrating draggable tabs, resizable panes, scenario controls, theme switching, and browser-persisted state.
    • Clarifies that opening an HTML tab alone must not execute author-provided scripts.

Walkthrough

The PR adds product and architecture documents for a one- or two-pane playground workspace and a React/Vite mockup with movable tabs, multiple content views, persistence, responsive styling, and deployment configuration.

Changes

Playground workspace design and mockup

Layer / File(s) Summary
Workspace proposal and product scope
docs/design/playground-workspace/README.md, docs/design/playground-workspace/prd.md
Defines the workspace concept, tab types, proposed behaviors, initial scope, success criteria, and open decisions.
Workspace architecture and implementation direction
docs/design/playground-workspace/rfc.md
Describes current architecture and proposes workspace state ownership, view lifecycle, persistence, permission boundaries, implementation options, and engineering questions.
Interactive workspace mockup behavior
docs/design/playground-workspace/mockup/index.html, docs/design/playground-workspace/mockup/src/main.tsx
Adds a React mockup with split panes, draggable tabs, local persistence, scenario controls, conversation and file views, explorer behavior, and an interactive board.
Mockup styling and delivery configuration
docs/design/playground-workspace/mockup/src/style.css, docs/design/playground-workspace/mockup/package.json, docs/design/playground-workspace/mockup/tailwind.config.ts, docs/design/playground-workspace/mockup/tsconfig.json, docs/design/playground-workspace/mockup/vite.config.ts, docs/design/playground-workspace/mockup/postcss.config.js, docs/design/playground-workspace/mockup/wrangler.jsonc, docs/design/playground-workspace/mockup/README.md
Adds responsive styling, build and type-check configuration, dependency configuration, Cloudflare deployment settings, and mockup usage documentation.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: 🟡 Moderate · up to ce32e

Core workspace actions can leave tabs without visible content or leave the requested opposite pane empty. Keyboard users also cannot see when the composer is focused. Resolve these interaction issues before using the mockup for product evaluation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 60.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 4 files. (7 skipped: 7 … Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description check ✅ Passed The description accurately summarizes the draft PRD, RFC, interactive mockup, relationship to #6529, and validation scope.
Title check ✅ Passed The title clearly identifies the documentation changes: a draft playground workspace PRD and initial RFC.
Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 60.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 4 files. (7 skipped: 7 unsupported.)

  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch agent/playground-workspace-design

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Advanced

Run ID: e1838e6b-0ee1-4f55-bff5-2343a5272b4d

📥 Commits

Reviewing files that changed from the base of the PR and between f94c539 and ce32e8b.

⛔ Files ignored due to path filters (3)
  • docs/design/playground-workspace/mockup/package-lock.json is excluded by !**/package-lock.json
  • docs/design/playground-workspace/mockup/preview-app.png is excluded by !**/*.png
  • docs/design/playground-workspace/mockup/preview.png is excluded by !**/*.png
📒 Files selected for processing (11)
  • docs/design/playground-workspace/README.md
  • docs/design/playground-workspace/mockup/README.md
  • docs/design/playground-workspace/mockup/index.html
  • docs/design/playground-workspace/mockup/package.json
  • docs/design/playground-workspace/mockup/postcss.config.js
  • docs/design/playground-workspace/mockup/src/main.tsx
  • docs/design/playground-workspace/mockup/src/style.css
  • docs/design/playground-workspace/mockup/tailwind.config.ts
  • docs/design/playground-workspace/mockup/tsconfig.json
  • docs/design/playground-workspace/mockup/vite.config.ts
  • docs/design/playground-workspace/mockup/wrangler.jsonc
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/design/playground-workspace/README.md

Included review availability: Your plan provides up to 8 included reviews per hour; 5 remain after this review.

panes: [
{
ids: s.panes.flatMap((p) => p.ids),
active: s.panes[s.focus].active || s.panes[0].active,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Select an active tab from either pane when merging.

When the focused pane is empty, this expression can set active to "" even when the other pane has tabs. For example, close all tabs in the focused left pane, then select “One pane.” The merged workspace shows no content until the user selects a tab.

Proposed fix
-                active: s.panes[s.focus].active || s.panes[0].active,
+                active:
+                  s.panes[s.focus].active ||
+                  s.panes.find((p) => p.active)?.active ||
+                  s.panes.flatMap((p) => p.ids)[0] ||
+                  "",
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
active: s.panes[s.focus].active || s.panes[0].active,
active:
s.panes[s.focus].active ||
s.panes.find((p) => p.active)?.active ||
s.panes.flatMap((p) => p.ids)[0] ||
"",

Comment on lines +211 to +212
open(id, 1);
} else open(id, n === 0 ? 1 : 0);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Move an existing resource to the target pane.

When the layout has one pane and that pane already contains id, openOther adds pane 1 and then calls open(id, 1). The open updater sees the added pane, finds id in pane 0, and only activates it there. Pane 1 remains empty.

Compute the target pane, then call move(id, target) when id exists in another pane. Otherwise call open(id, target).

Proposed fix
 const openOther = (id: string, n: number) => {
+  const target = state.panes.length === 1 ? 1 : n === 0 ? 1 : 0;
   if (state.panes.length === 1) {
     set((s) => ({ ...s, panes: [...s.panes, { ids: [], active: "" }] }));
-    open(id, 1);
-  } else open(id, n === 0 ? 1 : 0);
+  }
+  const current = state.panes.findIndex((p) => p.ids.includes(id));
+  if (current >= 0 && current !== target) move(id, target);
+  else open(id, target);
 };
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
open(id, 1);
} else open(id, n === 0 ? 1 : 0);
const openOther = (id: string, n: number) => {
const target = state.panes.length === 1 ? 1 : n === 0 ? 1 : 0;
if (state.panes.length === 1) {
set((s) => ({ ...s, panes: [...s.panes, { ids: [], active: "" }] }));
}
const current = state.panes.findIndex((p) => p.ids.includes(id));
if (current >= 0 && current !== target) move(id, target);
else open(id, target);
};

resize: none;
width: 100%;
height: 44px;
outline: none;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Keep a visible keyboard focus indicator on the composer.

This later rule overrides the global textarea:focus-visible outline because both selectors have equal specificity. Keyboard users cannot see focus in the message composer.

Remove this declaration or add an equally specific visible focus rule.

Proposed fix
 .composer textarea {
   resize: none;
   width: 100%;
   height: 44px;
-  outline: none;
   background: transparent;

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant