Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
MSO frontend implementation contract
Current reference for every agent and contributor changing a visible MSO surface. Applies to
frontend/,app/, shared UI, and native HTML/CSS/JS surfaces inlib/. This is a required implementation/review contract, not a claim that every existing feature already meets every rule. Record adoption and evidence per changed feature.
Read before changing a feature
- Read root
AGENTS.mdandCLAUDE.mdfor source, host, permissions and release rules. - Read
DESIGN.mdfor the established product direction and semantic tokens. - Read this contract and
UI-UX-FOUNDATION.mdfor shared layout/state. - Read
Shell UI architectureand the affected shell's localdesign.md; preserve all five shell identities. - Read the feature's own contract and find a working sibling implementation.
SLICE-CATALOG.mdis the feature inventory SSOT. - Follow
ARCHITECTURE.md; run its ratchet before adding a seam.
For a whole-product request, inventory every registered feature before narrowing changes. Mark each item as fixed, verified unchanged, configuration-blocked, or not yet verified. A shared primitive improvement does not prove all consumer journeys were exercised.
Ownership: shell, feature, UI kit
| Layer | Owns | Required seam |
|---|---|---|
| Shell | Platform chrome, work area, typography, native navigation, default metrics | ShellManifest.layout, active design profile and LayoutBoundary |
| Feature | Content hierarchy, local override, loading/data/error states, feature actions | AppFrame, optional layout and padded, container-driven navigation |
| UI kit | Control geometry, semantic colour, focus, disabled/busy states, dialogs | Existing shared components and inherited metrics |
Do not fork API calls, validation, permission logic or durable state by operating system.
Mobile shells own feature navigation: one shell header, centered title and the established
back/AI actions. Do not add a second competing mobile feature header.
Use ResponsiveDialog/FormDrawer for native shell presentation unless a documented feature
need requires an override. Portals must inherit the active layout and theme boundary.
Native DOM surfaces use their existing shared DOM components and the reviewed token bridge;
do not import React frontend components into server infrastructure.
Layout, padding and responsiveness
- Inherit
--feature-padding,--feature-gap,--feature-sidebar-width,--ui-control-heightand--ui-control-padding. Put reusable defaults at the shell or UI-kit layer, feature-specific exceptions onAppFrame.layout, not in every consumer. - Use semantic spacing/type/colour tokens. New literal values need a feature-specific reason; do not add another global scale or scatter OS checks through feature components.
- Opt into page spacing with
padded; editors, terminal and canvases can remain edge-to-edge. - Adapt to the feature container, including a narrow desktop window. Viewport width alone cannot decide whether a feature sidebar is inline or a drawer.
- Constrain flex/grid children with
min-width:0andmin-height:0where necessary. Assign one intentional scroll owner per region; avoid clipped controls and accidental nested scroll. - Long names, URLs, translated copy and real empty data must wrap or truncate with a way to recover the full value. Essential actions cannot disappear offscreen.
- Respect mobile safe areas, portrait/landscape, software keyboard, touch and larger text. A canvas may scroll internally; the whole document must not acquire accidental overflow.
- Fine-pointer dense desktop controls may follow shell metrics; touch targets must be at least 44 CSS px. Do not shrink tap targets merely to preserve a desktop row on a phone.
- Preserve intended window/widget geometry separately from constrained rendered geometry. Resizing the viewport must not permanently overwrite the user's preferred position/size.
State and asynchronous work
- Name the owner and lifetime of state: local interaction, exact window, URL, persisted user preference, durable feature record or server response. Do not conflate these identities.
- Use
useFeatureState(winId, key, initial)when ephemeral state must survive shell remounts. Forward the same window ID through desktop, Dashboard, iOS and Android. Closing the window clears that state; browser reload does not imply unsaved drafts are durable. - Use the existing feature store/API for durable data. Never persist secrets in localStorage, duplicate a second store, or store sensitive data merely to preserve a visual state. Unsubmitted credential form drafts may use the existing exact-window memory store as operational input. Clear them on save, discard, confirmed navigation and window close, and clear sensitive drafts on sign-out or loss of Owner privilege. They must never enter saved layouts, inspector payloads, URLs, logs or preference synchronization.
- Drafts need explicit save/discard behaviour and an unsaved-change guard at the relevant close, route, record and reload boundaries. State from one window/owner cannot bleed into another.
- Abort superseded requests and unmounted effects, or ignore results with a sequence/identity guard. Changing selected owner/provider/project must not display a late result for the old one.
- Prevent duplicate writes, show pending feedback, handle rejection and restore retry controls. Optimistic updates need a defined rollback. A completed request must update the canonical state.
- Distinguish initial loading, empty data, no filter matches, error, unavailable service and permission denied. A timeout or iframe load event alone is not successful readiness.
- URL/deep-link restoration must wait for asynchronous feature/connected-app registration. Keep the existing History API routing contract; do not force full shell remounts for focus.
- Persist through the repository's validated schema and flush lifecycle. Malformed cache, storage failure and legacy state must degrade without breaking the feature.
Actions, menus, forms and copy
- Every visible interactive control must perform its stated action. No placeholder buttons, fabricated measurements, false success, invented security claims or demo data presented as live.
- Use icons for familiar repeated utilities such as reveal, copy, delete and overflow. Give icon-only controls a precise accessible name and tooltip. Decorative SVGs are hidden from AT.
- Keep text for primary/unfamiliar actions and for dropdown items; leading icons aid scanning. Dropdown triggers expose open/closed state. Preserve keyboard opening, Escape, outside close and focus return. Do not claim ARIA menu semantics without implementing its keyboard model.
- Reveal/copy secrets only after a human action. Keep Copy masked, provide feedback and discard temporary values on hide, timeout or failure. Never put secret values in labels, logs or URLs.
- Destructive actions keep the established confirmation, exact target and permission check. Cancel restores focus to that target or the closed trigger, not an arbitrary matching icon.
- Forms have associated labels, field-specific errors, useful validation and predictable submit behaviour. Explain disabled/unavailable actions when the reason is not obvious.
- Use plain, task-specific copy. No user-visible em dash. Empty and failure states offer a real recovery action where the feature can provide one.
- UI filtering is not authorization. Preserve server role checks and fail-closed permissions. Do not weaken iframe, origin, filesystem or service policy to make a preview appear successful.
Accessibility, theme and motion
- Both shipped themes use semantic colours and WCAG AA text contrast. Run the contrast gate; also inspect the rendered composition, since token checks alone cannot prove every overlap.
- Support keyboard-only navigation, visible focus, meaningful headings/landmarks and labels. Dialog/drawer focus is contained while open; background regions are inert where appropriate.
- Use the correct native element before adding ARIA. Announce asynchronous status without repeatedly stealing focus. Status must not depend only on colour or an unlabeled icon.
- Respect reduced motion, touch input and larger text. Avoid motion that changes the effective layout measurement or prevents access to a control during an animation.
- Loading/skeleton states preserve meaningful hierarchy without masquerading as real data.
Feature-specific acceptance
The same contract applies to every family below; use the catalog for exact feature ownership.
| Feature family | Additional journey to verify |
|---|---|
| Files, terminal, code and host tools | Selection/path/session identity, resize, scroll, keyboard, permission failure and real error recovery |
| Assistant, channels, agents, managed runtimes | Conversation/turn identity, stream cancellation, activity state, reconnect and unavailable runtime |
| Workflows, Organization, Memory and canvas/media editors | Draft/save/discard, selection, canvas bounds, filters, undo where supported and reload boundaries |
| Settings, Integrations and infrastructure | Owner/project scope, input validation, pending/error state, secrets, confirmation and long menus |
| Browser, n8n and external/connected apps | Ready handshake, denied embedding, failed route, reload, external-open fallback and origin isolation |
| Store, Create, Quicklinks, Docs and pickers | Empty/search/no-match, valid navigation, real action completion and focus return |
| Shell, authentication and lock surfaces | Five-shell transitions, deep links, locked privacy, safe areas, portals and restored/minimized windows |
Verification and definition of done
- Reproduce the original problem; preserve the first error or screenshot and identify the real repository/runtime. Choose the smallest authoritative reversible fix.
- Add behaviour tests for state or interaction regressions. Do not add tests that only mirror cosmetic markup. Wire important journeys into existing mandatory gates.
- Inspect the actual frontend using synthetic fixtures for sensitive writes. Follow the operator's chosen design/browser tools. When pen.dev MCP and Browser are requested, use those surfaces; do not take over the native desktop. Keep source edits in the authorized checkout.
- For changed shared layout/state, inspect all five shells and both themes. For local feature changes, inspect the affected shell contexts plus representative desktop, narrow window and mobile sizes. Record exact sizes, larger-text checks and keyboard behaviour. Continuous CSS support is the goal; finite samples are not proof of every possible resolution or real device.
- Check loading, empty, no-match, error, permission, pending and success states that apply. Include a route/reload or shell-remount round trip when the changed state promises to survive it.
- Run targeted tests, architecture/docs/contrast gates and the repository-required full local, security and remote checks on the exact committed SHA. A build pass alone is insufficient.
- In the PR/final report include: feature and owner, before/after, affected layers, state lifetime, shell/theme/viewport evidence, test results, untested paths, external configuration limits and deployed SHA if released. Mark blocked or unverified items honestly; do not call them fixed.
- Ship through the canonical main/release path in root instructions. Preserve rollback and verify runtime health plus the actual user journey before claiming a deployed fix.
Evidence row for each feature in a whole-product audit
| Feature / catalog entry | Observed problem | Shared/local change | Shell/theme/size journey | Result and limit |
|---|---|---|---|---|
| Exact feature name | Concrete error/screenshot | Owning layer and file | Named interactions and sample dimensions | Fixed / verified unchanged / configuration-blocked / not verified |
A rule exception must identify the rule, concrete reason, affected consumers and proof. If it conflicts with a task or root policy, name the conflict and ask; do not silently change the rule.