fix: make base-path deployments portable

[jmfederico]

Summary

• make one published client build work at /, /ai/, and deeper canonical prefixes such as /test/ai/ when a reverse proxy strips the prefix
• route HTTP/XHR, images, plugins, and WebSockets through one application-base contract, with absolute ws:/wss: WebSocket URLs
• keep PWA navigation and assets inside the deployment prefix
• preserve local and federated plugin loading across rolling upgrades: upgraded remotes retain leading application-root module references, while updated gateways also accept manifest-relative and legacy plugin-root-relative inputs
• document canonical trailing slashes, prefix stripping, authentication, and HTTP/WebSocket reverse proxying without adding deployment-specific PI WEB server configuration

This work builds on and preserves the original authored commit from @yimeng's PR #46. Thank you to @yimeng for the initial arbitrary base-path implementation. This branch completes that feature against current main without changing PR #46 itself.

Architecture and compatibility

• Vite builds standard client assets with portable relative references (base: "./"), so no prefix-specific rebuild is needed.
• A small application URL resolver combines import.meta.env.BASE_URL with the document base. Core browser routes stay application-relative until one named boundary resolves them; Path/Url helper naming and contributor guidance make deviations easy to assess. API requests, XHR uploads, images, plugin manifests/modules, and WebSockets use that contract.
• WebSocket endpoints resolve as HTTP(S) application URLs first, then map explicitly to absolute ws:/wss: URLs for the supported browser target.
• PWA start_url, scope, and icons remain manifest-relative.
• Plugin manifests retain leading application-root module references so gateways on current main can consume upgraded remotes. The browser maps those references into the current application base.
• Federated gateways additionally accept explicit manifest-relative (./<plugin-id>/<asset>) and legacy plugin-root-relative (nested/plugin.js) inputs, then rewrite accepted modules to deployment-relative gateway references.
• No PI_WEB_BASE_PATH setting or other deployment-specific runtime/build source of truth is introduced.

Documentation and release note

• Added reverse-proxy guidance to the README and published docs, including /ai → /ai/ redirects, prefix stripping, authentication placement, forwarded headers, and WebSocket proxying.
• Updated plugin and machine-federation docs for leading application-root manifest output, portable plugin assets, and prefixed gateways.
• Added .changeset/portable-base-paths.md; Changesets reports only @jmfederico/pi-web queued for a patch bump.

Verification

Run across implementation and independent final reviews, with the latest full checks at c64a01d:

• npm test -- --run src/server/piWebPluginService.test.ts src/server/app.plugins.test.ts src/client/src/plugins/external.test.ts — focused plugin compatibility coverage passed, 3 files and 22 tests.
• npm run verify — typecheck, ESLint, Knip, and all 168 test files passed; 1119 tests passed and 2 skipped (1121 total).
• npm run build — passed; 223 client modules transformed and 8 TypeScript plugin files built. The only warning is the existing Vite chunk-size warning.
• npm run pack:dry — passed, including a production rebuild; 216 package files, displayed package size 1.6 MB and unpacked size 3.8 MB.
• Built-content audit — all 6 app-owned references in dist/client/index.html are relative; none are leading-root. Manifest start_url, scope, and icons are relative.
• Disposable production reverse-proxy smoke test — passed at /, /ai/, and /test/ai/ for HTML, entry assets, favicon/image, PWA manifest scope/start URL, GET api/projects, local plugin manifest, and local plugin module. Also passed 308 redirects for /ai and /test/ai and a real WebSocket upgrade through stripped /test/ai/.
• Application-path convention audit, independent focused review, npm run changelog:status, git diff --check, branch ancestry/original-author checks, and tracked grep for PI_WEB_BASE_PATH / piWebBasePath — passed.