dsh-plugin-completion-notify 0.1.0

package/lib/index.js

@@ -0,0 +1,29 @@
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/completion-notify-settings.js
+/** Completion-notify preferences stored in the Host user-settings document. */
+/** Settings namespace owned by the completion-notify plugin. */
+const COMPLETION_NOTIFY_SETTINGS_NAMESPACE = "ui-completion-notify";
+/** Field carrying whether desktop completion notifications are enabled. */
+const COMPLETION_NOTIFY_ENABLED_FIELD = "enabled";
+/** Default when the user-settings document has no override: notifications on. */
+const DEFAULT_COMPLETION_NOTIFY_ENABLED = true;
+/** Durable completion-notify schema; also the wire envelope the browser scope validates against. */
+const CompletionNotifySettingsSchema = z.object({ [COMPLETION_NOTIFY_ENABLED_FIELD]: z.boolean().default(true) });
+//#endregion
+//#region lib/types/index.js
+/** Host registration for the completion-notify preference. */
+const NAMESPACE = settingsNamespace(COMPLETION_NOTIFY_SETTINGS_NAMESPACE);
+/**
+* Register the durable completion-notify section when the optional settings
+* service is composed. The browser half reads and writes the enabled flag
+* through the settings scope bound to this namespace.
+* @param ctx - Host context that may acquire the settings service.
+*/
+function apply(ctx) {
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.register(NAMESPACE, CompletionNotifySettingsSchema);
+	});
+}
+//#endregion
+export { COMPLETION_NOTIFY_ENABLED_FIELD, COMPLETION_NOTIFY_SETTINGS_NAMESPACE, DEFAULT_COMPLETION_NOTIFY_ENABLED, apply };

package/lib/types/client/CompletionNotifyRow.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Completion-notify preference row: an enable switch for desktop completion
+ * notifications, registered into the General section item slot. The row is
+ * a simple checkbox pair (title + description) whose state mirrors the
+ * settings-scope snapshot. Styles are inline (a standalone plugin avoids the
+ * harness's CSS Modules pipeline).
+ */
+import type { PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
+import type { createCompletionNotifyRowStore } from './settings-store.js';
+/** Injected business face: the preference write (t rides the standard locale seat). */
+export interface CompletionNotifyRowInjected {
+    /** Persist the desktop-notification enabled flag. */
+    setEnabled: (enabled: boolean) => void;
+}
+/** Full component props: runtime share + store share + locale seat + injected face. */
+export type CompletionNotifyRowComponentProps = PropsRuntime<'settings.general.item'> & PropsStore<ReturnType<typeof createCompletionNotifyRowStore>> & PropsLocale<'settings.completionNotify'> & CompletionNotifyRowInjected;
+/**
+ * Render the completion-notify enable switch row.
+ * @param props - composed slot props.
+ * @returns the row element tree.
+ */
+export declare function CompletionNotifyRow({ t, setEnabled, useStore }: CompletionNotifyRowComponentProps): import("react").JSX.Element;
+//# sourceMappingURL=CompletionNotifyRow.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Completion-notify surface plugin, browser half: raises a system desktop
+ * notification (browser Notification API) when a session completes while it
+ * is not the one the user is looking at. For a NON-selected session the
+ * completion marker already exists on the sessions list snapshot
+ * (`SessionListState.byId[id].completed`, armed by the runtime's
+ * `syncCompletedNotifications` for running→idle edges of non-selected
+ * sessions). For the SELECTED session — which the runtime never marks
+ * completed because the user is presumed to be watching it — this plugin
+ * detects the running→idle edge itself and raises the notification only
+ * while the page is in the background (`document.hidden`), i.e. when the
+ * user has switched away and would otherwise miss the completion.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type CompletionNotifyKey } from './locales.js';
+export { CompletionNotifyRow } from './CompletionNotifyRow.js';
+export type { CompletionNotifyRowInjected } from './CompletionNotifyRow.js';
+export type { CompletionNotifyKey } from './locales.js';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The completion-notify settings row and notification copy. */
+        'settings.completionNotify': CompletionNotifyKey;
+    }
+}
+/** Required services: the settings row slot, sessions list, locale, and the settings scope. */
+export declare const inject: string[];
+/**
+ * The browser Notification surface narrowed to what this plugin uses, so
+ * tests can stub it and non-browser environments degrade silently.
+ */
+export interface NotificationApi {
+    readonly permission: NotificationPermission;
+    requestPermission(): Promise<NotificationPermission>;
+    create(title: string, options?: {
+        body?: string;
+    }): unknown;
+}
+/**
+ * Resolve the browser Notification constructor, or undefined where absent
+ * (old browsers, restricted environments, non-browser test hosts). The
+ * returned surface adapts the constructor: `create` wraps `new
+ * Notification(title, options)`, because the native constructor carries no
+ * `create` method.
+ * @returns the Notification surface when available.
+ */
+export declare function browserNotification(): NotificationApi | undefined;
+/**
+ * Raise one completion notification through the browser Notification API.
+ * Permission must already be granted — requesting it here would run in a
+ * non-user-gesture context (a backgrounded completion), which browsers
+ * silently ignore; the first interaction and the settings switch request
+ * permission instead. Any missing grant stays silent.
+ * @param api - the browser Notification surface.
+ * @param title - the notification title.
+ * @param body - the notification body.
+ */
+export declare function notifyCompletion(api: NotificationApi, title: string, body: string): Promise<void>;
+/**
+ * Request the browser notification permission, meant to run inside a user
+ * gesture (the settings switch's click, or the first interaction). Browsers
+ * require transient user activation for `Notification.requestPermission` and
+ * silently ignore it otherwise.
+ * @param api - the browser Notification surface.
+ * @returns whether the permission is granted afterwards.
+ */
+export declare function requestNotificationPermission(api: NotificationApi): Promise<boolean>;
+/**
+ * Whether the page is currently in the background (hidden tab or minimized
+ * window). The selected session's completion is only notified while this is
+ * true — when the page is visible the user is watching the completion.
+ * @returns whether the document is hidden.
+ */
+export declare function pageIsHidden(): boolean;
+/**
+ * Client plugin body: subscribe to the sessions list snapshot and raise a
+ * desktop notification when a session completes — the non-selected session
+ * via its runtime `completed` marker, the selected session via its
+ * running→idle edge while the page is hidden — plus register the
+ * General-settings enable switch.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,18 @@
+/** `settings.completionNotify` namespace dictionaries (the settings row's and notification's copy). */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'row.title': string;
+    'row.desc': string;
+    'notification.title': string;
+    'notification.body': string;
+};
+/** The settings.completionNotify namespace key union. */
+export type CompletionNotifyKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'row.title': string;
+    'row.desc': string;
+    'notification.title': string;
+    'notification.body': string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/settings-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Completion-notify settings row slot store: a mirror of the settings-scope
+ * snapshot. The plugin's apply-world change listener is the only writer; the
+ * row component reads via props.useStore.
+ *
+ * The store is a local implementation of the ui-slots StoreHandle contract
+ * instead of the harness runtime's `defineStore` engine: the standalone
+ * plugin cannot import that engine (it is not part of the published npm
+ * client bundle), so this module provides the minimal snapshot-source +
+ * baked-actions shape the render machinery consumes.
+ */
+import type { StoreHandle } from '@deepseek-ai/dsh-client-ui-slots';
+/** Store state mirrored from the settings scope snapshot. */
+export interface CompletionNotifyRowState {
+    /** Whether desktop completion notifications are enabled. */
+    enabled: boolean;
+    /** Namespace revision; -1 until first sync so revision 0 lands as a change. */
+    revision: number;
+}
+/** Declared action shape giving the exported factory a stable return type. */
+type CompletionNotifyRowActions = {
+    sync: (draft: CompletionNotifyRowState, enabled: boolean, revision: number) => void;
+};
+/**
+ * Declares the completion-notify row state and write surface.
+ * @returns the store handle.
+ */
+export declare function createCompletionNotifyRowStore(): StoreHandle<CompletionNotifyRowState, CompletionNotifyRowActions>;
+export {};
+//# sourceMappingURL=settings-store.d.ts.map

package/lib/types/completion-notify-settings.d.ts

@@ -0,0 +1,16 @@
+/** Completion-notify preferences stored in the Host user-settings document. */
+import z from '@deepseek-ai/schemastery';
+/** Settings namespace owned by the completion-notify plugin. */
+export declare const COMPLETION_NOTIFY_SETTINGS_NAMESPACE = "ui-completion-notify";
+/** Field carrying whether desktop completion notifications are enabled. */
+export declare const COMPLETION_NOTIFY_ENABLED_FIELD = "enabled";
+/** Default when the user-settings document has no override: notifications on. */
+export declare const DEFAULT_COMPLETION_NOTIFY_ENABLED = true;
+/** Durable completion-notify section shared by the Host schema and the browser scope. */
+export interface CompletionNotifySettings {
+    /** Whether a non-selected session completion raises a desktop notification. */
+    enabled: boolean;
+}
+/** Durable completion-notify schema; also the wire envelope the browser scope validates against. */
+export declare const CompletionNotifySettingsSchema: z<CompletionNotifySettings>;
+//# sourceMappingURL=completion-notify-settings.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,11 @@
+/** Host registration for the completion-notify preference. */
+import type { Context } from '@deepseek-ai/cordis';
+export { COMPLETION_NOTIFY_ENABLED_FIELD, COMPLETION_NOTIFY_SETTINGS_NAMESPACE, DEFAULT_COMPLETION_NOTIFY_ENABLED, type CompletionNotifySettings, } from './completion-notify-settings.js';
+/**
+ * Register the durable completion-notify section when the optional settings
+ * service is composed. The browser half reads and writes the enabled flag
+ * through the settings scope bound to this namespace.
+ * @param ctx - Host context that may acquire the settings service.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "dsh-plugin-completion-notify",
+  "description": "Desktop completion notifications for dsh web: a system notification when a session finishes while you are not looking at it",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/build-client.mjs",
+    "bundle": "node scripts/build-client.mjs",
+    "watch": "node scripts/build-client.mjs --watch"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/node": "^22.20.1",
+    "@types/react": "~18.3.1",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "notification",
+    "desktop"
+  ]
+}