workspaces 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c580535eeb20692a3454144150752141b76eeed504ca7f13d59f2ee498e5e8eb
-  data.tar.gz: dc5fbe433b8ffd2c485bdbf91bcb2aae72bf4010926f4c0106361cc5a1369ce6
+  metadata.gz: fc21704825da052eb9cde1ea64cf3ab4958242f08492cf2a5b538d6fd97ebca3
+  data.tar.gz: 46dc25654e97ef6fb461058470dcfeb56e5a82720fa6df875c5b3c34b5d273a6
 SHA512:
-  metadata.gz: 3287a5de3b491b3df3573494b43afa9a099aae057e535943fd4fd277b09e4b3755b37bf566894cab253804eb39ae009ed21f887414c4dad51b81f4ce816bbba8
-  data.tar.gz: 623e7caec5c6bdc116c350efe7ffde325e3cdb66e22c473f69cbe6efecc65de12c1d3e794c8625e9a01c24db6f783e828105e52cfa03b6005f5409fabe5f9131
+  metadata.gz: daa43e3151dd5bb2e4239ae61ca9322101eb8793d437a91782dfa71ec078ce42721d384bea49564c0929a087b9476ab8c76d44860ad806ab3dab7e4145352193
+  data.tar.gz: 61d43cac06ed0948041320abf6d0a876697241a26063f5aa3f85537580cea660c8e0c7af2e8589fad80a32c6d3ba8432140e959a9fee70ba791ca92f3c81534a

data/DESIGN.md

@@ -48,19 +48,24 @@ Restrained tooling UI: dark elevated panels, compact spacing rhythm, clear statu
 - **PR source update**: a secondary Update from PR form only for PR-sourced workspaces; it fetches the latest PR head, fast-forwards the checkout, and preserves local edits without rebuilding or restarting. A persistent result message explains when rebuild is needed or when a retained stash needs manual recovery.
 - **Failure panel**: prominently above the log, with escaped error details and a matching retry action.
 - **PR page**: existing workspaces are primary; creating another is a collapsed secondary disclosure. Creation is primary only when none exist.
-- **Lifecycle state machine**: the workspace detail page is driven by `Presentation::STATES`. Each state (`idle`, `busy`, `ready`, `stopped`, `error`/`interrupted`, `unknown`) declares which sections exist (progress, actions, environment, log, details, danger zone) and the label of the single environment-form button. Sections that are not usable or meaningful in a state are hidden, never shown disabled. The server renders the initial state and the polling script re-applies it from `presentation.sections`, so the page transitions without a reload.
-  - `idle` (brand new): only the environment editor plus a **Start workspace** button, with a one-line hint. No log, actions, details, or delete.
-  - `busy` (setup/restart running): only progress and the live log.
-  - `ready`: everything, with **Save & restart**.
-  - `stopped`: no progress from the previous run; **Save & start**.
-  - `error`/`interrupted`: retry action, environment editor, progress, and logs; **Save & retry**.
+- **Three layers**: the workspace page leads with the friendly, the deliberate, then the technical. Each layer is shown or collapsed by lifecycle state, driven by `Presentation::STATES`:
+  1. **Lead** (always visible): a plain-language headline, one sentence, and at most one primary action (a large button). The setup steps never appear here.
+  2. **Settings** (a `<details>` titled *Change settings*, or *Choose what to preview* on a brand new workspace): presets first, as buttons, then the environment variables. The one submit button names what it does (Start workspace, Save & restart, Save & start, Save & retry). It starts open only for a new workspace.
+  3. **Technical details** (one `<details>`): setup steps with timings, the live log, workspace controls (rebuild, restart, stop, update from PR), preview URL, branch and path, and the Danger Zone. It starts collapsed, and opens by itself while setup runs or after a failure so a cause is never hidden.
+- **Lead by state**:
+  - `idle`: "Let's get your workspace running", with the settings open and *Start workspace* in the form.
+  - `busy`: "Setting things up…", with the current step as a quiet line and the elapsed time. Technical details open so progress and the log can be watched.
+  - `ready`: "Your workspace is ready" with a large **Open workspace** button. Everything else is collapsed.
+  - `stopped`: "Your workspace is paused" with a large **Start workspace** button.
+  - `error`/`interrupted`: a plain "Something didn't go to plan" with a large **Retry** button, the error shown, and technical details open.
+  - `unknown`: a minimal view with technical details open.
+- **Disclosure behavior**: the server renders the initial open state and the polling script re-applies it from `presentation.open`, but only when the state changes. A section the user opened or closed is left alone on later polls. Sections that are not meaningful in a state are hidden, never shown disabled.
 - **Action buttons**: start, prepare/rebuild, restart server, stop server, and refresh
-- **Actions & settings panel**: status-adjacent panel that combines routine lifecycle controls, Open workspace, Refresh status, PR update messaging, and editable environment settings so routine operations stay in one keyboard-reachable region.
 - **Open workspace**: success-styled link available when the server is ready
 - **Lifecycle controls**: hidden while busy (see state machine); helper text distinguishes rebuilding from server-only restart
 - **Bounded log panel**: monospace text, fixed max height, manual-scroll-safe updates
 - **Log source switcher**: two native links inside one log panel, with current selection announced through `aria-current`; only the selected bounded log is loaded and refreshed. Setup is the default.
-- **Preview destination**: a small muted URL in Workspace details, visible before readiness; the primary Open workspace action remains reserved for ready servers.
+- **Preview destination**: a small muted URL in Technical details, visible before readiness; the large Open workspace button is reserved for ready servers.
 - **Editable environment**: labelled monospace multiline `NAME=value` control for non-secret recipe defaults and added workspace settings; busy state disables the fieldset and save button, values are escaped in HTML, other legacy overrides remain hidden. Omitted default names revert to recipe defaults; omitted added names are unset.
 - **Environment presets (JS-enhanced)**: optional preset selector is hidden by default and revealed only when JavaScript is active and presets exist. Selecting a preset replaces the entire draft editor content and announces unsaved state without submitting. Draft edits remain local until Save & restart.
 - **Danger Zone**: isolated section on the detail page with explicit loss-of-uncommitted-and-untracked-work copy, an exact-workspace-ID confirmation field, and a destructive action. Deletion remains possible without JavaScript, is disabled while setup is busy, and never appears as a list-row action.

data/README.md

@@ -143,6 +143,64 @@ The front door is not an authentication boundary. Its host and same-origin check
 protect routing and POST actions, but a publicly reachable instance still needs
 access control such as VPN or SSO. Do not expose workspace backend ports directly.
 
+### Proxy middleware
+
+The front door can run Rack middleware around traffic that is forwarded to a workspace
+backend. The gem knows nothing about what a middleware does: the container or host
+that runs `serve` registers its own. Typical uses are injecting a script tag, adding a
+header, or logging.
+
+```ruby
+# my_middleware.rb
+Workspaces.configure_proxy do
+  use MyMiddleware, option: 'value'
+end
+```
+
+Load it with `serve --require FILE` (repeatable) or by setting `WORKSPACES_REQUIRE` to
+one or more paths separated like `PATH` entries. Environment entries load first, then
+`--require` files in order. A missing file or an error while loading stops `serve` with
+a non-zero exit instead of silently running without it. These files are executed with
+the front door's privileges, so only name files the operator controls. With nothing
+registered, the front door behaves exactly as before.
+
+Blocks run in registration order and the first `use` is outermost. The stack wraps only
+the step that forwards a request to a ready workspace backend. The dashboard, redirects
+for workspaces that are not ready, and error pages never pass through it. For each
+proxied request, two Rack env keys are available:
+
+| Key | Value |
+| --- | --- |
+| `workspaces.workspace_id` | The workspace ID, such as `main-1ae4815f` |
+| `workspaces.workspace` | The workspace snapshot hash (branch, status, related PR, and so on) |
+
+Two details matter when rewriting response bodies. The proxy passes the browser's
+`Accept-Encoding` to the backend, so a compressed response arrives compressed; set
+`env['HTTP_ACCEPT_ENCODING'] = 'identity'` before calling the app, or skip responses
+with a `Content-Encoding` header. If you change the body, drop the stale `Content-Length`
+header. An example that appends a script tag to HTML pages:
+
+```ruby
+class ScriptInjector
+  TAG = '<script src="https://example.test/widget.js" data-thread-id="%<id>s"></script>'
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    env['HTTP_ACCEPT_ENCODING'] = 'identity'
+    status, headers, body = @app.call(env)
+    return [status, headers, body] unless headers['content-type'].to_s.start_with?('text/html')
+
+    html = body.each.to_a.join.sub('</body>', format(TAG, id: env['workspaces.workspace_id']) + '</body>')
+    [status, headers.reject { |key, _| key.casecmp?('content-length') }, [html]]
+  end
+end
+
+Workspaces.configure_proxy { use ScriptInjector }
+```
+
 ### Local HTTPS
 
 To serve TLS directly, install/trust a local CA and create a certificate covering
@@ -198,6 +256,7 @@ and forwarded scheme/host headers; it does not change the internal listener to T
 | `WORKSPACES_PUBLIC_ORIGIN` | `http://localhost:4747` | Browser-facing dashboard origin and scheme |
 | `WORKSPACES_BASE_DOMAIN` | `localhost` | Preview hostname suffix |
 | `WORKSPACES_SUBDOMAIN_PREFIX` | `ws-` | Prefix before the workspace ID on preview hosts |
+| `WORKSPACES_REQUIRE` | none | Ruby files, separated like `PATH`, loaded by `serve` to register proxy middleware |
 
 Keep the project root, public origin, preview domain, and storage settings consistent
 across CLI and server processes. Changing the browser-facing origin requires restarting

data/lib/workspaces/cli.rb

@@ -5,6 +5,7 @@ require 'rack/handler/puma'
 require_relative 'registry'
 require_relative 'coordinator'
 require_relative 'front_door'
+require_relative 'proxy_middleware'
 require_relative 'tls'
 require_relative 'child_env'
 
@@ -86,6 +87,7 @@ module Workspaces
     end
 
     def parse_tls_options(parser, options)
+      parser.on('--require PATH') { |value| (options[:require] ||= []) << value }
       parser.on('--secure') { options[:secure] = true }
       parser.on('--tls-cert PATH') { |value| options[:tls_cert] = value }
       parser.on('--tls-key PATH') { |value| options[:tls_key] = value }
@@ -93,6 +95,7 @@ module Workspaces
 
     def serve(_id, options)
       tls = Tls.from_serve_options(options)&.validate!
+      ProxyMiddleware.load_files(ProxyMiddleware.env_paths + options.fetch(:require, []))
 
       if tls
         tls.apply_env_defaults { serve_with_tls(tls) }
@@ -196,7 +199,7 @@ module Workspaces
     end
 
     def usage
-      'Usage: bin/workspaces serve | create (--branch REF | --pr NUMBER | --new-branch NAME [--from REF]) [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
+      'Usage: bin/workspaces serve [--require FILE] | create (--branch REF | --pr NUMBER | --new-branch NAME [--from REF]) [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
         'list [--pr NUMBER] [--json] | show/start/prepare/restart ID [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | stop ID | ' \
         'exec ID -- COMMAND... | remove ID [--force]'
     end

data/lib/workspaces/dashboard/app.js

@@ -14,7 +14,7 @@
   let actionsSignature = null;
   function toggleBusyState(nextBusy) {
     busy = !!nextBusy;
-    root.querySelectorAll('.workspace-actions button').forEach((button) => {
+    root.querySelectorAll('.workspace-actions button, .lead__action button').forEach((button) => {
       button.disabled = busy;
     });
     if (window.WorkspaceEnvironment)
@@ -95,7 +95,7 @@
     completed = Date.parse(data.completed_at);
     renderStatus(view);
     renderSections(view);
-    node('message').textContent = data.message || '';
+    if (node('message')) node('message').textContent = data.message || '';
     node('source-update-message').textContent = data.source_update_message || '';
     node('progress').replaceChildren(...view.steps.map(renderStep));
     renderActions(view.actions);
@@ -109,25 +109,69 @@
     root.querySelectorAll('[data-section]').forEach((element) => {
       element.hidden = !sections[element.dataset.section];
     });
-    const controls = node('controls');
-    if (controls) {
-      controls.hidden = !sections.actions && !sections.environment;
-      const title = node('actions-settings-title');
-      if (title && view.controls_title) title.textContent = view.controls_title;
-    }
-    const hint = node('hint');
-    if (hint) {
-      hint.textContent = view.hint || '';
-      hint.hidden = !view.hint;
-    }
-    node('message').hidden = view.state === 'idle';
+    renderLead(view);
+    applyDisclosureState(view);
     if (window.WorkspaceEnvironment)
       window.WorkspaceEnvironment.setSubmitLabel(view.environment_submit);
   }
 
+  function renderLead(view) {
+    node('status').textContent = view.headline || view.title;
+    node('summary').textContent = view.summary || '';
+    const subtitle = node('subtitle');
+    const activity = node('activity');
+    if (subtitle) {
+      const text = view.subtitle || '';
+      subtitle.hidden = !text;
+      // The text has its own element, so it can be set whether or not the server rendered any.
+      const target = node('subtitle-text');
+      if (target) target.textContent = text;
+    }
+    if (activity) activity.hidden = !view.busy;
+    const title = node('environment-title');
+    if (title && view.environment_title) title.textContent = view.environment_title;
+    renderLeadAction(view.lead_action);
+  }
+
+  // The lead action is a lifecycle post (start/retry) or, when ready, the preview link
+  // rendered separately as #preview. Rebuild only when it actually changes.
+  let leadSignature = null;
+  function renderLeadAction(action) {
+    const holder = node('lead-action');
+    if (!holder) return;
+    const signature = JSON.stringify(action || null);
+    if (signature === leadSignature) return;
+    leadSignature = signature;
+    holder.replaceChildren();
+    if (!action || action.kind !== 'post' || !allowedActions.includes(action.key)) return;
+    const form = document.createElement('form');
+    form.method = 'post';
+    form.action = base + '/' + action.key;
+    const button = document.createElement('button');
+    button.className = 'button button--primary button--large';
+    button.textContent = action.label;
+    form.append(button);
+    holder.append(form);
+    toggleBusyState(busy);
+  }
+
+  // A disclosure opens by itself when its state says so (a failure must never be hidden,
+  // a fresh workspace needs its settings), but we never close one the user opened, and
+  // we only apply the state's preference when the state changes, not on every poll.
+  let lastDisclosureState = root.dataset.disclosureState || null;
+  function applyDisclosureState(view) {
+    if (view.state === lastDisclosureState) return;
+    lastDisclosureState = view.state;
+    const open = view.open || {};
+    [['environment-disclosure', open.environment], ['technical-disclosure', open.technical]].forEach(
+      ([id, shouldOpen]) => {
+        const element = node(id);
+        if (element) element.open = !!shouldOpen;
+      }
+    );
+  }
+
   function renderStatus(view) {
-    node('status').textContent = view.title;
-    node('activity').hidden = !view.busy;
     node('preview').hidden = !view.ready;
     node('error').textContent = view.error || '';
     node('error-panel').hidden = !view.error;

data/lib/workspaces/dashboard/styles.css

@@ -148,7 +148,64 @@ h1 {
 .log-panel,
 .danger-zone { gap: var(--space-3); }
 
-details.status-panel[open] > summary { margin-block-end: var(--space-4); }
+
+/* Lead: a friendly headline, one sentence, and at most one big button. */
+.lead { gap: var(--space-4); padding-block: var(--space-8); }
+.lead__text { display: grid; gap: var(--space-2); }
+.lead h2 { font-size: clamp(1.4rem, 2vw + 1rem, 1.9rem); line-height: 1.2; }
+.lead__summary { max-inline-size: 38rem; color: var(--muted); font-size: 1.05rem; line-height: 1.5; }
+.lead__actions { display: flex; flex-wrap: wrap; gap: var(--space-3); }
+.lead__action:empty { display: none; }
+.button--large { min-block-size: 52px; padding-inline: var(--space-8); font-size: 16px; border-radius: var(--radius); }
+
+/* Disclosures: quiet by default, a clear label and a one-line hint of what is inside. */
+/* A disclosure has to read as a control. The native marker is lost once a summary is a flex
+   container, so draw our own chevron; the whole header is the click target, with a hover
+   fill and a keyboard focus ring. */
+/* Two classes so the narrow-screen panel padding below cannot re-add padding around the summary. */
+.status-panel.disclosure { padding: 0; }
+.disclosure > summary {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: var(--space-1) var(--space-3);
+  padding: var(--space-4) calc(var(--space-6) + var(--space-8)) var(--space-4) var(--panel-padding);
+  position: relative;
+  list-style: none;
+  color: var(--text);
+  font-weight: 600;
+  border-radius: var(--radius);
+  cursor: pointer;
+  user-select: none;
+  transition: background-color 120ms ease;
+}
+.disclosure > summary::-webkit-details-marker { display: none; }
+.disclosure > summary::after {
+  content: '';
+  position: absolute;
+  inset-inline-end: var(--panel-padding);
+  inset-block-start: 50%;
+  inline-size: 8px;
+  block-size: 8px;
+  margin-block-start: -6px;
+  border-inline-end: 2px solid var(--muted);
+  border-block-end: 2px solid var(--muted);
+  transform: rotate(45deg);
+  transition: transform 160ms ease, border-color 120ms ease;
+}
+.disclosure[open] > summary::after { margin-block-start: -2px; transform: rotate(225deg); }
+.disclosure > summary:hover { background: color-mix(in oklab, var(--accent) 8%, transparent); }
+.disclosure > summary:hover::after { border-color: var(--text); }
+.disclosure > summary:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }
+.disclosure[open] > summary { border-end-start-radius: 0; border-end-end-radius: 0; border-block-end: 1px solid var(--border); margin-block-end: 0; }
+.disclosure > :not(summary) { margin: var(--panel-padding); }
+.disclosure__hint { color: var(--muted); font-size: 13px; font-weight: 400; }
+@media (prefers-reduced-motion: reduce) { .disclosure > summary, .disclosure > summary::after { transition: none; } }
+.disclosure .technical > section:not(.danger-zone) { padding: 0; border: 0; box-shadow: none; background: none; }
+.disclosure .danger-zone { display: grid; gap: var(--space-3); padding: var(--space-4); border: 1px solid var(--danger); border-radius: var(--radius); }
+.disclosure .log-panel { padding: 0; }
+.disclosure .danger-zone h3 { color: var(--danger); font-size: 1rem; }
+.disclosure h3 { font-size: 1rem; }
 
 .status-row {
   display: grid;

data/lib/workspaces/dashboard/template.html.erb

@@ -1,37 +1,27 @@
-<main class="dashboard" id="workspace" data-id="<%= @id %>" data-status="<%= field('status') %>" data-started="<%= field('prepare_started_at') %>" data-completed="<%= field('completed_at') %>" data-busy="<%= @presentation['busy'] %>">
+<main class="dashboard" id="workspace" data-id="<%= @id %>" data-status="<%= field('status') %>" data-started="<%= field('prepare_started_at') %>" data-completed="<%= field('completed_at') %>" data-busy="<%= @presentation['busy'] %>" data-disclosure-state="<%= escape(@presentation['state']) %>">
   <header class="dashboard__header">
-    <div class="dashboard__title"><p class="eyebrow">Managed workspace</p><h1><%= @id %></h1><p class="muted"><%= field('branch') %></p></div>
+    <div class="dashboard__title"><p class="eyebrow">Managed workspace</p><h1><%= @id %></h1></div>
     <a class="button button--subtle" href="/workspaces">All workspaces</a>
   </header>
-  <section class="status-panel" aria-labelledby="status">
-    <div class="status-row">
-      <h2 id="status" role="status"><%= escape(@presentation['title']) %></h2>
-      <span id="activity" <%= 'hidden' unless @presentation['busy'] %>><span class="activity-dot" aria-hidden="true"></span> In progress · <span id="elapsed">—</span></span>
+  <section class="status-panel lead" id="lead" data-section="lead" aria-labelledby="status" <%= 'hidden' unless section?('lead') %>>
+    <div class="lead__text">
+      <h2 id="status" role="status"><%= escape(@presentation['headline']) %></h2>
+      <p id="summary" class="lead__summary"><%= escape(@presentation['summary']) %></p>
+      <p id="subtitle" class="muted" <%= 'hidden' unless @presentation['subtitle'] %>><span id="subtitle-text"><%= escape(@presentation['subtitle']) %></span><span id="activity" <%= 'hidden' unless @presentation['busy'] %>> · <span class="activity-dot" aria-hidden="true"></span> <span id="elapsed">—</span></span></p>
     </div>
-    <p id="hint" <%= 'hidden' unless @presentation['hint'] %>><%= escape(@presentation['hint']) %></p>
-    <p id="message" <%= 'hidden' if @presentation['state'] == 'idle' %>><%= field('message') %></p>
-    <ol class="stepper" id="progress" data-section="progress" aria-label="Setup progress" <%= 'hidden' unless section?('progress') %>>
-      <% @presentation['steps'].each do |step| %>
-        <li class="step" data-step-state="<%= step['state'] %>" <%= 'aria-current="step"' if step['state'] == 'active' %>><span class="step-bullet" aria-hidden="true"></span><span><%= escape(step['label']) %></span><span class="step-outcome"><%= escape(step_outcome(step)) %></span></li>
-      <% end %>
-    </ol>
+    <div class="lead__actions">
+      <a id="preview" class="button button--primary button--large" href="<%= escape(Config.preview_url(@id)) %>" <%= 'hidden' unless @presentation['ready'] %> target="_blank" rel="noopener noreferrer">Open workspace</a>
+      <div id="lead-action" class="lead__action"><%= lead_action_form(@presentation['lead_action']) %></div>
+    </div>
+    <p id="message" class="muted" hidden><%= field('message') %></p>
     <section class="error-panel setup-error" id="error-panel" role="alert" <%= 'hidden' unless @presentation['error'] %>>
       <h3>What went wrong</h3><pre id="error"><%= escape(@presentation['error']) %></pre>
     </section>
     <p id="connection" role="status"></p>
   </section>
-  <section class="status-panel controls-panel" id="controls" data-section-group aria-labelledby="actions-settings-title" <%= 'hidden' unless section?('actions') || section?('environment') %>>
-    <h2 id="actions-settings-title"><%= escape(@presentation['controls_title']) %></h2>
-    <div class="workspace-actions-group" data-section="actions" aria-labelledby="actions-heading" <%= 'hidden' unless section?('actions') %>>
-      <h3 id="actions-heading">Workspace actions</h3>
-      <div class="workspace-actions">
-        <a id="preview" class="button button--primary" href="<%= escape(Config.preview_url(@id)) %>" <%= 'hidden' unless @presentation['ready'] %> target="_blank" rel="noopener noreferrer">Open workspace</a>
-        <div id="actions" class="workspace-actions"><% @presentation['actions'].each do |action| %><%= action_form(action) %><% end %></div>
-      </div>
-      <p id="source-update-message" role="status"><%= field('source_update_message') %></p>
-    </div>
-    <div class="workspace-settings" data-section="environment" aria-labelledby="environment-overrides" <%= 'hidden' unless section?('environment') %>>
-      <h3 id="environment-overrides">Environment</h3>
+  <details class="status-panel disclosure" id="environment-disclosure" data-section="environment" <%= 'open' if @presentation.dig('open', 'environment') %> <%= 'hidden' unless section?('environment') %>>
+    <summary><span id="environment-title"><%= escape(@presentation['environment_title']) %></span><span class="disclosure__hint">Presets and environment variables</span></summary>
+    <div class="workspace-settings" aria-labelledby="environment-title">
       <form method="post" action="/workspaces/<%= @id %>/environment" id="environment-form" class="stack" data-environment-form data-environment-presets="<%= escape(environment_presets_json) %>">
         <fieldset class="env-fieldset" data-environment-fieldset <%= 'disabled' if @presentation['busy'] %>>
           <legend class="env-legend">Workspace settings</legend>
@@ -57,25 +47,45 @@
         <p class="muted" id="environment-status" role="status" aria-live="polite"></p>
       </form>
     </div>
-  </section>
-  <section class="log-panel" data-section="log" aria-labelledby="log-title" <%= 'hidden' unless section?('log') %>>
-    <div class="log-header"><h2 id="log-title">Live <%= field('log_source') == 'backend' ? 'backend' : 'setup' %> log</h2><time id="updated"><%= field('updated_at') %></time></div>
-    <nav class="log-switch" aria-label="Log source">
-      <a href="?log=setup" data-log-source="setup" <%= 'aria-current="page"' if @snapshot['log_source'] != 'backend' %>>Setup log</a>
-      <a href="?log=backend" data-log-source="backend" <%= 'aria-current="page"' if @snapshot['log_source'] == 'backend' %>>Backend log</a>
-    </nav>
-    <pre id="log" tabindex="0" aria-label="<%= field('log_source') == 'backend' ? 'Backend' : 'Setup' %> log"><%= field('log_tail') %></pre>
-  </section>
-  <details class="status-panel" data-section="details" <%= 'hidden' unless section?('details') %>><summary>Workspace details</summary><dl><dt>Preview URL</dt><dd><a class="detail-link" href="<%= escape(Config.preview_url(@id)) %>" target="_blank" rel="noopener noreferrer"><%= escape(Config.preview_url(@id)) %></a> <span class="muted">Available when ready</span></dd><dt>Branch</dt><dd><%= field('branch') %></dd><dt>Path</dt><dd><code><%= field('path') %></code></dd><dt>Related PR</dt><dd><%= escape(@snapshot.dig('related_pr', 'number') || 'None') %></dd><dt>Created</dt><dd><%= escape(@snapshot['created_at'] || 'Unavailable') %></dd><dt>Last startup</dt><dd><%= escape(@snapshot['started_at'] || 'Never') %></dd></dl></details>
-  <section class="status-panel danger-zone" data-section="danger" aria-labelledby="danger-heading" <%= 'hidden' unless section?('danger') %>>
-    <h2 id="danger-heading">Danger Zone</h2>
-    <p>Deleting this workspace stops its server and removes its worktree. <strong>Discard uncommitted and untracked changes</strong> permanently. The branch and committed work are preserved.</p>
-    <form method="post" action="/workspaces/<%= @id %>/remove" id="remove-form">
-      <label for="confirm-id">Type <code><%= @id %></code> to confirm deletion</label>
-      <input id="confirm-id" name="confirm_id" required autocomplete="off" spellcheck="false" aria-describedby="remove-warning" <%= 'disabled' if @presentation['busy'] %>>
-      <p class="muted" id="remove-warning">This cannot restore uncommitted or untracked files.</p>
-      <button class="button button--danger" <%= 'disabled' if @presentation['busy'] %>>Delete workspace</button>
-    </form>
-  </section>
+  </details>
+  <details class="status-panel disclosure" id="technical-disclosure" data-section="technical" <%= 'open' if @presentation.dig('open', 'technical') %> <%= 'hidden' unless section?('technical') %>>
+    <summary><span>Technical details</span><span class="disclosure__hint">Setup steps, logs and workspace controls</span></summary>
+    <div class="technical stack stack--loose">
+      <ol class="stepper" id="progress" data-section="progress" aria-label="Setup progress" <%= 'hidden' unless section?('progress') %>>
+        <% @presentation['steps'].each do |step| %>
+          <li class="step" data-step-state="<%= step['state'] %>" <%= 'aria-current="step"' if step['state'] == 'active' %>><span class="step-bullet" aria-hidden="true"></span><span><%= escape(step['label']) %></span><span class="step-outcome"><%= escape(step_outcome(step)) %></span></li>
+        <% end %>
+      </ol>
+      <div class="workspace-actions-group stack stack--snug" data-section="actions" aria-labelledby="actions-heading" <%= 'hidden' unless section?('actions') %>>
+        <h3 id="actions-heading">Workspace controls</h3>
+        <div class="workspace-actions">
+          <div id="actions" class="workspace-actions"><% @presentation['actions'].each do |action| %><%= action_form(action) %><% end %></div>
+        </div>
+        <p id="source-update-message" role="status"><%= field('source_update_message') %></p>
+      </div>
+      <section class="log-panel" data-section="log" aria-labelledby="log-title" <%= 'hidden' unless section?('log') %>>
+        <div class="log-header"><h3 id="log-title">Live <%= field('log_source') == 'backend' ? 'backend' : 'setup' %> log</h3><time id="updated"><%= field('updated_at') %></time></div>
+        <nav class="log-switch" aria-label="Log source">
+          <a href="?log=setup" data-log-source="setup" <%= 'aria-current="page"' if @snapshot['log_source'] != 'backend' %>>Setup log</a>
+          <a href="?log=backend" data-log-source="backend" <%= 'aria-current="page"' if @snapshot['log_source'] == 'backend' %>>Backend log</a>
+        </nav>
+        <pre id="log" tabindex="0" aria-label="<%= field('log_source') == 'backend' ? 'Backend' : 'Setup' %> log"><%= field('log_tail') %></pre>
+      </section>
+      <section class="stack stack--snug" data-section="details" <%= 'hidden' unless section?('details') %>>
+        <h3>Workspace details</h3>
+        <dl><dt>Preview URL</dt><dd><a class="detail-link" href="<%= escape(Config.preview_url(@id)) %>" target="_blank" rel="noopener noreferrer"><%= escape(Config.preview_url(@id)) %></a> <span class="muted">Available when ready</span></dd><dt>Branch</dt><dd><%= field('branch') %></dd><dt>Path</dt><dd><code><%= field('path') %></code></dd><dt>Related PR</dt><dd><%= escape(@snapshot.dig('related_pr', 'number') || 'None') %></dd><dt>Created</dt><dd><%= escape(@snapshot['created_at'] || 'Unavailable') %></dd><dt>Last startup</dt><dd><%= escape(@snapshot['started_at'] || 'Never') %></dd></dl>
+      </section>
+      <section class="danger-zone" data-section="danger" aria-labelledby="danger-heading" <%= 'hidden' unless section?('danger') %>>
+        <h3 id="danger-heading">Danger Zone</h3>
+        <p>Deleting this workspace stops its server and removes its worktree. <strong>Discard uncommitted and untracked changes</strong> permanently. The branch and committed work are preserved.</p>
+        <form method="post" action="/workspaces/<%= @id %>/remove" id="remove-form">
+          <label for="confirm-id">Type <code><%= @id %></code> to confirm deletion</label>
+          <input id="confirm-id" name="confirm_id" required autocomplete="off" spellcheck="false" aria-describedby="remove-warning" <%= 'disabled' if @presentation['busy'] %>>
+          <p class="muted" id="remove-warning">This cannot restore uncommitted or untracked files.</p>
+          <button class="button button--danger" <%= 'disabled' if @presentation['busy'] %>>Delete workspace</button>
+        </form>
+      </section>
+    </div>
+  </details>
   <noscript><a href="/workspaces/<%= @id %>">Refresh status</a></noscript>
 </main>

data/lib/workspaces/dashboard_view.rb

@@ -161,6 +161,15 @@ module Workspaces
       JSON.generate(environment_presets)
     end
 
+    # The lead's primary action. `open` is rendered separately as a link (it needs the
+    # preview URL and must stay a real anchor), so only lifecycle posts produce a form.
+    def lead_action_form(action)
+      return '' unless action && action['kind'] == 'post'
+
+      "<form method=\"post\" action=\"/workspaces/#{@id}/#{action.fetch('key')}\">" \
+        "<button class=\"button button--primary button--large\">#{escape(action.fetch('label'))}</button></form>"
+    end
+
     def action_form(action)
       style = action['primary'] ? 'button--primary' : 'button--subtle'
       "<form method=\"post\" action=\"/workspaces/#{@id}/#{action.fetch('key')}\">" \

data/lib/workspaces/front_door.rb

@@ -5,15 +5,22 @@ require 'net/http'
 require_relative 'coordinator'
 require_relative 'dashboard_view'
 require_relative 'environment_overrides'
+require_relative 'proxy_middleware'
 
 module Workspaces
   class FrontDoor
     WORKSPACE_ROUTE = %r{\A/workspaces/([a-z0-9]+(?:-[a-z0-9]+)*)
                           (?:/(status|start|prepare|restart|stop|remove|update-pr|environment))?\z}x
 
+    # Rack env keys set on requests that reach a ready workspace backend, for use by
+    # middleware registered with Workspaces.configure_proxy.
+    WORKSPACE_ID_ENV = 'workspaces.workspace_id'.freeze
+    WORKSPACE_ENV = 'workspaces.workspace'.freeze
+
     def initialize(coordinator: Coordinator.new, registry: Registry.new)
       @coordinator = coordinator
       @registry = registry
+      @forwarder = ProxyMiddleware.build(method(:forward_to_backend))
     end
 
     def call(env)
@@ -230,7 +237,9 @@ module Workspaces
       snapshot = @coordinator.snapshot(id, include_log: false)
       return unavailable(id, request) unless snapshot['status'] == 'ready' && !snapshot['active']
 
-      forward(id, request)
+      request.env[WORKSPACE_ID_ENV] = id
+      request.env[WORKSPACE_ENV] = snapshot
+      @forwarder.call(request.env)
     rescue IOError, SystemCallError, Timeout::Error => e
       response(502, "Workspace backend unavailable: #{e.class}")
     end
@@ -241,6 +250,11 @@ module Workspaces
       response(503, "Workspace not ready. Visit #{Config.dashboard_url(id)}")
     end
 
+    # Innermost app of the proxy stack: sends the request to the workspace backend.
+    def forward_to_backend(env)
+      forward(env.fetch(WORKSPACE_ID_ENV), Rack::Request.new(env))
+    end
+
     def forward(id, request)
       uri = URI("http://127.0.0.1:#{Backend.new(id).port}#{request.fullpath}")
       upstream = upstream_request(id, request, uri)

data/lib/workspaces/presentation.rb

@@ -6,8 +6,13 @@ module Workspaces
     ACTIONS = { 'start' => 'Start workspace', 'prepare' => 'Rebuild & restart',
                 'restart' => 'Restart server', 'stop' => 'Stop server' }.freeze
 
-    SECTIONS = %w(progress actions environment log details danger).freeze
-    MANAGEABLE = SECTIONS
+    # Three layers, from friendly to technical. `lead` is the headline, one sentence and at
+    # most one primary action. `environment` (presets and variables) is the area for
+    # deliberately changing something. `technical` is one disclosure holding setup steps,
+    # logs, workspace details, lifecycle controls and deletion; it is never the first thing
+    # a user reads, but it opens by itself when something needs attention.
+    SECTIONS = %w(lead progress actions environment technical log details danger).freeze
+    TECHNICAL = %w(technical progress actions log details danger).freeze
 
     # Workspace lifecycle state machine. Each state declares only what is usable and
     # meaningful there; everything else is hidden rather than shown disabled.
@@ -20,19 +25,60 @@ module Workspaces
     #
     # `environment_submit` labels the single environment-form button, which saves the
     # settings and (re)starts the workspace, so a brand new workspace needs only that.
+    #
+    # Per state: `headline` and `summary` are plain language; `open_environment` and
+    # `open_technical` say which disclosures start expanded. A failure always opens the
+    # technical section so the cause is visible without hunting for it.
     STATES = {
       'idle' => {
-        sections: %w(environment),
-        environment_submit: 'Start workspace', controls_title: 'Set up your workspace',
-        hint: 'Choose the environment you want to preview below, then start the workspace. ' \
-              'Setup usually takes a few minutes.'
+        sections: %w(lead environment),
+        headline: "Let's get your workspace running",
+        summary: 'Pick the version of the site you want to preview, then start. Setup usually takes a few minutes.',
+        environment_submit: 'Start workspace', environment_title: 'Choose what to preview',
+        open_environment: true, open_technical: false
+      },
+      'busy' => {
+        sections: %w(lead technical progress log),
+        headline: 'Setting things up…',
+        summary: "This usually takes a few minutes. We'll take you to the preview when it's ready.",
+        environment_submit: 'Save & restart', environment_title: 'Change settings',
+        open_environment: false, open_technical: true
+      },
+      'ready' => {
+        sections: %w(lead environment) + TECHNICAL,
+        headline: 'Your workspace is ready',
+        summary: 'Everything is set up and running. Open it to see your changes.',
+        environment_submit: 'Save & restart', environment_title: 'Change settings',
+        open_environment: false, open_technical: false
+      },
+      'stopped' => {
+        sections: %w(lead environment) + TECHNICAL,
+        headline: 'Your workspace is paused',
+        summary: 'Start it again to pick up where you left off.',
+        environment_submit: 'Save & start', environment_title: 'Change settings',
+        open_environment: false, open_technical: false
+      },
+      'error' => {
+        sections: %w(lead environment) + TECHNICAL,
+        headline: "Something didn't go to plan",
+        summary: 'Setup stopped before it finished. You can try again, or change settings first.',
+        environment_submit: 'Save & retry', environment_title: 'Change settings',
+        open_environment: false, open_technical: true
+      },
+      'interrupted' => {
+        sections: %w(lead environment) + TECHNICAL,
+        headline: 'Setup was interrupted',
+        summary: 'It stopped before it finished. Try again to pick up from the start.',
+        environment_submit: 'Save & retry', environment_title: 'Change settings',
+        open_environment: false, open_technical: true
       },
-      'busy' => { sections: %w(progress log), environment_submit: 'Save & restart' },
-      'ready' => { sections: MANAGEABLE, environment_submit: 'Save & restart' },
-      'stopped' => { sections: %w(actions environment log details danger), environment_submit: 'Save & start' },
-      'error' => { sections: MANAGEABLE, environment_submit: 'Save & retry' },
-      'interrupted' => { sections: MANAGEABLE, environment_submit: 'Save & retry' },
-      'unknown' => { sections: %w(log details), environment_submit: 'Save & restart' }
+      'unknown' => {
+        sections: %w(lead technical log details),
+        headline: 'Workspace status unknown',
+        summary: 'Open the technical details to see what the workspace is doing.',
+        environment_submit: 'Save & restart', environment_title: 'Change settings',
+        open_environment: false, open_technical: true
+      }
     }.freeze
 
     def initialize(snapshot)
@@ -42,9 +88,12 @@ module Workspaces
     def to_h
       { 'title' => title, 'busy' => busy?, 'error' => error, 'steps' => steps,
         'actions' => actions, 'ready' => status == 'ready' && !busy?,
-        'state' => state, 'sections' => sections, 'hint' => definition[:hint],
-        'controls_title' => definition.fetch(:controls_title, 'Actions & settings'),
-        'environment_submit' => definition[:environment_submit] }
+        'state' => state, 'sections' => sections,
+        'headline' => definition[:headline], 'summary' => definition[:summary],
+        'subtitle' => subtitle, 'lead_action' => lead_action,
+        'environment_title' => definition[:environment_title],
+        'environment_submit' => definition[:environment_submit],
+        'open' => { 'environment' => definition[:open_environment], 'technical' => definition[:open_technical] } }
     end
 
     private
@@ -73,6 +122,23 @@ module Workspaces
       SECTIONS.to_h { |name| [name, visible.include?(name)] }
     end
 
+    # The single most useful thing to do next, or nil when the user should just wait.
+    # `open` links straight to the preview; the others are lifecycle form posts.
+    def lead_action
+      case state
+      when 'ready' then { 'kind' => 'open', 'label' => 'Open workspace' }
+      when 'stopped' then { 'kind' => 'post', 'key' => 'start', 'label' => 'Start workspace' }
+      when 'error', 'interrupted' then retry_action.merge('kind' => 'post')
+      end
+    end
+
+    # What is happening right now, in the quiet line under the headline.
+    def subtitle
+      return nil unless state == 'busy'
+
+      @snapshot['message']
+    end
+
     def title
       return 'Workspace busy' if @snapshot['active'] && !busy_status?
       return @snapshot['message'] || 'Running setup' if status == 'preparing'

data/lib/workspaces/proxy_middleware.rb

@@ -0,0 +1,77 @@
+require 'rack'
+
+module Workspaces
+  # Adds a Rack middleware stack around workspace preview traffic.
+  #
+  # The gem stays unaware of what any middleware does: the process hosting the front
+  # door registers its own, for example from a file named by WORKSPACES_REQUIRE:
+  #
+  #   Workspaces.configure_proxy do
+  #     use MyMiddleware, option: 'value'
+  #   end
+  #
+  # Blocks are replayed in registration order into a Rack::Builder, so the first
+  # `use` is the outermost middleware. The stack wraps only the step that forwards a
+  # request to a ready workspace backend. The dashboard, redirects for workspaces that
+  # are not ready, and error responses never pass through it.
+  module ProxyMiddleware
+    ENV_VAR = 'WORKSPACES_REQUIRE'
+
+    # Raised for unusable configuration; the CLI reports it and exits non-zero.
+    class ConfigurationError < ArgumentError; end
+
+    @blocks = []
+
+    def self.register(&block)
+      raise ConfigurationError, 'Workspaces.configure_proxy requires a block' unless block
+
+      @blocks << block
+      self
+    end
+
+    def self.any?
+      !@blocks.empty?
+    end
+
+    def self.reset!
+      @blocks.clear
+    end
+
+    # Returns the endpoint untouched when nothing is registered, so an unconfigured
+    # front door behaves exactly as it did before this seam existed.
+    def self.build(endpoint)
+      blocks = @blocks.dup
+      return endpoint if blocks.empty?
+
+      Rack::Builder.new do
+        blocks.each { |block| instance_exec(&block) }
+        run endpoint
+      end.to_app
+    end
+
+    # Paths from WORKSPACES_REQUIRE, separated like PATH entries.
+    def self.env_paths
+      ENV.fetch(ENV_VAR, '').split(File::PATH_SEPARATOR).map(&:strip).reject(&:empty?)
+    end
+
+    # Executes the given Ruby files so they can register middleware. These files run
+    # with the privileges of the front door; only name files the operator controls.
+    def self.load_files(paths)
+      paths.each do |path|
+        full_path = File.expand_path(path)
+        raise ConfigurationError, "Proxy middleware file not found: #{path}" unless File.file?(full_path)
+
+        begin
+          require full_path
+        rescue ScriptError, StandardError => e
+          raise ConfigurationError, "Could not load proxy middleware #{path}: #{e.class}: #{e.message}"
+        end
+      end
+      paths
+    end
+  end
+
+  def self.configure_proxy(&block)
+    ProxyMiddleware.register(&block)
+  end
+end

data/lib/workspaces/version.rb

@@ -1,3 +1,3 @@
 module Workspaces
-  VERSION = '0.1.9'
+  VERSION = '0.1.11'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.11
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 2026-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -88,6 +88,7 @@ files:
 - lib/workspaces/paths.rb
 - lib/workspaces/port_allocator.rb
 - lib/workspaces/presentation.rb
+- lib/workspaces/proxy_middleware.rb
 - lib/workspaces/recipe.rb
 - lib/workspaces/registry.rb
 - lib/workspaces/state_store.rb