---
name: openhost-frontend-preview
description: |
  Live, hot-reloading preview of the Sculptor WEB frontend from a phone or any
  browser, served through the OpenHost nginx /proxy front. ONLY relevant when
  running INSIDE the openhost-deployed Sculptor (the container fronted by nginx on
  :5050, reachable at https://sculptor.<zone>/) — NOT for local or Electron dev.
  Frontend-only: it reuses the single shared backend, so it previews UI/frontend
  changes, not a per-workspace backend. Invoke when iterating on the web UI and
  wanting to see it live in a browser through the OpenHost SSO front.
user-invocable: true
---

# OpenHost frontend live preview (`/proxy/<port>/`)

Run a Vite dev server (HMR) for the Sculptor web UI and reach it from any
logged-in browser — including a phone — through the OpenHost nginx front, entirely
behind OpenHost's owner SSO. Nothing is exposed publicly.

## When this applies — OpenHost only

Use this ONLY inside the openhost-deployed Sculptor. Quick checks:
- `test -f /app/openhost-nginx.conf` (the nginx front config), and
- PID 1 is nginx: `ps -p 1 -o args=` -> `nginx ...` (backend is on loopback :5051).

If those are NOT true (local dev, Electron, a plain backend on :5050), this skill
does not apply — use normal `pnpm run dev` / `just frontend` there instead.

## How it works (read first)

- nginx owns :5050 (the only port OpenHost proxies) and routes `/proxy/<port>/*`
  -> `127.0.0.1:<port>`; everything else -> the backend on :5051.
- A preview is just a **Vite dev server** on a loopback port in the **51000-59999**
  band, served with `base=/proxy/<port>/`, dialing HMR back over
  `wss://...:443/proxy/<port>/`. Its `/api` + `/ws` calls are same-origin absolute,
  so they hit the ONE shared backend — there is no per-preview backend.
- So this previews **frontend** changes. Full-stack per-workspace instances (each
  with its own backend) are not supported on one origin: every backend would set
  the same session cookie on the same origin, and they collide.

## What surrounds a preview (already wired — don't rebuild it)

- **Switchboard + down-page:** `/proxy/` (no port) serves a self-contained page
  (`openhost-preview-fallback.html`, repo root) that scans the band from the
  browser and links to live previews. nginx serves the SAME page when a
  `/proxy/<port>/` target is dead, with a way back and an auto-reload poll that
  returns to the preview once its server is back.
- **Identity meta:** each preview's index.html carries
  `<meta name="sculptor-preview" content="<branch>@<sha>[*]">` (`*` = dirty
  tree), injected per request by `previewIdentity` in
  `sculptor/frontend/vite.base.config.ts` under `SCULPTOR_OPENHOST_PROXY`. A
  tree with no `.git` reports the frontend dir it serves from instead — e.g.
  `/app/sculptor/frontend` for a preview of the deploy image, which ships no
  git history. The switchboard and the switcher extension show this label.
- **Preview-switcher pill:** the `openhost-preview-switcher` extension
  (`sculptor/frontend/extensions/`, auto-installed at boot by `openhost-run.sh`)
  renders a bottom-left pill in the deployed app listing live previews in
  51000-51099, and an amber badge with a way back when ON a preview. Switching
  preserves the `#/` route.
- **HMR keepalive:** the dev server sends a no-op custom HMR event to every
  client every 25s (`previewHmrKeepalive` in
  `sculptor/frontend/vite.base.config.ts`, also `SCULPTOR_OPENHOST_PROXY`-gated).
  Without it the idle HMR websocket gets killed by the edge and Vite
  hard-reloads the page about once a minute (and on every return from the
  background). If "random reloads" ever reappear, check the keepalive before
  suspecting app code.

## Run a preview

Use a port in the 51000-51099 band. The preview-switcher pill in the
deployed app only auto-discovers that range (and the `/proxy/` switchboard page,
openhost-preview-fallback.html, quick-scans it on load), so a preview there shows
up without a full-band scan. A higher port (51100-59999) still works, but it will
**not** appear in the pill — you'd reach it only via the switchboard's full-band
scan or a direct `/proxy/<port>/` URL, so don't reach for a random high port. The
zero-friction way to get a valid one is to let the script pick: run
`launch-preview.sh` with **no argument** and it auto-selects a free 51000-51099
port (printed to the log).

Launch it **DETACHED** — do NOT use a tracked background task; this Sculptor will
not release your turn to the user while one is alive:

    cd <frontend-dir>
    setsid bash launch-preview.sh 51042 >/tmp/vite-51042.log 2>&1 </dev/null &

(or `setsid bash launch-preview.sh >/tmp/vite-preview.log 2>&1 </dev/null &` with
no port to auto-pick a free 510xx one — then read the chosen port and the
`ready in` line from the log.)

`<frontend-dir>` is either:
- **`/app/sculptor/frontend`** — preview the deployed UI as-is (its `node_modules`
  and `.venv` are already there, so it starts fast), or
- **your workspace's `sculptor/frontend`** — preview YOUR edits with HMR. A fresh
  worktree has no `node_modules`, so run `pnpm install` there once first (slow),
  then launch.

`launch-preview.sh [port]` sets `SCULPTOR_FRONTEND_PORT` + `SCULPTOR_OPENHOST_PROXY`
and runs `pnpm run dev` — the `/proxy/<port>/` base AND the OpenHost wss/HMR
override are both derived from those env vars in `vite.base.config.ts`, so do NOT
pass `--base` yourself (pnpm forwards a stray `--` that Vite reads as
end-of-options and silently drops the flag). First start pre-bundles deps
(~tens of seconds) — watch
`/tmp/vite-<port>.log` for `ready in`. Then open, on any logged-in browser:

    https://sculptor.<your-zone>/proxy/51042/

Edits to the frontend source hot-reload live.

## Stop a preview

Do NOT `pkill -f vite...` — the pattern matches your own shell command and kills
the call. Stop by port -> pid -> process group:

    PID=$(ss -tlnpH | grep ':51042' | grep -oE 'pid=[0-9]+' | head -1 | cut -d= -f2)
    PGID=$(ps -o pgid= -p "$PID" | tr -d ' ')
    kill -9 -"$PGID"

## Gotchas

- **Detached, not background.** Launch via `setsid ... &` from a normal foreground
  command so your turn releases. A `run_in_background` task or persistent `Monitor`
  blocks the user from talking to you until it ends.
- **One browser per workspace page.** Sculptor syncs tab state via `localStorage`,
  so the same workspace open in two browsers can desync — preview on a different
  page/tab than the one you're chatting in.
- **Same-origin trust.** Previews share the app's origin, so preview JS runs with
  your session's privileges — only run frontend code you trust.