Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,9 +85,13 @@ The single `http://<bind-host>:<port>/` URL a phone types into its browser to re
_Avoid_: connection URL, daemon URL

**Health issue**:
Something the daemon knows is wrong on the host that makes input fail silently, today a missing OS permission (macOS Accessibility). Reported by the platform backend, pushed to every client as a `health` frame (full list on change; an empty list means healthy), shown as a banner above the grid, and listed under `/diag`'s `health` block. Not the same as `GET /health` (host identity) or `focus.healthy` (is context switching working). See issue #195.
Something the daemon knows is wrong on the host that makes input fail silently, today a missing OS permission (macOS Accessibility, or Automation of System Events). Reported by the platform backend (from proactive checks plus refusals seen at action time, #196), pushed to every client as a `health` frame (full list on change; an empty list means healthy), shown as a banner above the grid, and listed under `/diag`'s `health` block. Not the same as `GET /health` (host identity) or `focus.healthy` (is context switching working). See issue #195. An action the OS refuses for the same cause also gets an **Action error**.
_Avoid_: warning, alert, permission error

**Action error**:
The daemon's reply to one session when the OS refused an action that session triggered, today a macOS key press blocked for want of Accessibility or Automation (`reason: "permission_denied"`). Sent as an `action_error` frame to the requesting session only, shown as a toast, recorded as `outcome="permission_denied"` in `/actions/recent` and `/metrics`. Its `issue_id` names the **Health issue** that carries the fix steps. See issue #196.
_Avoid_: permission error, failure toast

### Session screen state (issue #160)

**Screen locked**:
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Pre-alpha, but usable day-to-day. Here's what deckd can do today and what's stil
- [x] **Chrome media indicator** — the media icon sprouts a pulsing green dot whenever a media player is playing (passive playback indicator), independent of the browser view.
- [x] **Now playing** — control any supported media player (Spotify, Firefox, VLC, etc.) from a dedicated chrome view, with album art, per-player transport controls, and now-playing metadata.
- [x] **Session lock awareness** — when the desktop session locks, the phone swaps to a "Screen locked" takeover and the daemon refuses presses / injection / trackpad / window raising (`--allow-while-locked` opts out); a plain screen blank keeps input live so a press wakes the machine.
- [x] **Missing-permission warnings** — when an OS permission deckd needs is missing (today: macOS Accessibility), the phone shows a banner naming what won't work and how to fix it, and clears it by itself once you grant the permission.
- [x] **Missing-permission warnings** — when an OS permission deckd needs is missing (today: macOS Accessibility and Automation → System Events), the phone shows a banner naming what won't work and how to fix it, and clears it by itself once you grant the permission. A key press the OS refuses toasts straight away.
- [x] **Running programs list** — tap a deck-grid icon in the bottom chrome to open a list of every open window on the host, labeled by the deck the window would match. Tap a row to raise (focus) that window and close the list. Enumeration and raise are GNOME-only today (via the focus extension); other backends show the list's "unsupported on this platform" empty state.
- [x] **VLC media widgets** — full VLC control surface with play/pause, seek, volume, album art. Configurable art sources (VLC embedded art + iTunes fallback).
- [x] **Live sensor widgets** — meter and stats widgets pushed to the client in real time (CPU %, memory %, swap %, root disk %), bound to daemon-side sensor sources.
Expand Down
30 changes: 30 additions & 0 deletions client/src/ActionErrorToast.test.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
/** Toast for an action the OS refused (issue #196).
*
* The daemon answers a key press macOS blocked (missing Accessibility or
* Automation) with an ``action_error`` frame; the toast shows its message
* right away. The banner carries the fix steps, so the toast only says what
* happened and can be dismissed.
*/
import { cleanup, fireEvent, render, screen } from "@testing-library/react";
import { afterEach, describe, expect, it, vi } from "vitest";
import { ActionErrorToast } from "./ActionErrorToast";

afterEach(cleanup);

const MESSAGE = "Key press blocked: deckd.app needs Accessibility permission.";

describe("ActionErrorToast", () => {
it("shows the daemon's message in a polite live region", () => {
const { container } = render(<ActionErrorToast message={MESSAGE} onDismiss={() => {}} />);
expect(screen.getByText(MESSAGE)).toBeTruthy();
expect(container.querySelector('[aria-live="polite"]')).not.toBeNull();
});

it("offers Dismiss, and no Retry: a retry would be refused the same way", () => {
const onDismiss = vi.fn();
render(<ActionErrorToast message={MESSAGE} onDismiss={onDismiss} />);
expect(screen.queryByRole("button", { name: "Retry" })).toBeNull();
fireEvent.click(screen.getByRole("button", { name: "Dismiss" }));
expect(onDismiss).toHaveBeenCalledOnce();
});
});
26 changes: 26 additions & 0 deletions client/src/ActionErrorToast.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
/** Non-blocking toast for an action the OS refused (issue #196).
*
* The daemon answers a key press macOS blocked for want of a permission
* with an ``action_error`` frame; this shows its message straight away.
* The health banner, raised at the same time, carries the fix steps, so the
* toast only says what happened. No Retry: the OS would refuse it the same
* way until the grant lands. Shares the media toast's look and placement.
*/
export function ActionErrorToast({
message,
onDismiss,
}: {
message: string;
onDismiss: () => void;
}) {
return (
<div className="media-error-toast" aria-live="polite">
<span className="media-error-text">{message}</span>
<span className="media-error-actions">
<button className="media-error-btn" onClick={onDismiss}>
Dismiss
</button>
</span>
</div>
);
}
63 changes: 62 additions & 1 deletion client/src/App.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
*/
import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { ClientMessage, ServerChromeMedia, ServerDeck, ServerMediaError, ServerState } from "./protocol";
import type { ClientMessage, ServerChromeMedia, ServerDeck, ServerMediaError, ServerActionError, ServerState } from "./protocol";

/** Replace the real socket hook with a controllable fake. The chrome
* icon's job is to call ``send`` with the right message; the test
Expand All @@ -42,6 +42,7 @@ const cancelReconnect = vi.fn();
const retryNow = vi.fn();
let sessionStateHandler: ((m: ServerState) => void) | null = null;
let mediaErrorHandler: ((m: ServerMediaError) => void) | null = null;
let actionErrorHandler: ((m: ServerActionError) => void) | null = null;
vi.mock("./socket", () => ({
useDeckdSocket: (
deckCb: (m: ServerDeck) => void,
Expand All @@ -52,12 +53,15 @@ vi.mock("./socket", () => ({
_runningWindowsCb: unknown,
sessionStateCb: ((m: ServerState) => void) | undefined,
mediaErrorCb: ((m: ServerMediaError) => void) | undefined,
_healthCb: unknown,
actionErrorCb: ((m: ServerActionError) => void) | undefined,
_options: unknown,
) => {
onDeck.mockImplementation(deckCb);
chromeMediaHandler = chromeMediaCb ?? null;
sessionStateHandler = sessionStateCb ?? null;
mediaErrorHandler = mediaErrorCb ?? null;
actionErrorHandler = actionErrorCb ?? null;
return {
get status() {
return mockStatus;
Expand Down Expand Up @@ -1421,3 +1425,60 @@ describe("App — media error toast", () => {
expect(send.mock.calls.length).toBe(before);
});
});

/* -------------------------------------------------------------------------
* Action refused by the OS (issue #196): a key press macOS blocked for want
* of a permission toasts at once; a media failure after it takes its place.
* --------------------------------------------------------------------- */

describe("App — action error toast", () => {
afterEach(cleanup);
beforeEach(() => {
send.mockReset();
actionErrorHandler = null;
mediaErrorHandler = null;
mockStatus = "open";
window.history.replaceState(null, "", "/?demo=mpris");
});

const blocked: ServerActionError = {
type: "action_error",
id: "new-window",
reason: "permission_denied",
issue_id: "automation_system_events_missing",
message: "Key press blocked: deckd.app needs Automation permission to control System Events.",
};

it("shows the message and announces it", () => {
render(<App />);
act(() => actionErrorHandler?.(blocked));
expect(screen.getAllByText(blocked.message).length).toBeGreaterThan(0);
expect(screen.getByRole("status").textContent).toBe(blocked.message);
});

it("dismisses", () => {
render(<App />);
act(() => actionErrorHandler?.(blocked));
fireEvent.click(screen.getByRole("button", { name: "Dismiss" }));
expect(document.querySelector(".media-error-toast")).toBeNull();
});

it("the newer failure replaces the older toast", () => {
render(<App />);
act(() => actionErrorHandler?.(blocked));
act(() =>
mediaErrorHandler?.({
type: "media_error",
id: "mpris.vlc",
player: "VLC media player",
message: "player disappeared",
retryable: true,
}),
);
expect(document.querySelectorAll(".media-error-toast").length).toBe(1);
expect(screen.getByText(/player disappeared/)).toBeTruthy();
act(() => actionErrorHandler?.(blocked));
expect(document.querySelectorAll(".media-error-toast").length).toBe(1);
expect(screen.queryByText(/player disappeared/)).toBeNull();
});
});
29 changes: 28 additions & 1 deletion client/src/App.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ import type {
HealthIssue,
ServerHealth,
ServerMediaError,
ServerActionError,
ServerRunningWindows,
ServerState,
WindowListEntry,
Expand All @@ -53,6 +54,7 @@ import { ReflowHelp } from "./ReflowHelp";
import { ConfirmModal } from "./ConfirmModal";
import { ConnectionOverlay } from "./ConnectionOverlay";
import { MediaErrorToast } from "./MediaErrorToast";
import { ActionErrorToast } from "./ActionErrorToast";
import { HealthBanner } from "./HealthBanner";
import type { Widget, ConfirmRequestMessage, MediaCommandMessage } from "./protocol";
import { wireWindowsToServer } from "./protocol";
Expand Down Expand Up @@ -216,7 +218,18 @@ export function App() {
const lastMediaCommandRef = useRef<
Record<string, { command: MediaCommandMessage["command"]; value?: number }>
>({});
const onMediaError = useCallback((m: ServerMediaError) => setMediaError(m), []);
// Action refused by the OS (issue #196): a key press macOS blocked for
// want of Accessibility / Automation. Both toasts sit in the same spot,
// so the newer failure replaces the older one, whichever kind it is.
const [actionError, setActionError] = useState<ServerActionError | null>(null);
const onMediaError = useCallback((m: ServerMediaError) => {
setActionError(null);
setMediaError(m);
}, []);
const onActionError = useCallback((m: ServerActionError) => {
setMediaError(null);
setActionError(m);
}, []);
// Daemon health issues (issue #195): missing OS permissions that make
// input fail silently. The daemon pushes the full list on change, so
// the latest frame is the whole truth; empty means healthy.
Expand Down Expand Up @@ -272,6 +285,7 @@ export function App() {
onSessionState,
onMediaError,
onHealth,
onActionError,
{ enabled: !demoDeck && !isPlayground },
);
const playgroundSocket = usePlaygroundDaemon(
Expand Down Expand Up @@ -706,6 +720,11 @@ export function App() {
// eslint-disable-next-line react-hooks/set-state-in-effect
setLiveText(`Media error: ${mediaError.player || mediaError.id}`);
}, [mediaError]);
useEffect(() => {
if (!actionError) return;
// eslint-disable-next-line react-hooks/set-state-in-effect
setLiveText(actionError.message);
}, [actionError]);

// Chrome app-identity badge (ADR-0007): the daemon relays an
// optional ``display_name`` / ``theme`` / ``icon`` per deck; the
Expand Down Expand Up @@ -1190,6 +1209,14 @@ export function App() {
onDismiss={() => setMediaError(null)}
/>
) : null}
{/* Key press refused by the OS (issue #196). The health banner has
the fix steps; this says what just happened. */}
{actionError ? (
<ActionErrorToast
message={actionError.message}
onDismiss={() => setActionError(null)}
/>
) : null}
</>
);
}
24 changes: 24 additions & 0 deletions client/src/HealthBanner.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -40,3 +40,27 @@ export const Warning: Story = () => (
/>
</div>
);

/** The macOS Automation issue (#196), worded like
* ``deckd.platform_macos._automation_missing_issue`` for the packaged app. */
const AUTOMATION: HealthIssue = {
id: "automation_system_events_missing",
severity: "error",
title: "Automation permission missing",
detail:
"macOS isn't letting deckd.app control System Events, so key buttons do nothing and the deck may not follow the app in front.",
fix_steps: [
"On the Mac, open System Settings → Privacy & Security → Automation.",
"Under deckd.app, turn on System Events.",
"If deckd.app isn't listed, or System Events is already on, run `tccutil reset AppleEvents com.deckd.daemon` in Terminal, then click OK when macOS asks to let it control System Events.",
"This warning clears by itself a few seconds after the grant.",
],
affects: ["key", "focus"],
};

/** Both grants missing: one banner each, Accessibility first. */
export const BothMissing: Story = () => (
<div style={frame}>
<HealthBanner issues={[AX, AUTOMATION]} dismissed={new Set()} onDismiss={() => {}} />
</div>
);
7 changes: 7 additions & 0 deletions client/src/HealthBanner.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,13 @@ describe("HealthBanner", () => {
expect(screen.getAllByRole("listitem").length).toBe(2);
});

it("names the deck-following that a missing Automation grant breaks (issue #196)", () => {
render(<Harness issues={[{ ...AX, id: "automation_system_events_missing", affects: ["key", "focus"] }]} />);
const text = screen.getByRole("alert").textContent;
expect(text).toContain("key presses, switching decks with the app in front");
expect(text).not.toContain("focus");
});

it("falls back to the raw key for an unknown primitive", () => {
render(<Harness issues={[{ ...AX, affects: ["teleport"] }]} />);
expect(screen.getByRole("alert").textContent).toContain("teleport");
Expand Down
1 change: 1 addition & 0 deletions client/src/HealthBanner.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ const AFFECTS_LABELS: Record<string, string> = {
scroll: "scrolling",
key: "key presses",
raise_window: "raising windows from the list",
focus: "switching decks with the app in front",
};

function describeAffects(affects: string[]): string {
Expand Down
36 changes: 31 additions & 5 deletions client/src/protocol.generated.ts
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,32 @@ export type MediaErrorMessage = {
retryable?: boolean;
};

/**
* Daemon -> client push: an action this session triggered was refused
* by the OS (issue #196).
*
* Sent only to the *requesting* session, like ``media_error``: the
* failure is a consequence of one session's press. Today the one
* ``reason`` is ``permission_denied`` (macOS refused the keystroke for
* want of Accessibility or Automation); the client shows ``message``
* as a toast. ``issue_id`` names the :class:`HealthIssue` with the fix
* steps, which the daemon raises at the same time. ``id`` is the
* pressed widget's id, ``None`` for manual-control keys and typed text.
*
*/
export type ActionErrorMessage = {

type: "action_error";

id?: string | null;

reason: "permission_denied";

issue_id: string;

message: string;
};

/**
* Daemon -> client push: the chrome media icon's passive
* playback-state snapshot (issue #47).
Expand Down Expand Up @@ -465,13 +491,13 @@ export type RunningWindowsMessage = {
* One thing the daemon knows is broken on this host (issue #195).
*
* Platform-neutral: a backend mints these from whatever it can probe
* (macOS Accessibility trust today; Automation, Linux ``uinput`` access
* are follow-ups). ``id`` is a stable machine key (``accessibility_missing``)
* the client can dedupe and dismiss by. ``fix_steps`` are complete,
* (macOS Accessibility trust and Automation of System Events today;
* Linux ``uinput`` access is a follow-up). ``id`` is a stable machine
* key (``accessibility_missing``) the client can dedupe and dismiss by. ``fix_steps`` are complete,
* user-facing sentences that name the exact app to grant and the
* Settings path. ``affects`` lists the input primitives that silently
* fail while the issue stands (``pointer``, ``scroll``, ``key``,
* ``raise_window``, ...).
* ``raise_window``, ``focus``, ...).
*
*/
export type HealthIssue = {
Expand Down Expand Up @@ -509,7 +535,7 @@ export type HealthMessage = {
issues: HealthIssue[];
};

export type ServerMessage = DeckMessage | StateMessage | BrightnessMessage | WidgetUpdateMessage | MediaStateMessage | MediaErrorMessage | ChromeMediaMessage | EventMessage | MacroResultMessage | ConfirmRequestMessage | RunningWindowsMessage | HealthMessage | ErrorMessage;
export type ServerMessage = DeckMessage | StateMessage | BrightnessMessage | WidgetUpdateMessage | MediaStateMessage | MediaErrorMessage | ActionErrorMessage | ChromeMediaMessage | EventMessage | MacroResultMessage | ConfirmRequestMessage | RunningWindowsMessage | HealthMessage | ErrorMessage;

export type HelloMessage = {

Expand Down
3 changes: 3 additions & 0 deletions client/src/protocol.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ import type {
ChromeMediaMessage,
ErrorMessage,
MediaErrorMessage,
ActionErrorMessage,
MacroResultMessage,
ConfirmRequestMessage,
RunningWindowsMessage,
Expand Down Expand Up @@ -61,6 +62,7 @@ export type {
WidgetUpdateMessage,
MediaStateMessage,
MediaErrorMessage,
ActionErrorMessage,
ChromeMediaMessage,
EventMessage,
MacroResultMessage,
Expand Down Expand Up @@ -200,6 +202,7 @@ export type ServerWidgetUpdate = WidgetUpdateMessage;
export type ServerChromeMedia = ChromeMediaMessage;
export type ServerError = ErrorMessage;
export type ServerMediaError = MediaErrorMessage;
export type ServerActionError = ActionErrorMessage;
export type ServerMacroResult = MacroResultMessage;
export type ServerConfirmRequest = ConfirmRequestMessage;
export type ServerHealth = HealthMessage;
Expand Down
Loading
Loading