feat(studio): refine Studio as a themed technical control room

Establish one coherent visual language across the Studio shell, empty states,
docked panes, traces, comparisons, and loading feedback. Add a dark
control-room default theme plus a supported light alternative mapped through
shared semantic tokens, with a title-bar theme control that persists local
preference and exposes state to assistive technology.

Add a non-dismissible first-run workspace gate for servers exposing
project-workspace session discovery, and a zero-configuration default local
harness source so the local Web workspace opens with a usable coder session.

Spec: docs/specs/2026-08-20-harness-studio-visual-redesign.md
Test: npm test in packages/harness-studio (121 passed)

Co-authored-by: QoderAI (Qwen 3.8 Max) <qoder_ai@qoder.com>

Author: phodal

DESIGN.md

@@ -18,6 +18,7 @@ colors:
   surface: "#FFFFFF"
   surface-subtle: "#F8FAFC"
   surface-hover: "#EEF1F5"
+  surface-active: "#E2E8F0"
   surface-selected: "#E7EFFB"
   border: "#D7DEE8"
   border-strong: "#B8C3D1"
@@ -38,6 +39,55 @@ colors:
   categorical-6: "#5E7F2E"
   categorical-7: "#7A7385"
 
+themes:
+  default: dark
+  light:
+    source: colors
+    overlay: "rgba(38, 50, 68, 0.34)"
+    scrollbar: "#B8C3D1"
+    scrollbar-hover: "#8D9BAD"
+    overlay-shadow: "0 18px 48px rgba(38, 50, 68, 0.2)"
+  dark:
+    primary: "#79A8FF"
+    primary-hover: "#9ABEFF"
+    primary-soft: "#142B4F"
+    on-primary: "#08111F"
+    text: "#E6EDF7"
+    text-muted: "#A6B2C3"
+    text-subtle: "#8492A6"
+    canvas: "#080C12"
+    titlebar: "#0C121C"
+    sidebar: "#0B1018"
+    workspace: "#111722"
+    panel: "#131A25"
+    surface: "#161F2C"
+    surface-subtle: "#0E141E"
+    surface-hover: "#1D2938"
+    surface-active: "#253348"
+    surface-selected: "#17345F"
+    border: "#2B3647"
+    border-strong: "#3C4B61"
+    focus: "#9FC1FF"
+    success: "#63D7A5"
+    success-surface: "#0E2B22"
+    warning: "#F2B76F"
+    warning-surface: "#352411"
+    danger: "#FF8A94"
+    danger-surface: "#35171D"
+    candidate: "#C5A7FF"
+    candidate-surface: "#251C3B"
+    categorical-1: "#7BB7E7"
+    categorical-2: "#B39AF4"
+    categorical-3: "#9AABC0"
+    categorical-4: "#6FD3BF"
+    categorical-5: "#E3AA61"
+    categorical-6: "#9BC36A"
+    categorical-7: "#B4AABD"
+    overlay: "rgba(2, 6, 12, 0.72)"
+    scrollbar: "#3C4B61"
+    scrollbar-hover: "#56667C"
+    overlay-shadow: "0 18px 48px rgba(0, 0, 0, 0.42)"
+
 typography:
   display:
     fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif"
@@ -281,6 +331,25 @@ Primary references:
 - Use Phosphor icons already owned by Studio. Do not use emoji, text glyphs, or
   improvised SVGs as interface icons.
 
+## Theme and visual direction
+
+- The default appearance is the dark technical-control-room theme. A supported
+  light theme maps the same semantic roles and remains available from a labelled
+  title-bar control. Theme choice is local presentation state, not server or
+  Session evidence.
+- The visual style is minimal and grid-led: tonal surface steps, neutral 1px
+  dividers, a blue interaction role, and semantic evidence colors. It may borrow
+  the discipline of Swiss minimalism, but it must not turn Studio into a landing
+  page, card dashboard, or decorative terminal pastiche.
+- Use the system UI stack in both themes. Generated recommendations for Web fonts
+  such as IBM Plex Sans or JetBrains Mono are references only; do not load them
+  unless the files are deliberately bundled and cross-platform tested.
+- Do not add glow, gradients, glass surfaces, or scroll-reveal choreography.
+  Hover, pressed, disclosure, pane, and loading transitions must explain state
+  and use the shared motion roles.
+- Measure dark and light contrast independently. A token name that passed in one
+  theme is not proof that its mapped value passes in the other.
+
 ## Information hierarchy
 
 Every surface must answer one primary question:
@@ -359,6 +428,10 @@ occupy more attention than the active task.
 - Shadows are forbidden on docked panes, rows, buttons, tabs, tables, empty
   states, and ordinary content groups. A shadow may only communicate a
   transient overlay above the workbench; it must disappear with that overlay.
+- A required first-run workspace chooser may use one centered floating dialog
+  above the dimmed workbench. It has one primary action, keeps the underlying
+  shell inert, cannot be dismissed into an unusable empty application, and
+  replaces itself with stable discovery progress until the workspace opens.
 - `full` radius is limited to a numeric count or circular target. Status text,
   evidence roles, filters, and navigation do not become pills by default.
 - Compact desktop text controls are 30px high and toolbar targets are at least

docs/specs/2026-08-20-harness-studio-local-web-workspace.md

@@ -50,6 +50,13 @@ surface exists.
   waiting for the native directory chooser or discovering workspace-matched
   Sessions. The Web UI polls that privacy-safe state and renders an indeterminate
   progress indicator with reduced-motion support.
+- **D-8: local Web owns a real default Debugger harness.** When workspace
+  Session discovery is available and no explicit harness was configured, the
+  server resolves a built-in single-session Qoder harness. Explicit harness
+  configuration still wins. After workspace selection, live runs use that
+  server-only directory as `cwd` and the default capability source root; no
+  absolute path is returned to the browser and no scripted demo executor is
+  substituted in production.
 
 ## Acceptance Scenarios
 
@@ -84,6 +91,11 @@ surface exists.
   live status first reports directory selection and then Session discovery, and
   completion automatically replaces the intake with the discovered Session
   list. No made-up percentage or absolute path is shown.
+- **AC-12:** The local Web Debugger is enabled without `--harness`, identifies
+  itself as the workspace default, opens the existing live-run composer, and
+  executes through the real built-in Qoder adapter in the selected workspace.
+  A caller-supplied harness/runtime remains authoritative, and a Studio server
+  without workspace discovery does not silently acquire a runnable endpoint.
 
 ## Non-goals
 
@@ -93,6 +105,8 @@ surface exists.
 - Editing, replaying, or writing back into imported sessions.
 - Shipping the public `better-harness web` package boundary in this first UI
   migration; the server and packaged-app ownership must be resolved first.
+- Faking an out-of-box run with a production scripted executor or bypassing the
+  selected host's normal authentication and permission boundaries.
 
 ## Plan and Tasks
 
@@ -126,6 +140,14 @@ Keep Studio's server start independent of data arguments. In a follow-up,
 package the built Studio runtime so the root command registry can dispatch
 `better-harness web` without repository-only paths.
 
+### 6. Provide the local default Debugger harness
+
+Resolve a compiler-valid built-in Qoder harness only for the local
+workspace-discovery host. Keep explicit harness configuration authoritative,
+bind execution to the selected workspace on the server, label the active
+default in the UI, and exercise the same AG-UI/live-run path as configured
+harnesses.
+
 ## Test and Review Evidence
 
 - AC-1/AC-8: empty-start model and Playwright assertions for UI copy and actions.
@@ -142,15 +164,21 @@ package the built Studio runtime so the root command registry can dispatch
 - AC-11: HTTP tests pause the injected chooser and provider to verify the two
   status stages; Playwright verifies the live discovery message, progress
   indicator, disabled action, and automatic transition to the Session list.
+- AC-12: server tests resolve and execute the default harness with an injected
+  deterministic executor while asserting the selected workspace `cwd` and
+  source root; Playwright opens Debugger after workspace discovery and completes
+  a live run through the default AG-UI path.
 
 Implementation evidence (2026-08-20):
 
-- `npm test` in `packages/harness-studio`: 18 files, 118 tests passed,
-  including controlled chooser/discovery stage transitions.
-- `npm run test:browser` in `packages/harness-studio`: 15 Playwright tests
+- `npm test` in `packages/harness-studio`: 18 files, 121 tests passed,
+  including controlled chooser/discovery stages and default-harness execution
+  rooted at the selected workspace.
+- `npm run test:browser` in `packages/harness-studio`: 16 Playwright tests
   passed, including the workspace intake, discovered Session detail, Compare,
-  animated discovery status, wide/compact/narrow screenshots, keyboard focus,
-  overflow, console, and page error checks.
+  the default live Debugger flow, animated discovery status,
+  wide/compact/narrow screenshots, keyboard focus, overflow, console, and page
+  error checks.
 - `npm test` at the repository root: 99 files, 1412 tests passed.
 - A live in-process discovery smoke against this repository returned the bounded
   100-Session catalog: Qoder 79, Codex 16, and Claude 5.

docs/specs/2026-08-20-harness-studio-visual-redesign.md

@@ -0,0 +1,152 @@
+# Refine Harness Studio as a technical control room
+
+## Traceability
+
+- Spec ID: harness-studio-visual-redesign
+- Status: Implemented
+
+## Intent
+
+Harness Studio should feel like a deliberate local developer workbench rather
+than an unstyled collection of dense tables. The redesign keeps the existing
+`Workspace -> Sessions -> Detail / Compare -> Artifacts` information
+architecture, while establishing one coherent visual language across the shell,
+empty states, docked panes, traces, comparisons, and loading feedback.
+
+The direction combines the repository's VS Code-inspired docked workbench
+contract with the verified `ui-ux-pro-max` recommendation for a minimal,
+high-contrast developer tool: restrained dark surfaces, a supported light
+alternative, semantic color, system typography, dense evidence rows, and subtle
+motion. The generated FAQ layout, unbundled Web fonts, green primary CTA, and
+scroll-reveal effects do not fit the product and are intentionally excluded.
+
+## Acceptance Scenarios
+
+- **AC-1:** A fresh Studio load uses the dark technical-control-room theme. A
+  labelled title-bar control switches between dark and light themes, persists
+  the local preference, and exposes its current state to assistive technology.
+- **AC-2:** Shared semantic tokens own both themes. Studio components introduce
+  no one-off colors, fonts, radii, shadows, or motion durations outside the
+  approved token source, and docked regions remain flat and edge-to-edge.
+- **AC-3:** The application shell has a clear hierarchy at first glance:
+  product identity and top-level tools on the left, current context and scoped
+  actions in the title bar, and one primary workspace surface. Selection,
+  availability, hover, focus, pressed, and disabled states are distinguishable.
+- **AC-4:** Overview and workspace-intake screens show one dominant next action,
+  readable supporting context, and stable loading feedback without becoming
+  card dashboards or decorative landing pages.
+- **AC-5:** Session rows establish provider and observed time before prompt,
+  keep compare selection separate from opening, and reveal a legible detail
+  timeline. Dense metadata uses tabular figures where alignment matters.
+- **AC-6:** Session Compare visually distinguishes the two evidence lanes using
+  labels and semantic lane treatments, retains the explicit no-winner boundary,
+  and keeps tables and tool sequences readable without color-only meaning.
+- **AC-7:** Icons use the existing Phosphor family. Decorative icons are hidden
+  from the accessibility tree; icon-only controls have an accessible name,
+  state where applicable, visible focus, and a tooltip.
+- **AC-8:** At 1440x900, 1024x768, 390x844, and 375x812, the primary decision is
+  visible, the document has no horizontal overflow, panes use bounded local
+  scrolling, and narrow controls provide at least 44px targets.
+- **AC-9:** Keyboard navigation, 200% zoom/reflow, light-theme and dark-theme
+  contrast, async live regions, and `prefers-reduced-motion` remain usable.
+- **AC-10:** Playwright captures meaningful non-loading screenshots of Overview,
+  workspace intake, Session browser, Session Compare, Artifact View, Bench,
+  Live trial, and Evidence results, with no browser console or page errors.
+- **AC-11:** When the server exposes project-workspace Session discovery and no
+  workspace is connected, Studio opens with a non-dismissible modal workspace
+  gate. The shell remains visible but inert and hidden from assistive
+  technology; successful discovery removes the gate and opens Sessions.
+  Preconfigured servers without workspace discovery keep their existing direct
+  entry into the relevant workbench.
+
+## Non-goals
+
+- Changing the project-workspace and Inspector Session-discovery architecture.
+- Introducing cards as the default container, gradients, glassmorphism, glow,
+  illustration assets, emoji icons, or marketing-page sections.
+- Loading Google Fonts, adding GSAP, or depending on network-hosted visual
+  assets.
+- Redesigning the separately owned Canvas artifact viewer rendered in its
+  sandboxed iframe.
+- Adding new data sources, evaluation semantics, or Session write-back.
+
+## Plan and Tasks
+
+### 1. Extend the visual source of truth
+
+Record the verified dark/light palette, theme behavior, motion roles, and
+control-room rationale in `DESIGN.md`. Keep the existing system font and
+semantic evidence roles.
+
+### 2. Rebuild shared visual primitives
+
+Update `styles/tokens.css` with dark-default and light-theme mappings, theme and
+motion roles, predictable focus/pressed/disabled states, and narrow target
+sizes. Keep every surface mapped to shared tokens.
+
+### 3. Refine shell and workspaces
+
+Update the React shell and `styles/shell.css` / `styles/workbench.css` so the
+brand, navigation, title bar, Overview, empty state, Sessions, detail timeline,
+Compare, Artifact View, Bench, Live trial, and Evidence results share the same
+hierarchy and density.
+
+### 4. Add explicit theme control
+
+Add a local, accessible dark/light toggle in the title bar. Apply the theme
+before meaningful paint where practical and preserve the user's selection
+without involving the server.
+
+### 5. Validate the actual product
+
+Build Studio, run behavioral tests, exercise all changed surfaces with
+Playwright, inspect console/page errors, verify overflow/focus/reduced motion,
+and visually review the required screenshots before marking this spec
+implemented.
+
+## Test and Review Evidence
+
+- AC-1/AC-2: theme-state unit/browser assertions plus parsed token/style-source
+  checks for approved semantic roles and absence of one-off visual literals.
+- AC-3/AC-4: Playwright shell, Overview, empty-state, hover/pressed/disabled,
+  and single-primary-action checks.
+- AC-5/AC-6: Session browser and Compare interaction tests and screenshots in
+  both themes, including independent checkbox/open behavior and no-winner copy.
+- AC-7: role/name/state assertions, keyboard focus checks, and icon ownership
+  review.
+- AC-8: overflow and screenshot checks at all four required viewport sizes.
+- AC-9: reduced-motion, 200% zoom/reflow, keyboard order, live-region, and
+  measured foreground/background contrast checks.
+- AC-10: full Studio Playwright suite with captured screenshots and empty
+  console/page-error collections.
+- AC-11: server capability assertion plus Playwright dialog, inert-shell,
+  responsive screenshot, loading-state, and post-selection navigation checks.
+
+### Recorded validation
+
+- `npm run typecheck` and `npm run build` in `packages/harness-studio` passed.
+- `npm test` in `packages/harness-studio` passed 18 files and 121 tests.
+- `npm run test:browser` in `packages/harness-studio` passed all 16 Playwright
+  scenarios, including the real provisioned `deck.pptx` Canvas viewer.
+- Playwright verified 1440x900, 1024x768, 390x844, and 375x812 layouts,
+  theme persistence, rendered foreground/background contrast of at least 4.5:1,
+  keyboard focus, reduced motion, bounded scrolling, and no page-level
+  horizontal overflow.
+- Screenshots were visually reviewed for Overview, workspace intake and loading,
+  Session browser, Session Compare, Artifact View, Bench, Live trial, and
+  Evidence results. Browser console and page-error collections were empty.
+
+### Risks
+
+- Dark-theme muted text and semantic states can appear polished while missing
+  WCAG contrast. Measure actual rendered pairs rather than reviewing hex values
+  by sight.
+- A global token change affects every Studio surface. Validate Bench, Live
+  trial, Evidence results, and artifact code/diff previews in addition to the
+  new Session flow.
+- Theme persistence can cause a flash or stale state if it is applied only after
+  React mounts. Initialize the root theme deterministically and keep storage
+  failure non-fatal.
+- Embedded Inspector and Canvas viewers own separate rendering contexts. Do not
+  claim theme parity inside an iframe unless that owner exposes a supported
+  theme contract.