A visual workspace for the real DSH WebUI

WebUI Studio is not a mock page builder. It runs against the official DSH WebUI and its real plugin graph, then turns visual inspection and source edits into distributable plugin-owned artifacts.

Studio is an independent downstream application of dsh-harmony. It uses Harmony's public Host extension, runtime, Patch engine, and service APIs together with the generic React registration API from dsh-harmony-react. The dependency direction stays one-way: Studio depends on Harmony; Harmony does not depend on Studio.

What you can do

• Create a minimal DSH Web Client plugin or import an existing local plugin folder
• Give every Draft its own Git worktree, DSH_HOME, profile, dependencies, and child Host
• Preview the official WebUI without loading Draft code into the stable Host
• Browse normally or inspect DOM, React owners, source candidates, and Patch traces
• Edit Draft source with CodeMirror and protect installed dependency sources as read-only
• Build, apply through Harmony, reload, and confirm the live Client graph revision
• Run Draft-scoped DSH Agents with explicit Studio tools
• Check package exports, artifacts, Patch state, ordering, dependencies, and pack output
• Run multiple isolated Draft Preview Hosts at the same time
• Snapshot the current WebUI profile or another local profile into each isolated Draft runtime
• Reorder plugins and enable or disable Harmony Providers through one transactional hot reload

How it works

flowchart LR
  A["Stable DSH Host"] --> B["WebUI Studio"]
  B --> C["Draft worktree"]
  B --> D["Draft worktree"]
  C --> E["Isolated DSH Home + Preview Host"]
  D --> F["Isolated DSH Home + Preview Host"]
  E --> G["Harmony runtime + real WebUI"]
  F --> G

The stable Host owns the Studio interface, Draft registry, and Agent sessions. Each Draft owns an isolated worktree and child Preview Host. A build becomes active only after the Preview confirms the new live Client graph revision. Stopping a Draft terminates its child Host but preserves its files and state.

Studio is served locally at:

http://127.0.0.1:<dsh-port>/studio

Its managed data lives under $DSH_HOME/studio/:

studio/
├── workspace.json
├── drafts/<draft-id>.json
├── repositories/<draft-id>/
├── worktrees/<draft-id>/
└── runtimes/<draft-id>/dsh-home/profiles/web/

Creating a new plugin initializes and commits a minimal DSH Web Client package. New plugins stay inside Studio by default. Creation can optionally record an absolute destination for a new or empty local folder; Studio does not create or modify that folder until Save plugin to folder is used from the instance panel. Later saves synchronize the Studio-owned project snapshot while leaving destination-only files such as node_modules untouched. Importing an existing plugin accepts an absolute local folder after validating its Web Client manifest, then copies an isolated snapshot without .git or node_modules into a Studio-owned Git repository. Symbolic links are rejected, and the original folder is never modified.

Each Draft can start from the stable Host's current web profile or from another local DSH profile selected by absolute folder path. Studio copies that profile's manifest and configuration into the isolated runtime and resolves relative link: dependencies against the selected source folder. The source profile remains untouched.

Draft display names are independent from npm package identities and can be renamed in the instance panel. Studio persists the ordered open tabs and active Draft in workspace.json; closing a tab only removes it from the current workspace and never stops or deletes the Draft. Unsaved Source changes must be saved with Ctrl+S or Command+S before switching or closing tabs.

Getting started

[!IMPORTANT] Studio requires the public Harmony extension and service APIs documented in docs/harmony-api-requirements.md. dsh-harmony@0.3.2 is the minimum compatible release.

dsh plugin --profile web add dsh-webui-studio --allow-build=dsh-harmony
dsh web

Harmony is resolved transitively and does not need to be installed as a second plugin. The build permission allows its global-only DSH shim installer; normal profile installs do not modify the global command.

To develop Studio itself from source:

git clone https://github.com/CH4ACKO3/dsh-webui-studio.git
cd dsh-webui-studio
npm install
npm run check

dsh plugin --profile web add link:$(pwd)
dsh web

To exercise the same single-package installation path as a release artifact:

studio_tarball="$(npm pack --silent --ignore-scripts)"
dsh plugin --profile web add "file:$(pwd)/${studio_tarball}" \
  --allow-build=dsh-harmony

Open the Studio URL printed by the local dsh web process, create or import a Draft, and start its Preview Host.

A Draft package must:

• declare dsh.client.platform: "web";
• export ., ./client, and ./package.json;
• define a non-empty scripts.build command.

Development

Command	Purpose
npm run typecheck	Check the Host, browser app, and Preview bridge
npm test	Run the unit and component test suite
npm run build	Build the Host, Studio UI, and Preview bridge
npm run check	Run typecheck, tests, build, and packed fresh-install integration
npm run test:integration	Pack and install the tarball in a fresh DSH home, then exercise Host, Draft, Preview, build, activation, and shutdown end to end

The integration test requires a Harmony build that exposes the APIs described in the compatibility note above.

Design boundaries

• The official WebUI keeps its own-origin /api and WebSockets; Studio does not proxy them.
• The Preview bridge requires the exact parent origin and a per-start capability.
• Preview DOM, React, source, Patch, and comment data is treated as untrusted evidence.
• Source writes stay inside the selected Draft package and never follow symbolic links outside it.
• Registered element boundaries and Patch traces are candidate evidence, not claims of exact DOM ownership.

Frequently asked questions

How is Studio different from other WYSIWYG tools?

DSH WebUI changes are delivered through plugins rather than direct edits to the upstream source. Its interface elements also participate in Cordis plugin lifecycle and control logic, so the problem extends beyond manipulating static DOM and CSS. Those constraints call for a dedicated toolkit that understands the DSH plugin system from preview through distribution.

Why not simply ask an Agent to edit the source?

Studio still connects to the real Agent inside DSH. It gives that Agent richer project context, integrated previews, purpose-built tools and skills, and a tighter edit-build-inspect-validate loop. Studio does not replace the Agent; it turns source editing into a more capable interactive workflow for both the Agent and the developer.

What is Harmony, and why use it?

The DSH WebUI exposes many useful slots, but Studio aims for deeper and more flexible changes—including UI and behavior introduced by other plugins—while keeping independently authored modifications as compatible as possible. dsh-harmony provides the runtime patching and extension model that makes this possible.

Related projects

• dsh-harmony - runtime patching, Host extension mounting, plugin reloads, and Patch inspection
• dsh-harmony-react - React-aware Patch factories and Studio element/variable registration

License

Distributed under the MIT License.