deck-plugin-sdk 1.5.0 → 1.6.1

package/types/core/editorsession.d.ts

@@ -1,50 +1,55 @@
-// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
-export interface SessionTab {
-    /** Older sessions can also hold "graph" and "pr" tabs, from before git moved to the Git
-     *  plugin. The Editor skips them on restore. */
-    kind: "file" | "media" | "graph" | "pr";
-    path: string;
-    rel: string | null;
-    dirty?: string;
-}
-export interface WorkspaceSession {
-    tabs: SessionTab[];
-    activeId: string | null;
-    expanded: string[];
-    /** A typed-but-uncommitted message. Per root, because a message belongs to the repo it
-     *  describes. Only the active module is mounted, so without this a half-written message is
-     *  destroyed by switching to a terminal to check something — which is exactly when you switch. */
-    commitMsg?: string;
-    /** Collapsed Source Control rows: the two section headers, and folders in tree view. Per root
-     *  because the keys are paths in this repo. A Set on the way in and out; an array here because
-     *  that is what survives JSON. */
-    scmCollapsed?: string[];
-}
-/** A file to open, and optionally where in it to land. */
-export interface PendingFile {
-    path: string;
-    line?: number;
-}
-export declare function queueOpenFiles(files: (string | PendingFile)[], instance?: EditorInstance): void;
-/** Take everything queued for one editor, leaving its queue empty. */
-export declare function drainOpenFiles(instance?: EditorInstance): PendingFile[];
-/**
- * Which editor is asking.
- *
- * There are two: the Editor tab, which opens whatever folder you point it at, and the one inside
- * Terminals, which follows that workspace's cwd. They are separate windows onto different work,
- * so their open folder and their UI prefs are stored per instance. Open TABS already separate on
- * their own — loadSession is keyed by root, and the two rarely share one.
- */
-export type EditorInstance = "tab" | "terminals";
-export declare function loadEditorRoot(instance: EditorInstance): string;
-export declare function saveEditorRoot(instance: EditorInstance, root: string): void;
-export interface GlobalUi {
-    mdMode: "edit" | "live" | "split" | "preview";
-    panel: "explorer" | "search" | "debug" | "scm";
-    sidebarW: number;
-}
-export declare function loadSession(root: string): WorkspaceSession | null;
-export declare function saveSession(root: string, s: WorkspaceSession): void;
-export declare function loadUi(instance: EditorInstance): Partial<GlobalUi>;
-export declare function saveUi(instance: EditorInstance, ui: GlobalUi): void;
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+export interface SessionTab {
+    /** Older sessions can also hold "graph" and "pr" tabs, from before git moved to the Git
+     *  plugin. The Editor skips them on restore. */
+    /** "untitled" is a buffer never saved (Ctrl+N), path `untitled:Untitled-N`: restored from
+     *  `content` alone, with no disk read. An older Deck skips the kind, as it skips "graph". */
+    kind: "file" | "media" | "graph" | "pr" | "untitled";
+    path: string;
+    rel: string | null;
+    dirty?: string;
+    /** untitled: its whole text, and the language picked by hand for it (none: detected). */
+    content?: string;
+    lang?: string;
+}
+export interface WorkspaceSession {
+    tabs: SessionTab[];
+    activeId: string | null;
+    expanded: string[];
+    /** A typed-but-uncommitted message. Per root, because a message belongs to the repo it
+     *  describes. Only the active module is mounted, so without this a half-written message is
+     *  destroyed by switching to a terminal to check something — which is exactly when you switch. */
+    commitMsg?: string;
+    /** Collapsed Source Control rows: the two section headers, and folders in tree view. Per root
+     *  because the keys are paths in this repo. A Set on the way in and out; an array here because
+     *  that is what survives JSON. */
+    scmCollapsed?: string[];
+}
+/** A file to open, and optionally where in it to land. */
+export interface PendingFile {
+    path: string;
+    line?: number;
+}
+export declare function queueOpenFiles(files: (string | PendingFile)[], instance?: EditorInstance): void;
+/** Take everything queued for one editor, leaving its queue empty. */
+export declare function drainOpenFiles(instance?: EditorInstance): PendingFile[];
+/**
+ * Which editor is asking.
+ *
+ * There are two: the Editor tab, which opens whatever folder you point it at, and the one inside
+ * Terminals, which follows that workspace's cwd. They are separate windows onto different work,
+ * so their open folder and their UI prefs are stored per instance. Open TABS already separate on
+ * their own — loadSession is keyed by root, and the two rarely share one.
+ */
+export type EditorInstance = "tab" | "terminals";
+export declare function loadEditorRoot(instance: EditorInstance, pane?: string): string;
+export declare function saveEditorRoot(instance: EditorInstance, root: string, pane?: string): void;
+export interface GlobalUi {
+    mdMode: "edit" | "live" | "split" | "preview";
+    panel: "explorer" | "search" | "debug" | "scm";
+    sidebarW: number;
+}
+export declare function loadSession(root: string): WorkspaceSession | null;
+export declare function saveSession(root: string, s: WorkspaceSession): void;
+export declare function loadUi(instance: EditorInstance): Partial<GlobalUi>;
+export declare function saveUi(instance: EditorInstance, ui: GlobalUi): void;

package/types/core/editorsettings.d.ts

@@ -80,6 +80,15 @@ export interface EditorSettings {
     agentNotifyFinished: boolean;
     agentNotifyNeedsInput: boolean;
     agentNotifyOsToast: boolean;
+    /** Layout: the file panel docked beside the code or a drawer over it (Ctrl+B either way), the
+     *  status as a bar along the bottom or a pill floating over the code, and the file's path on its
+     *  own row under the tabs or in the tab line. */
+    layoutFiles: "docked" | "drawer";
+    layoutStatus: "bar" | "pill";
+    layoutPath: "row" | "tabs";
+    /** With the files in a drawer: Search, Source Control and Debug as icons in the tab line, or
+     *  along the top of the drawer. */
+    layoutViews: "tabs" | "drawer";
     theme: "deck-dark" | "vs-dark" | "hc-black";
     iconTheme: string;
     diffSideBySide: boolean;

package/types/core/fileview.d.ts

@@ -29,7 +29,26 @@ export declare const fileOpeners: {
 /** The id of the plugin that opens `path` (by its extension), or undefined: the Editor's. */
 export declare function pluginForFile(path: string): string | undefined;
 /**
- * Open `path` in the plugin that claims its type, as a tab of its own. False when no plugin does,
- * so the caller opens it in the Editor as before. Every way Deck opens a file asks this first.
+ * The files Deck's browser opens: the types defaultbrowser.rs registers with Windows (FILE_TYPES
+ * there), so a choice offered here is one Windows can hand over too.
  */
-export declare function openWithPlugin(path: string): boolean;
+export declare const BROWSER_TYPES: string[];
+/** Where a file opens: the Editor, a browser tab, or a plugin's pane (`plugin:<id>`). */
+export type Opener = "editor" | "browser" | `plugin:${string}`;
+/** The user's choice per extension (Settings, `openWith`); a type with none is Automatic. */
+export declare const openPrefs: {
+    current: Record<string, string>;
+};
+/**
+ * Where `path` opens. The user's choice for its type wins, where it still can (the plugin is
+ * loaded, the file is local for a browser tab); otherwise Automatic: `hint`, how it was opened
+ * (a page Windows handed Deck as the browser), then the plugin that claims the type, then the Editor.
+ */
+export declare function openerFor(path: string, hint?: Opener, prefs?: Record<string, string>): Opener;
+/** `C:\a b\x.html` as file:///C:/a%20b/x.html, for a browser tab. */
+export declare const fileUrl: (path: string) => string;
+/**
+ * Open `path` where its type opens (`openerFor`), as a tab of its own. False when that is the
+ * Editor, which the caller opens it in. Every way Deck opens a file asks this first.
+ */
+export declare function openByType(path: string, hint?: Opener): boolean;

package/types/core/notifications.d.ts

@@ -0,0 +1,84 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/**
+ * attention: needs you now (a meeting starting, someone asking to join a board, a timer about to
+ * fire). activity: something finished in the background (a download, a timer that ran).
+ */
+export type NotifKind = "input" | "done" | "attention" | "activity" | "update" | "error" | "news" | "plugin";
+/**
+ * A button on a card and on its bell row. `nav` (a deck-navigate target) and `act` (a handler
+ * registered with onNotifAction) survive a restart; `run`, a plugin's own function, does not, so
+ * after a restart that button is gone from the bell.
+ */
+export interface NotifAction {
+    label: string;
+    primary?: boolean;
+    nav?: string;
+    act?: string;
+    run?: () => void;
+}
+export interface Notif {
+    id: string;
+    kind: NotifKind;
+    title: string;
+    body: string;
+    ts: number;
+    /** Replaces an earlier notification with the same key. */
+    key?: string;
+    /** The workspace an agent notification is about: a click goes there. */
+    wsId?: string;
+    /** Where a click on the card itself goes, when it is not about a workspace. */
+    nav?: string;
+    /** Who posted it, shown beside the time: a plugin's name. */
+    source?: string;
+    actions?: NotifAction[];
+    /** Seen: the bell has been opened since it came. Read: the bell was closed after that. */
+    seen?: boolean;
+    read?: boolean;
+}
+export type Card = Notif & {
+    sticky: boolean;
+};
+/** The kinds Settings lists. What's new counts as an update. */
+export type PrefKind = "input" | "done" | "attention" | "activity" | "update" | "error" | "plugin";
+export type Channel = "card" | "bell" | "sound" | "os";
+export declare const PREF_KINDS: {
+    kind: PrefKind;
+    label: string;
+    desc: string;
+}[];
+/**
+ * Whether a kind shows on a channel. Until it is set in Settings › Notifications, the agent kinds
+ * follow the four switches that Settings › AI agents used to have (on at all, finished, needs input,
+ * Windows), so nobody's choice flips.
+ */
+export declare function prefFor(kind: PrefKind, ch: Channel): boolean;
+export declare const useNotifCards: () => Card[];
+export declare function useNotifHistory(): Notif[];
+/** Whether Deck is the window in front, for a caller that only speaks up when you are away. */
+export declare const deckInFront: () => boolean;
+/**
+ * Post a notification. Returns its id, or "" when the user has every channel for its kind off.
+ * `transient`: a card only, never kept in the bell, for something in progress that a result will
+ * replace or resolveKey will take down (a hot reload while it runs).
+ */
+export declare function notify(n: Omit<Notif, "id" | "ts" | "seen" | "read"> & {
+    sticky?: boolean;
+    transient?: boolean;
+}): string;
+/** The card's ✕: it goes, and its key stays quiet (see notify) until resolved or acted on. */
+export declare function closeCard(id: string): void;
+/** The card goes; the bell keeps it. */
+export declare function dismissCard(id: string): void;
+/** Gone from the bell, and its card with it. */
+export declare function removeNotif(id: string): void;
+/** What a key was about is dealt with (an agent was answered): its card goes, its row is read. */
+export declare function resolveKey(key: string): void;
+export declare function clearNotifs(): void;
+/** The bell was opened: the badge clears, the rows stay lifted until it closes. */
+export declare function markSeen(): void;
+export declare function markRead(): void;
+/** What a persisted action's `act` runs. Registered by the module that posts it, at import. */
+export declare function onNotifAction(name: string, run: () => unknown): void;
+/** A click on the card or the row itself: where it is about, then the card goes. */
+export declare function openNotif(n: Notif): void;
+export declare function runAction(n: Notif, a: NotifAction): void;

package/types/core/notifyapi.d.ts

@@ -0,0 +1,39 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+export interface PluginNotification {
+    title: string;
+    /**
+     * Which of Settings › Notifications' rows it follows. "plugin" (the default) for a plugin's own
+     * news; "attention" for something that needs the user now (a meeting starting, a request to
+     * join), which also reaches Windows while Deck is behind; "activity" for something that finished
+     * in the background; "error" for a failure.
+     */
+    kind?: "plugin" | "attention" | "activity" | "error";
+    body?: string;
+    /** The plugin's name, shown beside the time. */
+    source: string;
+    /** Replaces this plugin's earlier notification with the same key, rather than adding another. */
+    key?: string;
+    /** Stays until dismissed instead of going after a few seconds. The bell keeps it either way. */
+    sticky?: boolean;
+    /**
+     * Something in progress: a card only, with no sound, never kept in the bell. Take it down with
+     * dismissNotification when it is done, or replace it (same key) with the result.
+     */
+    transient?: boolean;
+    /**
+     * Buttons on the card and on its bell row. `run` is the plugin's own function, so it lasts only
+     * as long as this session: after a restart the row is still in the bell, without its buttons.
+     */
+    actions?: {
+        label: string;
+        primary?: boolean;
+        run: () => void;
+    }[];
+}
+/**
+ * Post a notification: a card in the corner and a row in the bell, as Settings › Notifications
+ * says for plugins. For a passing word ("Copied") use toast() instead, which the bell does not keep.
+ */
+export declare function notify(n: PluginNotification): void;
+/** Take down this plugin's notification with that key: its card goes, its bell row is marked read. */
+export declare function dismissNotification(source: string, key: string): void;

package/types/core/terminals.d.ts

@@ -50,6 +50,8 @@ export interface LayoutWorkspace {
     cwd: string;
     tabs: LayoutTab[];
     activeTab: string;
+    /** Its colour on the sidebar's collapsed rail, by index (Terminals' TONES); none picks one from the name. */
+    color?: number;
 }
 export interface Layout {
     workspaces: LayoutWorkspace[];

package/types/modules/editor/detectlang.d.ts

@@ -0,0 +1,3 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** A Monaco language id (only ones Monaco ships), "plaintext" when nothing stands out. */
+export declare function detectLanguage(text: string): string;

package/types/modules/editor/editorstatus.d.ts

@@ -10,6 +10,8 @@ export interface EditorStatus {
         author: string;
         summary: string;
     } | null;
+    /** The shown model's Monaco language id: an untitled buffer's changes as it is detected. */
+    lang?: string;
 }
 export declare let editorStatus: EditorStatus;
 export declare function setEditorStatus(patch: Partial<EditorStatus>): void;

package/types/modules/editor/models.d.ts

@@ -1,7 +1,18 @@
 // GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
 import { monaco } from "../../core/monaco";
 export declare const viewStates: Map<string, monaco.editor.ICodeEditorViewState | null>;
+/**
+ * An untitled buffer (Ctrl+N): `untitled:Untitled-N`. It has no file behind it, so its model gets
+ * an untitled: URI rather than a file:// one, it is never shown to a language server (which would
+ * answer for a file that does not exist), and its language comes from its text.
+ */
+export declare const isUntitled: (path: string) => boolean;
 export declare function fileUri(path: string): monaco.Uri;
+/** Pick an untitled buffer's language by hand, or null to go back to detecting it. Fine to call
+ *  before its model exists (a restored tab): the model is then created with it. */
+export declare function setUntitledLanguage(path: string, id: string | null): void;
+/** Take `path` for `owner`; false when another editor's buffer has it. */
+export declare function claimUntitled(path: string, owner: string): boolean;
 export declare function getFileModel(path: string, initial: string): monaco.editor.ITextModel;
 export declare function setModelValue(path: string, value: string): void;
 export declare function disposeModel(path: string | undefined): void;