Run Dev Tools on Virtual Control (VC-4) by ndorin · Pull Request #55 · PepperDash/essentials-devtools

ndorin · 2026-10-22T18:55:02Z

Pairs with PepperDash/Essentials#1532, which puts the Dev Tools in each VC-4 room's own Html folder.

Problem

On VC-4, https://<server>/VirtualControl/Rooms/<RoomId>/cws/debug/ loaded a blank page (confirmed on bosd-vc401, room DEMOV3):

The build used an absolute base of /cws/debug/, so the browser requested /cws/debug/assets/index-*.js from the server root: 404. The same file is served under the room path.
Every API call went to /cws/appNN/api/.... On VC-4 the room's API is at <prefix>/cws/api/..., with no appNN.
Sign-in posted to /cws/app01..app10/api/login. A VC-4 room answers its own login with 500 "Authentication is not currently enabled on the controller" (the VC-4 web server does the signing in), which the form treated as wrong credentials.

Changes

shared/functions/hostPaths works out the layout from the page path: the prefix before /cws/, whether it's a VC-4 room, and the room ID. Everything below uses it.
Assets: the production build uses relative asset paths, and an inline script in index.html sets <base> to <prefix>/cws/debug/ before any asset tag, so deep links (.../cws/debug/app01/versions) still resolve after a reload. npm start keeps the absolute /cws/debug/ base.
Router basename is <prefix>/cws/debug.
API: the base is <prefix>/cws. On VC-4 the room ID acts as the single app ID (routes like /DEMOV3/versions), and /<RoomId>/api/... is mapped to VC-4's /api/.... Appliance URLs are unchanged.
Sign-in probes app01..app10 on an appliance and only the room on VC-4. A program answering "Authentication is not currently enabled" now counts as available, which also covers a 4-series with authentication turned off.
TopNav's app switcher no longer assumes appNN names; the routing-feedback session URL uses the same helper.

Testing

New tests: hostPaths (appliance, VC-4, casing, deep links, API mapping) and authErrors, plus a LoginForm test that signs in from a VC-4 room path against an auth-disabled response and checks it posts to /VirtualControl/Rooms/DEMOV3/cws/api/login (verified to fail without the change).
294 tests pass; tsc -b, lint, prettier and npm run build are clean. The built index.html has the base script ahead of every asset tag and only relative asset URLs.
MC4 (4-series): packaged into Essentials as essentials-devtools.zip, the page, its bundle under /cws/debug/assets/, and a deep link all return 200.
VC-4 browser test on bosd-vc401: results to follow in a comment.

Not covered: the debug-console and routing-feedback WebSockets connect to URLs the server returns; whether those ports are reachable on a VC-4 host is a server-side matter, like the Mobile Control port.

🤖 Generated with Claude Code

On VC-4 the app is served at /VirtualControl/Rooms/<RoomId>/cws/debug/ and the room's API is at <prefix>/cws/api, but the app assumed /cws/debug everywhere: its assets were requested from /cws/debug/assets at the server root (404, blank page), and every API call went to /cws/appNN/api. - shared/functions/hostPaths works out the layout from the page path: the prefix before /cws/, whether it's a VC-4 room, and the room ID. - The build uses relative asset paths, and index.html sets <base> to <prefix>/cws/debug/ at load so deep links still resolve. The dev server keeps its absolute /cws/debug/ base. - The router basename and the API base come from the layout. On VC-4 the room ID is the single "app ID", and /<RoomId>/api/... is mapped to VC-4's /api/... base, so routes and endpoints are otherwise unchanged. - Sign-in probes app01..app10 on an appliance and just the room on VC-4. - A program answering "Authentication is not currently enabled" counts as available instead of failing sign-in. VC-4 rooms answer this way (the VC-4 web server signs users in), as does a 4-series with auth disabled. - TopNav's app switcher no longer assumes appNN names, and the routing feedback session URL goes through the same helper. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot

🟡 Changes recommended

The document base breaks Help fragment links, and mount detection produces incorrect paths for VC-4 rooms named cws.

2 open issues

What changed in this PR

Adds VC-4 room support to Dev Tools while preserving appliance behavior, complementing the server-side deployment of Dev Tools into each room’s HTML folder.

Changes:

Derives asset, router, and API paths from the hosting location.
Uses room IDs for VC-4 app selection and accepts authentication-disabled login responses.
Adds host-layout and sign-in regression tests.

File	Description
vite.config.ts	Uses relative asset paths for production builds.
src/store/auth/authErrors.ts	Recognizes authentication-disabled responses.
src/store/auth/authErrors.test.ts	Tests login-error classification.
src/store/apiSlice.ts	Applies host-aware API paths.
src/shared/functions/hostPaths.ts	Centralizes appliance and VC-4 path handling.
src/shared/functions/hostPaths.test.ts	Tests host detection and URL mapping.
src/services/httpService.ts	Supports request-path rewriting.
src/index.tsx	Sets a host-aware router basename.
src/features/TopNav.tsx	Supports room IDs when identifying app routes.
src/features/Routing.tsx	Uses the shared routing-session URL helper.
src/features/LoginForm.tsx	Adjusts login discovery and availability handling.
src/features/LoginForm.test.tsx	Tests VC-4 sign-in with authentication disabled.
index.html	Sets the asset base dynamically for deep links.

_{Review effort: Balanced}

New how-to, "Use Dev Tools on Virtual Control (VC-4)": the per-room Dev Tools address, signing in when the room has Crestron authentication off, and the firewall ports the VC-4 host must open: - 65435-65534/tcp for the Debug Console WebSocket - 65335-65433/tcp for the routing feedback WebSocket - the Mobile Control direct server port (50002 by default), per room with firewalld commands, accepting the WebSocket certificate per port, and troubleshooting for blank pages, failed sessions and blocked ports. Linked from the how-to index, the README's program-slot section, and the connection troubleshooting guide. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ndorin · 2026-10-22T19:55:19Z

Added a how-to, Use Dev Tools on Virtual Control (VC-4) (docs/how-to/use-dev-tools-on-vc4.md). It covers:

the per-room Dev Tools address and signing in;
the firewall ports the VC-4 host must open, with firewalld commands: 65435–65534/tcp (Debug Console), 65335–65433/tcp (routing feedback), and the Mobile Control direct server port per room;
accepting the WebSocket certificate per port;
troubleshooting for blank pages, failed sessions and blocked ports.

It's linked from the how-to index, the README and the connection troubleshooting guide, so it shows up in the in-app Help.

Verified on bosd-vc401 (DEMOV3) with PepperDash/Essentials#1532 and #1533: the page loads, and with those ports open both WebSockets complete a TLS upgrade (101 Switching Protocols).

🤖 Generated with Claude Code

Copilot

🟡 Changes recommended

Asset-base detection mistakes a room named CWS for the application mount, preventing that room’s page from loading.

3 open issues

_{Review effort: Balanced}

…n the article - index.html and getHostLayout split the path at the first /cws/, which for a VC-4 room named CWS is the room ID. Both now match the /cws/debug mount. - The <base> tag made same-article Help links such as [Get API Paths](#get-api-paths) resolve to the app root. DocLink now routes them with React Router, keeping the article's path. - Tests run the real inline <base> script from index.html against sample paths. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot

🔵 Needs a closer look

A room-ID session regression remains unresolved, and target-host validation of the coordinated client/server changes is still pending.

1 open issue

Room IDs help/login break Debug Console sessions · New

3 resolved since last review

_{Review effort: Balanced}

On VC-4 the program ID is the room ID, so a room can be named help or login. getRouteAppId rejected those names outright, so Start Debug Session in such a room saw the response as stale, stopped the server session and left the button on "Connecting...". It now decides by the second segment: a path whose second segment is a program page belongs to the program in the first. The lookup moves to shared/functions/routeAppId.ts with tests for both room names, and a test that its page list covers every page routed under :appId in App.tsx. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot

🔵 Needs a closer look

End-to-end VC-4 browser validation remains pending for the combined asset-loading, sign-in, and session flows.

No open issues 🎉

1 resolved since last review

Room IDs help/login break Debug Console sessions

_{Review effort: Balanced}

ndorin · 2026-10-22T23:20:50Z

End-to-end check on Virtual Control. This answers the review's note about pending VC-4 browser validation.

Setup:

Where: headless Chrome, against the live VC-4 room DEMOV3 on bosd-vc401, at /VirtualControl/Rooms/DEMOV3/cws/debug/.
What it was running: Essentials 3.0.0-http-polling.2 (#1532 and #1536), with a dev tools build combining this PR, feat: read the debug console and routing feedback over HTTP polling on VC-4 #56 and feat: make Dev Tools usable on a phone in portrait #58.
What the build lacks: that build predates this PR's last commit (3ec7146, rooms named help/login). That commit has unit tests but isn't in this run.

Step	Result
Page and assets load from the room mount; `<base>` is `…/Rooms/DEMOV3/cws/debug/`	✅ no 4xx/5xx on any asset
Sign-in with room authentication disabled → `/DEMOV3/versions`	✅ 6 assemblies listed
In-app navigation to API Paths through `…/cws/api` (no `appNN`)	✅
Debug Console: start, messages arrive, stop	✅ over HTTP polling
Routing page live-feedback badge	✅ Live
Help article from a deep link inside the room	✅
Full reload of `…/debug/DEMOV3/apiPaths`, sign in again → back on API Paths	✅
No WebSockets and no requests to ports 65335–65534	✅ 0 and 0

The only HTTP error in the run was POST …/cws/api/login → 500 {"Error": "Authentication is not currently enabled on the controller"}. That's the room's answer when authentication is off, and isAuthenticationDisabledError treats it as signed in, as intended.

🤖 Generated with Claude Code

Copilot AI balanced review requested due to automatic review settings October 22, 2026 18:55

Copilot started reviewing on behalf of ndorin October 22, 2026 18:55

View session

Copilot AI reviewed Oct 22, 2026

View reviewed changes

Comment thread index.html Resolved

Comment thread src/shared/functions/hostPaths.ts Resolved

Copilot AI balanced review requested due to automatic review settings October 22, 2026 19:55

Copilot started reviewing on behalf of ndorin October 22, 2026 19:55

View session

Copilot AI reviewed Oct 22, 2026

View reviewed changes

Comment thread index.html Resolved

ndorin mentioned this pull request Oct 22, 2026

feat: read the debug console and routing feedback over HTTP polling on VC-4 #56

Merged

ndorin added this pull request to stack #57 October 22, 2026 21:05

Copilot AI balanced review requested due to automatic review settings October 22, 2026 21:07

Copilot started reviewing on behalf of ndorin October 22, 2026 21:07

View session

Copilot AI reviewed Oct 22, 2026

View reviewed changes

Comment thread src/shared/functions/hostPaths.ts Resolved

Copilot AI balanced review requested due to automatic review settings October 22, 2026 22:44

Copilot started reviewing on behalf of ndorin October 22, 2026 22:44

View session

ndorin mentioned this pull request Oct 22, 2026

feat: make Dev Tools usable on a phone in portrait #58

Merged

Copilot AI reviewed Oct 22, 2026

View reviewed changes

ndorin requested a review from jonnyarndt October 22, 2026 23:17

jonnyarndt approved these changes Oct 22, 2026

View reviewed changes

ndorin merged commit cee5d5e into main Oct 22, 2026
3 checks passed

Navigation Menu

Repository navigation

Run Dev Tools on Virtual Control (VC-4) - #55

Run Dev Tools on Virtual Control (VC-4)#55
ndorin merged 4 commits into
mainfrom
feature/vc4-support

ndorin commented Oct 22, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

ndorin commented Oct 22, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

ndorin commented Oct 22, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

ndorin commented Oct 22, 2026

Problem

Changes

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

ndorin commented Oct 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

ndorin commented Oct 22, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants