main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-project-workspaces description: >- Hydrogen's Project workspaces menu (icon right of the Adom logo) and its API: apply or unload the bench layout a project ships in hydrogen/workspace.json. Use when asked about project workspaces, apply a bench, workspace.json, or the workspace offer card.

hydrogen-project-workspaces: the desktop side of shared workspaces

A project can ship its Hydrogen layout as hydrogen/workspace.json (or hydrogen/workspaces/<name>.json) in its page repo. The platform pieces are shared with Hydrogen Cloud and documented in the wiki-workspaces skill (file, hints, adom-cli hydrogen workspace export|apply|teardown) and adom-workspace-control (the pane routes). Hydrogen (ah) adds a menu, a one-time offer, placeholder tabs that know the bridge state, and a control API for all of it. Use the API; never click for the user.

The menu

Right of the Adom logo. Benches grouped by project, labelled "project / name", from the checkout (~/project root and one clone folder down) plus the cloud mirror (mirror, and legacy when keyed by repo instead of project). Rows have Apply, Unload and a copy-the-command button; below: "Replace existing tabs on Apply" and "Save as project workspace". Apply/Unload/Save run adom-cli in the workspace with the output in a launch console tab (closes itself on success, stays with the reason on failure).

Control API (ah, port 47084 by default; GET /ports for the real one)

The live control URL is in ~/.adom/hydrogen-control-url.

Route Body Notes
GET /workspaces/benches benches[] with identity, project, name, path, dir, source, legacy, tabs, panels, requires, applied, apply_command, unload_sources.
POST /workspaces/refresh rescan checkout + mirror
POST /workspaces/apply `{identity project
POST /workspaces/unload same selectors tries identity, then the relative and absolute path adom-cli may have recorded
POST /workspaces/save {dir, out?, project?} adom-cli hydrogen workspace export --out <out> in dir; project when the folder has no page.json
POST /workspaces/offer `{action: "apply" "dismiss"}`
POST /workspaces/menu {open: bool} UI-bus: project-workspaces.open / .close
POST /workspaces/demo the "Show me how it works" walkthrough (ab demo panel pw-tour, captions, narration); returns at once
GET /workspaces/status running, walkthrough, last (with transcript), offer, applied this session
POST /ab/verb {command, args?, timeoutMs?} any Adom Bridge verb on this machine (ab's own gates still apply)

A name given to apply/unload resolves to the applied bench first, then a checkout bench, then a mirror copy (a legacy mirror entry can share a name with a checkout bench).

On Linux, the walkthrough and /ab/verb work while Adom Bridge runs on this computer (Hydrogen installs it when a Linux build is published for the user's account; GET /ab/health tells you). Apply, unload, save and the menu do not need it.

Rules the desktop follows

  • A checkout bench is applied as the local file from its project folder (what the user is editing); a mirror-only entry with a project uses the wiki ref. Identity is project#hydrogen/... (path inside the project), the key adom-cli and the cloud use.
  • The project for a files-only wiki clone comes from the wiki (page.json has the slug, not the owner).
  • The offer card appears only for a project that shows up in the checkouts after Hydrogen's first scan on that machine (a new clone). One card per app start at most, preference key workspace.offered.<owner>.<repo>; Apply, Not now and the one-minute timeout are remembered. Never auto-apply.
  • Placeholder tabs ("X (not available)" / "(not started)", or panelState.placeholder) carry a card saying what happened, with Re-apply; the Adom Bridge state and a Connect button appear only when the app is a desktop bridge. For about a minute after apply Hydrogen reads the app's newest ~/.adom/launch-logs/<owner>-<slug>-*.log for its last http://127.0.0.1:<port>/ line, probes it inside the workspace, and re-points the tab in place.
  • The workspace API on the proxy (47083) serves the cloud's granular routes plus GET /api/panels/catalog, POST .../current/apply (replace mode, keeps the VS Code leaf), and forwards .../shared[/...] to Hydrogen Cloud with the desktop session. Every tree mutation bumps a revision; a PUT /current whose _rev is behind gets 409, so an external apply cannot be erased by the browser's echo.
  • POST /splits seeds the new pane with the placeholder tab adom-cli sends (panelType, displayName, position, ratio); adom-cli deletes it as tabIndex 0 after adding the bench's tabs.
  • No 3D panel on the desktop: a 3d-viewer tab renders as "not available on Hydrogen Desktop" (the UI's own wording).
  • hydrogen://edit?workspace=<ref|identity|path> is registered for this user at every start; a second launch focuses the running Hydrogen, which applies the bench once the list loads. Test with xdg-open "hydrogen://edit?workspace=john/example-bench" on the host.
  • The VS Code pane is never created, removed or replaced by any of this.

Testing a change (the ralph loop)

CTL=$(cat ~/.adom/hydrogen-control-url)
cd ~/project && adom-wiki repo clone john/example-bench
curl -s -X POST $CTL/workspaces/refresh | jq '.benches[].identity'
curl -s -X POST $CTL/workspaces/apply -H 'content-type: application/json' -d '{"identity":"john/example-bench#hydrogen/workspace.json"}' | jq '{ok,summary}'
curl -s $CTL/workspace/tabs | jq '[.tabs[].name]'
curl -s -X POST $CTL/workspaces/unload -H 'content-type: application/json' -d '{"identity":"john/example-bench#hydrogen/workspace.json"}' | jq '{ok,summary}'

Symptoms: "no recorded apply" from the CLI means the source spelling differs from what apply recorded (the unload route already tries identity, relative and absolute path); an empty mirror in the menu with entries visible to curl means the forward stripped gzip (fixed 1.0.371, the proxy asks for identity encoding); a tab created by apply vanishing within a second means a stale browser write got through (the revision check refuses it since 1.0.364).