vps-page

VPS Control Room — Svelte Page Pattern

Use this pattern for a terminal-scoped frontend page or substantial page refactor. Root CLAUDE.md remains the SSOT. Do not add a new page for provider management, browser automation, scheduling, managed apps, or other non-terminal product scope.

Location

frontend/src/routes/<route>/+page.svelte
frontend/src/routes/<route>/+page.server.ts     # only when server-side page loading is useful
frontend/src/routes/<route>/+error.svelte       # when route-level recovery needs custom UX
frontend/src/lib/features/<feature>/            # reusable feature logic/components

Do not build large feature logic directly into +page.svelte; keep the route as orchestration and place domain logic in a vertical slice.

Svelte 5 state

<script lang="ts">
  let loading = $state(true);
  let error = $state<string | null>(null);
  let items = $state<Item[]>([]);
  let count = $derived(items.length);

  async function refresh() {
    loading = true;
    error = null;
    try {
      const response = await fetch('/api/example');
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      items = await response.json();
    } catch (cause) {
      error = cause instanceof Error ? cause.message : String(cause);
    } finally {
      loading = false;
    }
  }
</script>

Use $props(), $state, $derived, $effect, and snippets. Do not introduce legacy component syntax or shared writable/readable stores.

Data boundary

Frontend pages talk to authenticated SvelteKit server routes. Those server routes may proxy to the Node agent through $lib/server/gateway. Host access never occurs in the page/component itself.

For privileged proxy routes:

const denied = await requireSession(event);
if (denied) return denied;
return proxyGatewayJson('/some-agent-path');

Terminal live output is a special case: browser SSE is bridged server-side to the agent WebSocket. Do not invent a direct browser-to-agent socket.