UI Runtime Modes: RuntimeContext v2 + capability system (replaces FeatureFlags)

[itlackey]

Summary

Replace FeatureFlags { admin: boolean } with a two-layer RuntimeContext + capability resolution system. This is the foundation that enables assistant-container mode, PWA mode, and the connection-management refactor.

Background

The current features.admin boolean cannot express:

• "Chat + assistant settings but no host management" (assistant-container)
• "Connection management only" (PWA/client-only install)
• "Full host management without Electron IPC" (browser to host-ui)

Every route currently checks if (features.admin) in scattered locations. There is no single source of truth for what the current deploy mode can do.

Design

Full design in docs/technical/ui-runtime-modes-plan.md.

Two-layer model

Server context (computed at request time, public via /api/runtime):

type ServerRuntimeContext = {
  version: 2;
  hostMode: 'electron-host' | 'host-ui' | 'assistant-container' | 'pwa-static';
  serverCapabilities: Capability[];
  // ... routes, security, versions
};

Client context (detected in the browser — never server-computed):

type ClientContext = {
  displayMode: 'electron' | 'standalone-pwa' | 'browser';
  activeConnection?: { kind, id, grantedCapabilities? };
};

Resolved = resolveCapabilities(serverCaps, clientCtx) — one function, one file.

Capability matrix

hostMode	clientDisplayMode	Effective capabilities
electron-host	electron	ALL
host-ui	browser	ALL (minus Electron IPC)
assistant-container	browser / standalone-pwa	chat, assistant-settings:read/write
pwa-static	standalone-pwa / browser	connections:manage, connections:switch, chat, pwa:install

Extension point

activeConnection.grantedCapabilities allows future rules (e.g. "assistant settings when connected to a remote assistant-container") without touching the resolution function structure.

Acceptance criteria

• lib/server/features.ts → computeServerRuntimeContext(event) returning ServerRuntimeContext
• lib/runtime-context.svelte.ts → resolveCapabilities(serverCaps, clientCtx), hasCapability(cap), reactive runtimeContext store
• lib/client-context.ts → detectClientDisplayMode() (client-only, never server-computed)
• routes/+layout.server.ts returns serverRuntimeContext
• routes/+layout.svelte initializes clientContext and derives effectiveCapabilities
• routes/api/runtime/+server.ts — public endpoint, no auth required
• features.admin derived alias preserved so existing code continues to work until migration completes
• Zero if (features.admin) checks added (all new code uses hasCapability())
• Capability matrix correct for all four host mode combinations
• bun run ui:check 0 errors 0 warnings; existing tests pass

Related

• docs/technical/ui-runtime-modes-plan.md — §6.1, §6.2, §6.3, Phase 1
• Remote-only (client) install: connect to a remote assistant/stack #486 — connection management (Phase 2, depends on this)
• Reconcile app styling to the setup-wizard design language (normal modes) #506 — styling (route split depends on capability-driven landing, Phase 3)
• @openpalm/skeleton npm package — replace GitHub raw fallback with versioned artifact delivery #508 — skeleton package (Phase 0, prerequisite)

[fwdslsh-dev]

Direction ratified 2026-07-06 (docs/technical/ui-client-split-assessment.md): this issue's scope is unchanged and confirmed as the foundation — RuntimeContext v2 + resolveCapabilities() proceed exactly as written.

Two notes from the re-scope:

• After Extract packages/client (@openpalm/client) + packages/ui-kit — thin static client app (Phase 5) #555 lands, the client app gets its own (smaller) capability space: host:* members are absent from its local Capability union — narrowing enforced by the type system rather than runtime filtering. The host app keeps the full union. Same function shape in both.
• /api/runtime gains a second job: the contract-version handshake the hosted client uses to degrade gracefully against older instances (PWA mode: installable client from two origins — localhost (zero TLS) + official hosted URL #511). Worth including the contract version in the payload from day one.

Also: #556 (openpalm admin) ships the host-ui mode early via the existing env flag and picks up the proper hostMode from this work when it lands.

---

Generated by Claude Code

[itlackey]

Completed by merged PR #559 (merge commit c1eadbd). RuntimeContext v2, capability resolution, server runtime context, runtime API, capability-driven landing/navigation, and the Phase 1-4 control-plane split landed in this PR.