# Pylon Web

Local React client and loopback-only Node host for Pylon.

```sh
npm install
npm run dev --workspace @pylon/web
```

The development server hosts the Pi runtime, same-origin API, event stream, and Vite middleware at `127.0.0.1:3141`. Use `PYLON_CWD` or `PYLON_PORT` to override the defaults.

## Structure

- `src/main.tsx`: browser bootstrap; `src/server/index.ts` and `start.ts`: host entry points.
- `src/client/app`: app composition, navigation, appearance, and global styles.
- `src/client/{browser,conversation,database,sessions,settings,terminal,usage,workspace}`: feature UI, hooks, pure client helpers, and companion styles.
- `src/client/rendering`: code and markdown rendering, deferred syntax highlighting, and file icons. `file-icon-map.ts` is generated by `scripts/sync-file-icons.mjs`.
- `src/client/runtime`: browser API client, event store, synchronization helpers, and remote UI dialogs.
- `src/client/ui`: reused controls, icons, formatting, keyboard shortcuts, and audio.
- `src/server/http` and `transport`: loopback HTTP/WebSocket handling, security, static assets, commands, and event replay.
- `src/server/runtime/session-runtime.ts`: one SDK-backed session runtime.
- `src/server/runtime/runtime-coordinator.ts`: selected-session routing and concurrent runtime lifecycle. Other runtime files bridge SDK events, hooks, attachments, tools, and remote UI.
- `src/server/{database,packages,sessions,settings,usage,workspace}`: credentials, package discovery, session indexing, settings, usage aggregation, and workspace operations and persistence.
- `src/shared/{protocol,sessions,settings,workspace}`: protocol contracts and helpers required by both client and server, including annotation validation and its code-viewer model dependency.
- `test`: existing flat Node test suite; `public`: assets served at stable URLs.

Keep files beside the feature that owns them, with descriptive kebab-case names and companion CSS. Use direct relative imports rather than barrel exports. Client and server may import shared code; shared code must not import either runtime layer. Tests may import pure client helpers directly without pulling in React or TSX.

The coordinator keeps running sessions alive in the background. An unselected session that was only viewed sleeps after one minute; one that received input sleeps after 30 idle minutes. Switching to an awake session reuses its runtime.

## Commands

```sh
npm run typecheck --workspace @pylon/web
npm test --workspace @pylon/web
npm run build --workspace @pylon/web
npm run verify --workspace @pylon/web
npm run start --workspace @pylon/web
```

For focused tests and direct TypeScript diagnostics, run Node from `platform/web` so runner options stay before the test path and the repository's native TypeScript transform is used:

```sh
cd platform/web
node --experimental-transform-types --test-concurrency=2 --test --test-name-pattern="terminals stay attached per session until that session deactivates" test/server-transport.test.ts
node --experimental-transform-types --input-type=module --eval "import { SessionIndex } from './src/server/sessions/session-index.ts'; console.log(SessionIndex.name)"
```

Node's native transform does not load `.tsx`. Tests that need a client module can use the already-installed Vite transform, which handles TSX and extensionless production imports:

````ts
```ts
import { createServer } from "vite";
const vite = await createServer({ server: { middlewareMode: true }, appType: "custom" });
try { const module = await vite.ssrLoadModule("/src/client/app/navigation.ts"); }
finally { await vite.close(); }
````

## Session workspaces

The sidebar also includes a built-in **General** scope below Projects. General sessions are rooted at the current OS user's home directory, can search and edit files available to that user through explicit paths, and do not use repository indexing. Normal Guard protections still apply.

New sessions use the project's explicit workspace policy. Local works directly in the registered folder without changing branches, Project folder uses a Pylon session branch in that checkout, and Session worktree creates a linked worktree under the agent directory. Project setup commands run only inside newly created worktrees.

Project-folder and Session-worktree sessions can apply their bounded session delta to the branch currently checked out in the registered project folder. The merge preserves that branch's index and unrelated working changes, and leaves the applied result uncommitted. Project-folder sessions continue as Local afterward; Session-worktree sessions remain isolated.

The Files right panel exposes bounded, read-only file content and per-session diffs. “Move to project checkout” parks the checkout's branch, index, and working state and moves the session branch there; “Move to worktree” reverses that operation. Timeline must confirm checkpoint portability before either handoff.

When `pi-helios` is active, the Browser right panel can launch or take exclusive direct control of a Helios-owned browser. The screenshot-backed viewport supports pointer, keyboard, wheel, navigation, resize, and tab controls. Attached user browsers remain tool-only; panel frames are local, ephemeral, and served with `Cache-Control: no-store`.

`npm run verify` runs type checking, Node tests, and the production build. Before release, also exercise the session switcher, image paste/retry flow, responsive layout, and remote dialogs with keyboard-only navigation.