Skip to content

README.adoc

Latest commit

 

History

History
155 lines (118 loc) · 5.89 KB

README.adoc

File metadata and controls

155 lines (118 loc) · 5.89 KB

= UX Standards - E-Grade Launcher Specification :toc: :toclevels: 3

Overview

This directory contains UX standards for application launchers in the hyperpolymath ecosystem. The E-Grade Launcher Standard defines requirements for elite, efficient, elegant, and easy-to-use launchers.

E-Grade Principles

E-Grade launchers must adhere to these principles:

Elite

Only essential functionality, no bloat or unnecessary features

Efficient

Fast startup, minimal dependencies, optimized performance

Elegant

Clean code, proper error handling, consistent interface

Easy

Simple to use, clear feedback, intuitive operation

Self-Healing

Automatic recovery from common issues

Self-Diagnostic

Built-in troubleshooting and status reporting

Soft-Attach

Graceful degradation when dependencies are missing

Standard Launcher Templates

Two reference implementations are available:

  1. E-Grade Template: e-grade-launcher-template.sh - Original specification with elite/efficient/elegant/easy principles

  2. Comprehensive Template: comprehensive-launcher-template.sh - Full implementation with robust process management, error handling, and troubleshooting

Launchers should either:

  1. Use one of these templates with appropriate customization, or

  2. Implement equivalent functionality following the same patterns

For detailed implementation guidance, see Comprehensive Launcher Standard.

Dustfile Specification

When launchers fail, Dustfiles provide targeted, automated repair. See:

Dustfiles are self-diagnostic, self-healing scripts that: - Detect specific problems - Provide automated fixes - Integrate with feedback-o-tron for telemetry - Support exhausted users via Hypatia integration

Requirements for Desktop Launchers

NO Terminal Wrapping

Desktop launchers for GUI/web applications MUST NOT wrap commands in terminal emulators (konsole, gnome-terminal, etc.) unless: - The application is inherently a CLI tool - Terminal interaction is explicitly required - The user has opted into terminal mode

Rationale: Terminal wrapping causes "black window" syndrome and prevents proper browser launching.

Direct Execution

Desktop .desktop files must use direct execution:

Exec=/path/to/launcher.sh --mode
Terminal=false

NOT:

Exec=konsole -e /path/to/launcher.sh --mode
Terminal=true

Process Management

Launchers must properly manage background processes: - Use nohup to prevent process termination - Implement active waiting for server readiness - Provide clear feedback about process state - Clean up orphaned processes

Error Handling

Launchers must handle errors gracefully: - Catch and report browser launch failures - Provide manual fallback instructions - Log errors to predictable locations - Never silently fail

User Feedback

Launchers must provide clear, actionable feedback: - Success: "Server started at URL" - Waiting: "Waiting for server…​" - Failure: "Failed to start - check log at PATH" - Action: "Please manually open: URL"

Implementation Checklist

[ ] Remove all konsole/terminal wrapping from desktop files [ ] Set Terminal=false for GUI/web applications [ ] Implement nohup for background processes [ ] Add wait_for_server() function with timeout [ ] Implement run_diagnostics() function [ ] Add proper error handling for browser launching [ ] Provide clear user feedback at each step [ ] Log to predictable locations (/tmp/app-name.log) [ ] Handle missing dependencies gracefully [ ] Provide manual fallback instructions

Compliance

All new launchers must comply with this standard. Existing launchers should be migrated to E-Grade compliance as part of regular maintenance.

Feedback Integration

E-Grade launchers should integrate with the feedback-o-tron system for: - Automatic error reporting - Usage analytics (opt-in) - User satisfaction metrics - Continuous improvement loops

Complete Standards Suite

This UX standards directory provides a comprehensive suite:

Core Standards: - Comprehensive Launcher Standard - Main launcher specification - Dustfile Specification - Automated repair standard - LM/LA Lifecycle Standard - Complete lifecycle management - Face Identity Kit Standard - Naming and community-home design standard for language faces - CappauScripto Face Identity Card - CoffeeScript-facing face identity card (draft) - CappauScripto Release Gate Tracker - Launch readiness tracker with tests/fixtures/bench gates - CappauScripto Compatibility Matrix - CoffeeScript idiom support matrix - CappauScripto Migration Spec - cappa migrate transform and warning contract

Templates: - E-Grade Template - Minimal launcher - Comprehensive Template - Full-featured launcher - Dustfile Template - Automated repair script

Integration: - Integrity Verifier - Tamper-proof hash checking

Related Standards