first commit

openspec/changes/implement-platform-web-console-shell/design.md

@@ -0,0 +1,71 @@
+## Context
+
+`platform_web/` already contains the required first-party navigation entries and a working AI provider management page. The other first-party areas still use thin metric-only placeholders, and the shell owns only hash replacement without a reusable page model, status surface, or acceptance-focused layout.
+
+This change keeps implementation inside `platform_web/` and prepares the frontend for later server-management workflows. It uses existing Vite, React, TypeScript, local contracts, and fallback data patterns; it does not add backend behavior or cross-root imports.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make the console shell route-aware, accessible, and stable across refresh/hash navigation.
+- Give every required first-party area a useful operational page surface rather than a bare metric placeholder.
+- Keep API contracts and page contracts in dedicated frontend directories.
+- Add frontend client methods for currently available platform resources used by shell pages.
+- Add tests covering route/page behavior and page-level rendering.
+- Validate the UI with build/test commands and browser walkthrough evidence.
+
+**Non-Goals:**
+
+- Do not implement full server create/start/stop workflows; that is the next queued change.
+- Do not add billing, cloud host sales, provider marketplace, or unrelated SaaS behavior.
+- Do not expose raw AI keys, run credentials, host paths, storage backend credentials, or direct run sockets.
+- Do not introduce a router dependency unless existing hash navigation becomes insufficient.
+- Do not change backend platform APIs in this change.
+
+## Decisions
+
+### Decision 1: Keep hash routing for the shell baseline
+
+The app will continue to use hash-based navigation, but route resolution will be centralized in `routes/` and `stores/`. This keeps the console deployable as a static frontend while preserving direct links and refresh behavior.
+
+Alternative considered: add React Router now. Rejected because the current routing needs are simple and adding a dependency before workflow pages exist would increase surface area without improving the backlog item.
+
+### Decision 2: Use local page view contracts for first-party pages
+
+Each page will consume typed view contracts from `contracts/` and local-safe seed data until backend workflow APIs exist. Page components remain focused on rendering and local interactions, not hidden shared business types.
+
+Alternative considered: place page-specific types inside page components. Rejected because repository rules require frontend page roots to keep view contracts in fixed directories.
+
+### Decision 3: Extend the frontend API client only for existing backend endpoints
+
+The frontend client will add typed methods for health, game plugins, server instances, and bridge authorization where backend endpoints already exist. Pages may fall back to local data if APIs are unavailable.
+
+Alternative considered: create mock-only page data without API client expansion. Rejected because later workflow pages need a stable client surface and tests should exercise named contracts.
+
+### Decision 4: Design the shell for dense operational scanning
+
+The shell will prioritize compact navigation, status chips, tables/lists, and action strips over marketing-style presentation. The visual system should remain consistent with existing AI provider management styling.
+
+Alternative considered: add a landing-page style dashboard. Rejected because this is an operational game server management console, not a product marketing site.
+
+## Risks / Trade-offs
+
+- [Risk] Pages can imply workflows that are not implemented yet. Mitigation: label actions as planning/local status and avoid dispatching run jobs.
+- [Risk] Local fallback data can drift from backend contracts. Mitigation: keep frontend API types explicit and covered by tests.
+- [Risk] Hash routing can become limiting later. Mitigation: centralize route parsing so a future router can replace the implementation without changing page contracts.
+- [Risk] A richer shell may introduce responsive layout regressions. Mitigation: run build/tests and a browser walkthrough at desktop and mobile widths.
+
+## Migration Plan
+
+1. Add console shell view contracts, route helpers, API types/client methods, and tests.
+2. Expand first-party pages with operational sections and local-safe fallback data.
+3. Update shell styling for desktop and mobile responsive navigation/content.
+4. Run frontend tests/build/typecheck, structure validation, strict OpenSpec validation, and browser walkthrough.
+
+Rollback is contained to `platform_web/` and this OpenSpec change: remove the new page contracts/client methods/page rendering changes and return to the previous placeholder shell.
+
+## Open Questions
+
+- Whether a later workflow change should replace hash routing with a full router after server management forms and nested pages are introduced.
+- Whether dashboard summaries should eventually come from a dedicated backend summary endpoint or compose existing list endpoints.