# Develop Harness Studio with live reload

## Traceability

- Spec ID: studio-development-live-reload
- Status: Implemented

## Intent

Give Studio contributors one repository-owned development command that starts
the real local Studio server and shortens the browser feedback loop. Successful
frontend source rebuilds should refresh the open page automatically, while a
temporary build error should leave the server available and recover after the
source is corrected.

## Acceptance Scenarios

- **AC-1:** Running `npm run harness-studio:dev` from the repository root builds
  the Studio server and browser application, starts the existing loopback local
  workspace launcher with Session discovery, prints its URL, and forwards its
  launcher arguments supplied after `--`.
- **AC-2:** Changing a Studio browser dependency, stylesheet, or HTML entrypoint
  triggers an incremental rebuild and automatically reloads an open Studio page
  only after that rebuild succeeds.
- **AC-3:** A failed browser rebuild reports the error without publishing a new
  reload revision or stopping the Studio server; a later valid edit rebuilds and
  reloads normally.
- **AC-4:** Production `build`, package contents, and the Studio HTTP/API surface
  remain unchanged; live-reload code exists only in development output.
- **AC-5:** The development watcher and child-process orchestration use Node APIs
  and argv arrays and can run on Windows, macOS, and Linux.

## Non-goals

- React state-preserving HMR or Fast Refresh.
- Automatic recompilation or restart for Studio server source changes.
- Replacing the existing esbuild-wasm production bundle with Vite or another
  development-server dependency.
- Changing artifact-directory live updates or any public Studio endpoint.
- Expanding the packaged generic CLI with repository-local Session providers.

## Plan and Tasks

1. Extract the shared Studio browser/runtime build configuration so production
   and development builds cannot silently diverge.
2. Add a development orchestrator that performs the initial server build,
   incrementally rebuilds browser dependencies and static assets, starts the
   existing CLI with forwarded argv, and cleans up watchers and the child process.
3. Inject a development-only reload poller and revision asset into the copied
   `index.html`; advance the revision only after a successful build.
4. Add root/package scripts, concise contributor documentation, and focused
   behavior tests for injection, revision publication, argument forwarding, and
   recovery semantics.

## Test and Review Evidence

- **AC-1/AC-5:** focused tests for workspace-launcher argv forwarding plus a
  real `npm run harness-studio:dev -- --port 0` process lifecycle smoke; verify
  `/api/config` reports
  `workspaceDiscoveryEnabled: true`.
- **AC-2/AC-3:** focused build-controller tests plus a browser smoke that edits
  and restores a Studio static source, observes the revision advance and page
  reload, then checks browser console and page errors.
- **AC-4:** `npm run harness-studio:build`, package tests, and inspection of the
  production `dist/app/index.html` for absence of the development reload client.
- Review the final staged/local diff with the change-traceability Review
  Readiness Check, including generated-output and staged/unstaged boundaries.
- Main risks: duplicate or missed filesystem events, reload publication after a
  failed build, orphaned server processes, and platform-specific signal or path
  handling.

### Implementation evidence — 2026-08-24

- `npm run harness-studio:dev -- --port 0` started the repository workspace
  launcher with `workspaceDiscoveryEnabled: true`; interrupting it closed the
  loopback server cleanly.
- Browser smoke observed the page title change and return without a manual
  refresh, kept `Choose workspace` enabled, reported no console/page errors, and
  did not show the generic-launcher discovery error.
- An intentional temporary TSX syntax error left `/api/config` available with
  HTTP 200 and kept reload revision 4; restoring the source published revision
  5 and resumed automatic reload.
- `npm run harness-studio:test` passed 42 files and 259 tests. The full
  `npm run harness-studio:test:browser` suite passed 40 tests.
- Production `npm run harness-studio:build` succeeded and its generated
  `dist/app/index.html` contained no development reload client. The focused
  development build tests passed 4 tests, and the doc-link graph passed 8 tests.