Skip to content

UX redesign: persistent shell, sensible defaults and effortless installation #17

Open

Description

@Anheledir

Backlog and execution order: #58.

Current delivery tracking — 2026-10-26

Priority: P1. This is the UX specification/umbrella; implementation is split below.

Implemented: default-phone resolution (#20), persistent session/readable exports (#21), single-file/per-user install/PATH (#22), persistent output/brightness/profile/shell and Home/form recovery (#24). Beta.1 and beta.2 were published by the maintainer on 2026-10-26; beta.2 passed their local retest. #24 changes are newer than beta.2.

Remaining: first-run setup #31 (P1), responsive frame/live overview #32 (P1), guided managed-hook repair #30 (P1), remaining journeys/editor parity #33 (P2), inline delivery/preview recovery #34 (P2), actual terminal acceptance #7. Measured startup/size work is #25 (P1), with AOT/trimming research #26 (P2).

Settings/session history contains no push tokens. Existing checkboxes below mark automated implementation evidence, not all-platform physical/user certification. The detailed original design remains the reference.

Original UX specification follows; current implementation and remaining work are summarized above.

Goal

Make SidePulse.NET feel like a small, polished everyday companion: open it, see what is connected, do something useful, keep going. The current feature set works, but navigating it feels like assembling command-line arguments through a series of dialogs.

This is a design and delivery umbrella issue, with an implementable concept and acceptance criteria. Priority: P1 usability and adoption, before expanding the menu-driven feature surface.

Related: #7 terminal experience, #8 defaults/aliases/diagnostics, #4 pairing, #5 host, #10 distribution/updater, #16 OpenCode. This concept becomes the coordinating UX specification; existing issues retain their implementation and validation work.

User feedback and observed causes

The Windows preview has been tested with real iPhone pairing, state delivery and persisted pairing across CLI restarts. Its functional foundation is useful. The friction is in repeated everyday use:

  • Too many sequential menus and repeated questions about preview/dry-run, targets, executable paths, and run/copy choices.
  • Returning/backing out can end the process. Completing a command ends the interactive experience, requiring another launch.
  • Changing alignment, independently printed panels and disappearing/reappearing prompts make the interface feel unstable.
  • Script commands quote every word, obscuring simple commands.
  • A saved default phone is not used automatically when a state command has no explicit target and no USB device.
  • Downloading involves nested platform archives and hundreds of runtime/support files. Integrations can reference the executable inside Downloads, leaving the user to invent an installation and cleanup procedure.

Verified in the implementation reviewed for this concept:

  • Interactive.Resolve builds and returns one argument array; Program.cs then executes one command and terminates. It is not a persistent application session.
  • Interactive.Build/Review/Target repeatedly collect shared choices. Review adds another Run/Copy/Choose shell decision.
  • TerminalMode.Quote always quotes values, including command names and options.
  • Delivery.Send checks explicit phone/token flags, otherwise follows USB resolution. It does not consult the saved default phone for implicit delivery.
  • CI publishes self-contained directory distributions. Self-contained currently does not mean single-file.

Do not treat prior menu implementation checkboxes as evidence that these usability problems are solved.

1. Product character and interaction model

Calm, recognizable, fast, discoverable. Keep the restrained SidePulse identity, small LED motif and cyan accent. Borrow the useful qualities of Copilot/OpenCode-style terminal tools: a persistent session, predictable command entry, clear context, and unobtrusive help. Do not introduce an AI chatbot or a wall of decorative widgets.

Two deliberately different modes share the same application services:

Entry Experience
spn in an interactive terminal Persistent shell: home, navigation, command palette, inline results and settings
An explicit command, e.g. spn state working Executes once and exits, with concise output
Redirected streams, hooks, --quiet, --json, --no-interactive Never enter the shell or wait for input

Opening an interactive command group may open that section of the shell. Explicit commands remain one-shot; #18 intentionally removes the old executable name.

Home and information architecture

Home shows only what helps the next action:

  • Selected output: friendly name, transport, Dot/Pro model and why it was selected.
  • Host: running/stopped, aggregate agent state, active sessions.
  • Recent operation: meaningful result and time.
  • A compact action list: Send state, Animations, Devices & phones, Agents & host, Settings, Help & about.
  • Searchable command palette available from every normal screen.

Profiles belong with animations; installation, updates and diagnostics are accessible from Settings and the palette. Avoid a growing root menu with every internal subsystem as a peer.

No automatic network checks, device tests or state sends just for opening Home.

Navigation contract

  • Maintain a navigation stack, selected row, scroll position and in-progress form values.
  • Enter activates the focused primary action. Arrow keys navigate; Tab/Shift+Tab move between controls where appropriate.
  • Esc cancels the current edit/dialog or moves back exactly one level. It never exits the process as a side effect of ordinary navigation.
  • At Home, Esc has no exit side effect. Explicit Quit//quit exits; contextual shortcut hints explain this.
  • / opens a searchable action palette with actions such as /state, /animations, /devices, /agents, /settings, /help, /quit.
  • Ctrl+C cancels the current operation and returns control to the shell. When idle it can exit cleanly. Closing the UI does not implicitly stop the detached host.
  • Successful actions and recoverable failures return to the same context. No “press any key” after every operation.
  • Edits have Save/Cancel; cancel preserves previously saved values. Prompt cancellation does not discard unrelated form fields.
  • View-only pages and command results do not open a mandatory Run/Copy gate.

2. Visual layout and Spectre.Console direction

Use one consistent, responsive frame:

Region Content and behavior
Header Small product mark/version, section breadcrumb; consistent position and height
Context strip Output alias/model, host status, Live/Preview mode, only relevant warnings
Main workspace Current selection, concise form, preview or result; aligned left using shared padding and column rules
Activity/result region Bounded recent events; newest result stays visible without pushing navigation away
Footer Contextual keys and one script-command line when applicable; stable position within the application frame

Design first at 100×30, accept 80×24, and provide a single-column compact layout at 60×20. Collapse secondary panels and truncate decorative text before hiding primary controls or errors. Long aliases, Unicode and paths wrap or ellipsize predictably, with a detail view for full values.

Use Spectre Layout, Grid, Rows, Panel and Table composition deliberately. Use Canvas/LED cells for Dot/Pro previews; reserve Progress/Status for real work, not decoration. Prefer subtle boundaries over a panel around every sentence. No oversized ASCII banner, gratuitous chart, random centering, constant clearing or celebratory animation after every click.

Use restrained semantic colors plus text: cyan focus/activity, amber attention/preview, red failure, green completion. Color is never the only signal. Respect NO_COLOR, terminal background, reduced motion, Unicode/ASCII capabilities and narrow terminals.

Rendering architecture matters: one component owns input and terminal rendering. Background events update a view model; they never write directly over the UI. Spectre documents that live displays cannot run concurrently with prompts/progress/status displays. Do not build a permanent Live frame and nest independent Spectre prompts inside it. Prototype either a single custom input/render loop using Spectre renderables or coordinated pause/resume of rendering. Choose based on keyboard behavior, accessibility and flicker tests. Alternate-screen behavior, if used, must restore the cursor and original screen on normal exit, cancellation and failure.

3. Remove repeated questions and make Preview useful

A screen is an action workspace, not a questionnaire. For Send state, show the state choices, selected output, model/profile/brightness and optional LED simulation together. Use current settings immediately; allow editing inline.

Example interaction:

  1. Home → Send state.
  2. Choose Working; the command footer updates.
  3. Enter on Send Working sends once.
  4. Show “Working sent to Ned’s iPhone · bridge accepted” and remain in Send state.

After opening this screen, another state can be sent with selection + Enter. No target wizard, “dry run?”, or “Run or copy?” repeats.

  • Preview is a first-class secondary action, accessible from the action screen and palette. It shows the LED pattern or exact planned configuration changes.
  • Preview does not send, write provider configuration, install hooks, start a host, change defaults or silently turn into Apply.
  • Applying from a preview is a clearly labeled separate action, without re-answering the form.
  • Normal low-impact actions execute directly with a visible target. Mutating setup/update/removal screens show one relevant change summary and one explicit Apply/Install/Remove action, rather than several generic confirmations.
  • Keep unavoidable confirmations focused on irreversible loss or meaningful external/system changes. Do not introduce safety-dialog loops.
  • A configurable interactive Preview mode may exist, but is prominently visible while active and in results. It never silently affects explicit CLI commands, scripts or hooks; --dry-run keeps its explicit CLI meaning.
  • Clipboard/export are secondary shortcuts or an overflow menu, not mandatory decisions in the main action path.
  • Animation preview/edit keeps the chosen model, pattern and brightness when moving between preview, editing and sending.

4. Centralized settings and first-run setup

Settings groups:

  • Output: preferred target or Auto policy, default phone, model, brightness, profile.
  • Interaction: Live/Preview mode for the shell, command footer visibility, preferred export shell, reduced motion, color/accessibility.
  • Agents & background operation: installed integrations, managed executable path, host target/status and optional startup behavior.
  • Installation & updates: installed/portable mode, location, version/channel, update check/install, repair and uninstall.
  • Advanced: configuration/data/log paths, diagnostics and explicit overrides.

Use safe persisted non-secret settings separate from the existing protected phone credentials. Show effective value and source where useful: application setting, command-line override or automatic resolution. Write settings atomically with a versioned schema; preserve unknown fields when migrating where feasible.

Do not persist arbitrary command flags or a last-used secret as a global preference. Raw tokens remain in protected storage or explicit environment variables, never the ordinary settings file, history, command footer or diagnostics.

First run is short and skippable:

  1. Offer Install for this user or Continue portable, with location and consequences.
  2. Choose an output by discovering USB devices or pairing a phone; show aliases, not a request to type a known alias.
  3. Offer one explicit test and optional agent integration.
  4. Land on Home. Show incomplete setup as actionable empty states rather than rerunning onboarding at every launch.

Settings are editable later without repeating onboarding.

5. Sensible, shared output resolution

Use one resolver for state/write/animation delivery, shell actions, host startup and diagnostics. Selecting an explicit CLI target always overrides defaults.

Proposed deterministic policy:

Priority Resolution
1 Explicit --device, --phone or --token-env; validate conflicts as today
2 Explicitly saved application preferred output, including a chosen default phone
3 Auto policy: exactly one suitable mounted USB/SD device
4 If no single USB target was selected, use the designated saved default phone
5 Otherwise use the only saved phone, if there is exactly one
6 If unresolved, offer a target picker/setup action in the shell; explicit noninteractive commands return a short actionable error

Make the policy visible and configurable in Output settings. On phone pairing, offer “Use as default output” once; a first paired phone should be the convenient default when no other preference exists.

Required scenario: after pairing a default phone, unplug USB and run spn state working. It uses that phone without requiring --phone default. Display “Sent Working → Ned’s iPhone (default)” or the corresponding JSON receipt.

An explicit or saved preferred target that fails must not silently redirect a send to another device. Distinguish initial default resolution from fallback after a failure. Ambiguity without an applicable preference must not be resolved by filesystem order. Do not broadcast to all devices.

Dry-run can show an unresolved target and the selection policy without requiring a live device or transmitting anything. A receipt distinguishes “program validated”, “USB file written” and “bridge accepted”; it never claims a physical LED display acknowledgement that the transport cannot provide.

6. Script command footer that teaches without noise

Keep the original useful idea: building an action visually also shows how to script it. Improve its presentation:

  • Ordinary tokens remain unquoted: spn state working --phone default.
  • Quote only when the selected shell needs it, using a conservative shell-specific formatter. Spaces, apostrophes, metacharacters, empty arguments, Unicode and Windows trailing backslashes must round-trip correctly.
  • PowerShell executable paths that need quoting use the proper invocation syntax, including & where required. Do not make cosmetic changes that weaken escaping.
  • Use the selected export shell from Settings; do not ask for it during each operation.
  • The displayed and copied command are identical. Copy produces unobtrusive inline feedback.
  • By default the footer gives a complete explicit command for the resolved action, including target/model/profile/brightness where needed to reproduce it independently of local defaults. A shorter “use my defaults” variant can be selected in command details.
  • Show portable spn when available on PATH; otherwise render a correct invocation of the stable installed executable or the portable executable. Never pretend a PATH command exists when it does not.
  • Long commands stay one logical line in clipboard/export. The visual footer may wrap or truncate with an expansion action; it must not destabilize the frame.
  • Never expose protected push tokens. Use aliases or environment variable names. Do not store secret-bearing command text in history.
  • Advanced command details are one shortcut away; beginner screens do not display internal wrapper/IPC details.

7. Distribution and installation are part of UX

Users should download the correct build and run it, not maintain a .NET publish directory.

Download experience

  • Offer an obvious Windows x64 download, separately labeled Windows ARM64, macOS and Linux assets.
  • Remove nested “artifact ZIP → architecture ZIP → runtime directory” from the normal release path.
  • Target a self-contained single executable per OS/architecture as the primary portable experience. Prototype .NET single-file publishing with native-library extraction where required; measure startup and test all dependencies. Native AOT is an investigation, not a promised prerequisite.
  • Embed offline documentation/licenses where practical; preserve full attribution and accessible license commands. Keep debug symbols/developer artifacts separate.
  • Single-file distribution can still extract runtime components internally or use a small installed metadata file. The user-facing goal is one executable to download/manage, not an unsupported promise of zero files ever written.
  • Retain a directory package only as an explicitly labeled compatibility/developer option if needed.

Stable managed installation

Provide an explicit per-user install action from first run and CLI, with no default administrator requirement.

  • Windows proposal: executable under %LOCALAPPDATA%\Programs\SidePulse.NET; separate configuration/state/cache/log directories. Use appropriate user-owned paths on macOS/Linux.
  • Offer a user PATH entry and shortcut as explicit installation options; explain if a new terminal is needed. Never modify machine PATH by default.
  • Install before registering hooks, or offer that as the primary inline choice when launched from Downloads. Show the exact stable executable location.
  • Portable mode remains supported. Clearly explain that moving/removing the portable executable affects hooks, and offer Install/Repair rather than repeatedly asking for an executable path.
  • No ordinary workflow registers hooks to a disposable updater staging, extraction or temporary directory.
  • Upgrades keep a stable launch path and host configuration; hooks do not need manual path editing after every version.
  • Existing hooks pointing to Downloads require a reviewable repair/migration: show old/new paths and affected providers, back up configurations, preserve unrelated entries and refuse overwriting user edits.
  • Never delete a user’s Downloads folder or arbitrary source archive automatically. Offer scoped cleanup only for application-owned staging/cache files and explicitly identified old installation files.
  • Install/update/uninstall must work with single-file bundles: adapt package manifests, copied helper, startup probe, host stop/restart and rollback. Test Windows locked-executable replacement and interrupted updates.
  • Uninstall removes only owned binaries/PATH/shortcut/integration entries, with a separate choice for retained user settings and credentials. Removing the shell must not silently destroy a phone link.

install, uninstall and settings are implemented in #22/#24. Guided repair is tracked in #30.

8. Feedback, recovery and scripting quality

  • Empty states explain the next useful action: “No output selected. Pair a phone or connect SidePulse.” Offer actions in place.
  • Connection errors identify the target and offer Retry, Change output and Diagnostics, without restarting the app or rebuilding the form.
  • Integration screens show installed/not installed/modified/unavailable states and default to the stable installation path.
  • Network operations are cancellable and have bounded progress feedback. Do not show spinners for instant local actions.
  • Keep a compact activity history and expandable details. Do not pollute normal screens with stack traces, raw JSON or repetitive “Sent” lines.
  • The shell must reuse typed application services/results rather than spawning the CLI and parsing decorated stdout.
  • Direct CLI/hook behavior remains concise, deterministic and documented. JSON uses stable machine fields, no menus/ANSI/progress; errors go to stderr and use nonzero exit codes. Quiet successful commands stay silent.
  • Default resolution works consistently in scripts; ambiguous noninteractive commands fail promptly. Generated explicit commands remain the escape hatch from machine-local defaults.

Delivery tracking

9. Delivery plan

  1. Interaction/layout prototype: persistent navigation, home and Send state using fixture data; validate keyboard/back/cancel, narrow screens and frame stability before rewriting every feature.
  2. Shared settings and target resolver: effective preferences, default phone behavior, interactive selection and deterministic script behavior.
  3. Migrate core journeys: send state, animation preview/apply, pairing, agent install/status/remove, host management, updates and help. Remove repeated review/dry-run prompts.
  4. Packaging/install spike in parallel with UX work: validate single-file dependencies and stable-path installation; update/rollback design must be proven before replacing published packages.
  5. Installation and hook migration: per-user install, PATH option, repair existing paths, portable mode and cleanup behavior.
  6. Usability and release acceptance: real Windows/iPhone/agent sessions, native platform checks, updated wiki and screenshots demonstrating actual behavior.

Split into linked implementation issues with one owner and acceptance slice each. Do not close #7, #8 or #10 simply because this concept exists.

10. Definition of done

  • From one process launch, perform ten actions across three sections, go back repeatedly, and recover from a failed send without leaving the shell (Prepare spn beta with persistent sessions and verified release drafts #21 native Unix PTY smoke).
  • Once configured, sending another state requires selecting it and activating Send; no repeated target, dry-run, executable-path or Run/Copy questions.
  • Esc/back/cancel behavior is consistent at every level; only explicit quit or idle Ctrl+C exits. Detached host remains running unless explicitly stopped.
  • Footer/header/selection remain aligned and usable at 100×30, 80×24 and 60×20; resize during prompts, preview and errors causes no overlapping output.
  • No competing Live/prompt/progress renderers; no host/background logs overwrite the interactive frame; terminal/cursor state restores after errors.
  • Settings persist across launches; overrides and effective defaults are understandable; secrets are excluded from settings/history/footer.
  • Paired default phone + no USB + state working works without explicit target flags (Use the default phone when no USB device is mounted #20; automatic resolution and native CI).
  • Explicit target failure never sends to another target; ambiguous scripted invocation fails without waiting; dry-run requires no physical output.
  • Simple command footer has no unnecessary quotes. PowerShell/Bash/CMD quoting and copy/export round trips cover spaces, apostrophes, empty values, metacharacters, Unicode and trailing backslashes.
  • One preview action is enough; preview has no delivery/configuration side effects; Apply uses the same reviewed values.
  • A fresh Windows user can download, start, install per-user, pair a phone and send the first state without manually moving runtime files or editing hooks.
  • After deleting the original download directory, installed CLI and hooks still work.
  • Single-file startup, offline docs/licenses, native credential protection and updater rollback pass on supported platforms/architectures; any runtime extraction requirement is documented.
  • Upgrade preserves settings/phone links/stable hook paths; interrupted update recovers; uninstall preserves user data unless its deletion was explicitly chosen.
  • Existing one-shot scripts, quiet/JSON/no-color/noninteractive behavior and silent hooks remain compatible.
  • Test with actual Windows Terminal keyboard/clipboard, narrow/no-color/reduced-motion operation, macOS/Linux terminals, and real provider sessions. Snapshot tests are supplemented by resize/cancellation/navigation behavior tests and observed usability sessions.

Usability target: an existing user opens the app and sends a state in under 10 seconds without searching documentation or answering setup questions. First-run timing should distinguish user navigation time from phone/network delays. Measure actual task completion and errors, not only visual polish.

References and boundaries

This is a proposed design, not a claim that these behaviors already exist. Confirm feasibility through the prototype and native acceptance evidence; use Spectre’s strengths without turning every feature into a decorative dashboard.

Beta implementation (#21): persistent session/Home, section return after commands, searchable action palette and repeatable Send state with session-local output/Preview choice are implemented. Native Windows/Linux/macOS CI passed; Unix PTY acceptance performs ten actions across three sections, Home Esc, palette search, failed-send recovery and 60×20 preview. Saved settings and shell-form cancellation are implemented in #24; responsive layout (#32) and specialized-editor parity (#33) remain open. Merged in #21; 125 .NET tests and nine tooling/release tests pass.

Activity

  1. added
    enhancementNew feature or request
    P1Next delivery: usability, installation and release blockers
    on Oct 24, 2026
  2. Anheledir commented on Oct 26, 2026

    @Anheledir
    OwnerAuthor

    Next implementation slice: #23 / PR #24 persists output, brightness, profile/model and export shell; shares defaults with CLI/host/animation commands; adds Home context and shell-form/action-palette Esc/Ctrl+C recovery with retained input.

    The user reports beta.1 and beta.2 are now published, and beta.2 passed their local retest. This slice builds on that acceptance. Full responsive dashboard, advanced editor controls, guided hook repair and actual Windows Terminal acceptance for the new shell changes remain open.

  3. Anheledir commented on Oct 26, 2026

    @Anheledir
    OwnerAuthor

    Implemented and merged in #24 (26f64b9). Preferred output, brightness, profile/model and export shell persist; Home shows defaults, host status and last action; shell forms/action palette support Esc/Ctrl+C recovery. 138 .NET tests, 10 tooling tests, native Windows/Linux/macOS CI, published single-file/install/update smoke and Quality/Security checks pass. #23 is closed; the remaining #17 acceptance and hook-repair work stay open.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1Next delivery: usability, installation and release blockersenhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions