Refresh puter UI, power telemetry and demand-aware monitoring
Build and test / macos (push) Waiting to run
Signed release / release (push) Waiting to run

This commit is contained in:
2026-09-22 20:03:16 -04:00
parent 0da94715be
commit 4bfa239aa0
38 changed files with 1728 additions and 492 deletions
+50
View File
@@ -0,0 +1,50 @@
# Puter interface rules
Puter is a compact macOS system utility. Its visual hierarchy is the page title,
live data, and the selected item's details. Keep the user's attention on those.
## Direction
The chosen direction pairs a Liquid Glass navigation layer with a compact,
readable data workspace. The earlier flat utility treatment was too bland;
a full glass dashboard would distract from the dense process table. Glass belongs
to navigation and actions, while resource color and larger values give data hierarchy.
- Use the system font, semantic text styles, and tabular digits for telemetry.
- Use the system accent for selection and actions. Resource/chart colors convey
resource identity; status colors also require a text or symbol label.
- Keep data surfaces opaque and readable. Native toolbar controls receive the
platform's material treatment; the inset sidebar uses regular Liquid Glass.
Related page actions use glass buttons inside a GlassEffectContainer.
Never layer glass on table rows or resource readings.
- Honor Reduce Transparency with an opaque sidebar. Older systems use regular
material and bordered controls. Resource meters show actual percentages,
not decorative or simulated activity.
- Retain macOS 14 support. Newer APIs require macOS availability guards.
- Shared geometry lives in `PuterLayout`: 20-point page inset, 16-point section
spacing, 8-point control spacing. Native control metrics take precedence.
## Shell and interaction
- One native toolbar sits above the content. The sidebar is inset eight points
below it, with one 16-point rounded navigation surface instead of a hard divider.
- The window uses a unified hidden-title toolbar with native traffic lights and
outer corners. A regular-material surround connects the toolbar to the inset,
opaque workspace. Launch, refresh, and update actions share a glass container.
Do not replace native window chrome with a custom draggable header.
- Compact and expanded navigation use the same List, row heights, and ordering.
Width changes are immediate; frequently updated process data is not animated.
- Each page retains its search while switching pages. An explicit "Go to details"
clears that destination's filter so it cannot hide the requested process.
- Window-local selection and search belong to ContentView. Shared telemetry
remains in the observable monitor; do not add a forwarding view-model layer.
- Appearance is System, Light, or Dark. System is the default.
- Resource summaries adapt to the available width; tables keep their user-sized
columns and horizontal scrolling. Search-empty and collecting states are explicit.
## Verification
Check both appearances, compact/expanded navigation, the inspector open/closed,
search-empty states, keyboard navigation, context menus, and sidebar toggles.
Check resizing and motion in the running app. A screenshot verifies the captured
layout, not frame rate. Do not claim animation performance without measuring it.