fix(macos): stabilize startup and contrast; correct developer docs - #75
Merged
Conversation
Contributor
There was a problem hiding this comment.
🔵 Needs a closer look
It makes substantial macOS startup/subprocess and UI sizing/contrast changes that should be validated via real fresh-machine and interaction/accessibility checks beyond the added fixture/unit tests.
Pull request overview
This PR focuses on improving the macOS menubar app’s first-run reliability and UI contrast/behavior, while also updating developer-facing documentation to reflect the current published package surfaces and licensing model.
Changes:
- Fix macOS daemon bootstrap by resolving paired Node/npx installations, launching the version-matched
@sriinnu/drishtidaemon directly, and bounding subprocess output/timeouts. - Stabilize popover layout (content-sized + scroll-capped) and improve theme contrast handling (explicit theme-derived status ink; refreshed Glass visuals).
- Rewrite/root and package READMEs + SKILL docs to reflect the two published npm packages, correct commands/imports, and update licensing references; include additional materials in source archives.
File summaries
| File | Description |
|---|---|
| SKILL.md | Updates canonical published packages and integration guidance; adds license note. |
| scripts/prepare-license-materials.py | Includes SKILL docs and synthetic snapshot fixture in packaged source materials. |
| README.md | Rewrites root README around developer setup, surfaces, runtime behavior, and licensing. |
| packages/web/SKILL.md | Clarifies web is a private workspace app; adds license reference. |
| packages/web/README.md | Updates web dashboard setup instructions and license statement. |
| packages/tui/SKILL.md | Marks TUI as private workspace package; updates usage command; adds license reference. |
| packages/tui/README.md | Updates TUI readme to private-workspace guidance and AGPL notice. |
| packages/tokmeter/README.md | Refreshes package README positioning; updates license statement. |
| packages/mcp/SKILL.md | Updates Drishti tool list/docs; adds license note. |
| packages/mcp/README.md | Updates Drishti README to current commands/tooling and license statement. |
| packages/macos-bar/Tests/TokmeterBarTests/ThemeContrastTests.swift | Adds native-host contrast and “status ink independence” tests + widget pixel assertions. |
| packages/macos-bar/Tests/TokmeterBarTests/StartupTests.swift | Adds tests for daemon arguments, NodeToolchain selection, subprocess bounds, and error-state handling. |
| packages/macos-bar/Tests/TokmeterBarTests/StartupRenderTests.swift | Adds fixture render for actionable startup error UI. |
| packages/macos-bar/Tests/TokmeterBarTests/PopoverLayoutTests.swift | Adds regression tests for first-layout, resizing, and scroll-capping behavior. |
| packages/macos-bar/Tests/TokmeterBarTests/DemoRenderTests.swift | Adds opt-in theme review rendering across themes and disclosure states. |
| packages/macos-bar/Sources/TokmeterBar/UsageOverview.swift | Makes Usage details externally bindable and turns the full row into a single toggle button. |
| packages/macos-bar/Sources/TokmeterBar/UpdaterController.swift | Allows disabling Sparkle auto-start for tests/fixtures. |
| packages/macos-bar/Sources/TokmeterBar/TokmeterLoader+CLIFallback.swift | Switches daemon bootstrap to Drishti + toolchain resolution; improves error handling; uses bounded subprocess runner. |
| packages/macos-bar/Sources/TokmeterBar/TokmeterLoader.swift | Adds node-setup state + adjusts failure handling to keep protocol errors visible. |
| packages/macos-bar/Sources/TokmeterBar/TokmeterBarView.swift | Implements content-sized popover with height budgeting and integrates ConnectionIssueView. |
| packages/macos-bar/Sources/TokmeterBar/ThemePalettes.swift | Updates Glass palette values. |
| packages/macos-bar/Sources/TokmeterBar/Theme+Modes.swift | Adjusts Glass surface/tint and marks Glass as light for text inversion. |
| packages/macos-bar/Sources/TokmeterBar/Theme.swift | Replaces global status colors with theme-derived status ink; removes Noise from picker. |
| packages/macos-bar/Sources/TokmeterBar/SubprocessRunner.swift | Adds non-deadlocking subprocess runner with bounded stdout/stderr and timeouts. |
| packages/macos-bar/Sources/TokmeterBar/StatCards.swift | Makes delta/status colors theme-derived and adapts delta pill background for light themes. |
| packages/macos-bar/Sources/TokmeterBar/SignalsRibbon.swift | Allows chips to wrap using a custom flow layout; switches status colors to theme-derived ink. |
| packages/macos-bar/Sources/TokmeterBar/PanelVisibility.swift | Tracks screen height and reacts to screen/parameter changes for better popover sizing. |
| packages/macos-bar/Sources/TokmeterBar/NodeToolchain.swift | Adds paired Node/npx discovery across common managed/system installations + env composition. |
| packages/macos-bar/Sources/TokmeterBar/HubView.swift | Forces explicit SwiftUI color scheme based on theme; updates Glass backgrounds. |
| packages/macos-bar/Sources/TokmeterBar/HubSidebar.swift | Switches status colors to theme-derived ink and adjusts material sidebar background. |
| packages/macos-bar/Sources/TokmeterBar/HubPulseCard.swift | Switches semantic colors to theme-derived status ink. |
| packages/macos-bar/Sources/TokmeterBar/HubCrossToolCard.swift | Switches delta coloring to theme-derived status ink. |
| packages/macos-bar/Sources/TokmeterBar/HubCard.swift | Uses frosted glass panels for material themes. |
| packages/macos-bar/Sources/TokmeterBar/HeroHeader.swift | Updates Glass ink/shadows/notch behavior; switches status coloring to theme-derived ink. |
| packages/macos-bar/Sources/TokmeterBar/HeroBackground.swift | Simplifies Glass header treatment to align with shared frosted background. |
| packages/macos-bar/Sources/TokmeterBar/FrostedGlass.swift | Adds shared native blur background + panel components with reduce-transparency fallback. |
| packages/macos-bar/Sources/TokmeterBar/FooterBar.swift | Reworks footer hierarchy (app details vs pricing status) and uses theme-derived status ink. |
| packages/macos-bar/Sources/TokmeterBar/DataSections.swift | Improves light-theme legibility for model cost tints; uses frosted glass panels. |
| packages/macos-bar/Sources/TokmeterBar/ContextTelemetryPanel.swift | Switches warning/success/danger colors to theme-derived status ink. |
| packages/macos-bar/Sources/TokmeterBar/ContentSizedScrollView.swift | Adds scroll view that shrinks/grows with disclosure content while capping height. |
| packages/macos-bar/Sources/TokmeterBar/ConnectionIssueView.swift | Adds actionable error UI with Install Node and Retry controls. |
| packages/macos-bar/Sources/TokmeterBar/CompositionFill.swift | Uses theme-derived status ink for cacheRead tier color. |
| packages/macos-bar/Sources/TokmeterBar/CardBackground.swift | Uses frosted glass panel for glass-frost cards. |
| packages/macos-bar/Sources/TokmeterBar/AnomalyDetail.swift | Converts repricing pill to a native button; uses theme-derived status ink. |
| packages/macos-bar/README.md | Updates macOS app docs for startup behavior, themes, testing, and release pipeline. |
| packages/core/SKILL.md | Marks core as private workspace package; updates import guidance and license note. |
| packages/core/README.md | Updates core README for public package usage and MPL license statement. |
| packages/cli/SKILL.md | Marks CLI as private workspace package; adds AGPL license note. |
| packages/cli/README.md | Updates CLI README for @sriinnu/tokmeter usage and AGPL license statement. |
| docs/macos/popover-usability.md | Records popover sizing/theme/contrast validation evidence and remaining acceptance gaps. |
| docs/macos/first-use.md | Documents MAC-01 reproduction, fix approach, and remaining fresh-machine acceptance steps. |
| docs/macos-completion.md | Adds/updates macOS completion tracker and evidence/closure rules. |
| docs/licensing.md | Updates wording and included-materials list (skills + fixtures) for source archives. |
| docs/consuming-tokmeter.md | Updates integration guidance to @sriinnu/tokmeter + /cli subpath and license note. |
Review details
- Files reviewed: 54/54 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| PricingAnomaly(ts: 0, key: "sample-model-\($0)", field: "input", side: "increase", | ||
| previous: 1, current: 2, deltaPct: 100) | ||
| }, total: 5, cappedAt: 100) | ||
| let preferences = try XCTUnwrap(UserDefaults(suiteName: "TokmeterPopoverLayoutTests")) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fresh macOS installations could fail to start the usage daemon because the app invoked the CLI package, which imports an absent Drishti package. Start the version-matched Drishti package directly, discover paired Node/npx installations, and show actionable startup errors. Bound subprocess output and timeouts so installation cannot deadlock on full pipes.
Make the popup fit collapsed content, scroll within the screen-height budget, and expose the entire Usage details row as a button. Rework Glass with native light frost, explicit theme-based status ink, and clearer footer controls. Retire Noise from the picker while preserving persisted theme values. Native dark-host pixel checks cover the contrast mismatch that preview-only tests missed; the user accepted installed local build 46.6.
Rewrite the root README around developer setup, APIs, runtime behavior, limitations, and verification. Remove promotional package intros. Audit every README and SKILL.md against package manifests and source exports. Correct stale MIT labels, private-package install commands, helper imports, MCP tool names, and macOS distribution instructions. Include integration skills and the native synthetic test fixture in packaged source archives. Application licensing remains AGPL-3.0-only; core source remains MPL-2.0.
Validation:
The six-area macOS completion tracker remains open for fresh-machine acceptance, sustained reliability, a real Sparkle upgrade, independent accounting, broader keyboard/VoiceOver usability, and the five-person trial. This PR saves the implementation and documentation work; it does not publish a new release or close those acceptance gates.