deck-plugin-sdk 1.11.1 → 1.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deck-plugin-sdk",
-  "version": "1.11.1",
+  "version": "1.12.1",
   "description": "Build a plugin for Deck, outside the Deck repository.",
   "type": "module",
   "license": "MIT",

package/permissions.json

@@ -1,5 +1,5 @@
 {
-  "generated": "by sdk/gen-permissions.mjs from src/core/permissions.ts; do not edit",
+  "generated": "by sdk/gen-permissions.mjs from src/core/plugins/permissions.ts; do not edit",
   "permissions": {
     "files": "Read and change files anywhere on this PC",
     "processes": "Run programs and commands",

package/shim/p2p.d.ts

@@ -1,4 +1,4 @@
 // GENERATED by sdk/gen-shim.mjs — do not edit.
 //
 // Deck's real types, so a plugin is checked against the actual shape.
-export * from "../types/core/p2p";
+export * from "../types/core/app/p2p";

package/shim/settings.d.ts

@@ -1,5 +1,5 @@
 // GENERATED by sdk/gen-shim.mjs — do not edit.
 //
 // Deck's real settings types, so a plugin is checked against the actual shape.
-export { useSettings, getSettings, saveSettings, userName } from "../types/core/settingsstore";
+export { useSettings, getSettings, saveSettings, userName } from "../types/core/app/settingsstore";
 export type { Settings } from "../types/core/bridge";

package/shim/terminals.d.ts

@@ -1,4 +1,4 @@
 // GENERATED by sdk/gen-shim.mjs — do not edit.
 //
 // Deck's real types, so a plugin is checked against the actual shape.
-export * from "../types/core/terminals";
+export * from "../types/core/workspaces/terminals";

package/shim/ui.d.ts

@@ -6,21 +6,21 @@ export * from "../types/components/ConfirmDialog";
 export * from "../types/components/NamePrompt";
 export * from "../types/components/ContextMenu";
 export * from "../types/components/Toast";
-export * from "../types/core/notifyapi";
+export * from "../types/core/notifications/notifyapi";
 export * from "../types/components/useResize";
-export * from "../types/modules/editor/MarkdownLive";
+export * from "../types/modules/editor/viewers/MarkdownLive";
 export * from "../types/components/TreeRow";
 export * from "../types/components/dragrow";
 export * from "../types/components/TabStrip";
 export * from "../types/components/MarkdownToolbar";
 export * from "../types/components/ActivityBar";
-export * from "../types/core/editorsettings";
-export * from "../types/core/keystore";
-export * from "../types/modules/editor/viewers";
+export * from "../types/core/editor/editorsettings";
+export * from "../types/core/keys/keystore";
+export * from "../types/modules/editor/viewers/viewers";
 export * from "../types/components/FileIcon";
-export * from "../types/core/icontheme";
-export * from "../types/modules/editor/tree";
-export * from "../types/core/decode";
-export * from "../types/core/keys";
+export * from "../types/core/editor/icontheme";
+export * from "../types/modules/editor/tree/tree";
+export * from "../types/core/editor/decode";
+export * from "../types/core/keys/keys";
 export * from "../types/modules/editor/MonacoHosts";
-export * from "../types/core/fileview";
+export * from "../types/core/plugins/fileview";

package/template/plugin.json

@@ -5,6 +5,6 @@
   "icon": "Sparkles",
   "color": "#a78bfa",
   "version": "0.1.0",
-  "minDeck": "1.11.1",
+  "minDeck": "1.12.1",
   "permissions": []
 }

package/types/components/FileIcon.d.ts

@@ -1,5 +1,5 @@
 // GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
-import { type IconRef } from "../core/icontheme";
+import { type IconRef } from "../core/editor/icontheme";
 export declare function FileIcon({ icon, size, tint }: {
     icon: IconRef;
     size?: number;

package/types/components/TabStrip.d.ts

@@ -1,5 +1,6 @@
 // GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
+import { type MenuEntry } from "./ContextMenu";
 export interface TabItem {
     id: string;
     title: ReactNode;
@@ -12,7 +13,7 @@ export interface TabItem {
     /** Tooltip for the close button; defaults to "Close". */
     closeTitle?: string;
 }
-export declare function TabStrip({ tabs, activeId, onSelect, onClose, onReorder, onDoubleClick, leading, trailing, pill: pillProp, chip, onAdd, addTitle, }: {
+export declare function TabStrip({ tabs, activeId, onSelect, onClose, onReorder, onDoubleClick, menu, leading, trailing, pill: pillProp, chip, onAdd, addTitle, }: {
     tabs: readonly TabItem[];
     activeId: string | null;
     onSelect: (id: string) => void;
@@ -20,6 +21,8 @@ export declare function TabStrip({ tabs, activeId, onSelect, onClose, onReorder,
     /** Moves `from` to `to`'s position. Omit to make the strip non-reorderable. */
     onReorder?: (from: string, to: string) => void;
     onDoubleClick?: (id: string) => void;
+    /** A tab's right-click menu. Asked for when it opens, so it reflects the tabs as they are then. */
+    menu?: (id: string) => MenuEntry[];
     /** Controls before the first tab. */
     leading?: ReactNode;
     /** Right-aligned controls after the tabs — view toggles, save state. */

package/types/core/{settingsstore.d.ts → app/settingsstore.d.ts}

@@ -1,5 +1,5 @@
 // GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
-import { type Settings } from "./bridge";
+import { type Settings } from "../bridge";
 /** Called by Settings after every write, so readers update without a reload. */
 export declare function publishSettings(s: Settings): void;
 /**

package/types/core/bridge.d.ts

@@ -1,7 +1,7 @@
 // GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
-import { type DebugTarget } from "./debugtargets";
-import type { Accent, Background, Density, Palette, TermCustom, TermTheme } from "./theme";
-import type { SearchEngine } from "./browserurl";
+import { type DebugTarget } from "./editor/debugtargets";
+import type { Accent, Background, Density, Palette, TermCustom, TermTheme } from "./app/theme";
+import type { SearchEngine } from "./browser/browserurl";
 /** Open a URL in the default browser. */
 export declare const openExternal: (url: string) => Promise<void>;
 /** A box in physical pixels, relative to the window: where a browser pane's webview goes. */
@@ -375,7 +375,7 @@ export interface Settings {
     drawerHidden: string[];
     /** Drawer tabs left-to-right. Ids missing from it keep their discovery order, after the rest. */
     drawerOrder: string[];
-    /** Which side of the footer each drawer tab and readout sits on, in order (core/footerlayout.ts).
+    /** Which side of the footer each drawer tab and readout sits on, in order (core/app/footerlayout.ts).
      *  Absent until something is moved: drawer tabs left, readouts right, in the orders above. */
     footerLayout?: {
         left: string[];
@@ -1184,7 +1184,7 @@ export declare const sshTunnelClose: (id: number) => Promise<void>;
  * Offer programs to the editor's debugger: a plugin that runs something debuggable (the Flutter
  * plugin's runs) publishes them here, and the Run and Debug panel lists them to attach to. Pass
  * the plugin's whole current list each time, under its own `source`; an empty list removes it.
- * See core/debugtargets.ts.
+ * See core/editor/debugtargets.ts.
  */
 export declare const setDebugTargets: (source: string, targets: DebugTarget[]) => void;
-export type { DebugTarget } from "./debugtargets";
+export type { DebugTarget } from "./editor/debugtargets";

package/types/core/{bookmarks.d.ts → browser/bookmarks.d.ts}

@@ -4,6 +4,8 @@ export interface BookmarkNode {
     title: string;
     /** A page has a URL; a folder has children instead. */
     url?: string;
+    /** A word that opens it from the tool picker, as a link's does (links.ts). */
+    keyword?: string;
     children?: BookmarkNode[];
 }
 export interface Bookmarks {
@@ -30,8 +32,8 @@ export declare function folders(b: Bookmarks): {
 export declare const add: (b: Bookmarks, folder: string, node: BookmarkNode) => Bookmarks;
 /** Remove the node with `id`, wherever it is (a folder goes with what is in it). */
 export declare function remove(b: Bookmarks, id: string): Bookmarks;
-/** Change a node's title or URL. */
-export declare function update(b: Bookmarks, id: string, patch: Partial<Pick<BookmarkNode, "title" | "url">>): Bookmarks;
+/** Change a node's title, URL or keyword. */
+export declare function update(b: Bookmarks, id: string, patch: Partial<Pick<BookmarkNode, "title" | "url" | "keyword">>): Bookmarks;
 /** The node with `id`, and the id of the folder it is in. */
 export declare function locate(b: Bookmarks, id: string): {
     node: BookmarkNode;

package/types/core/{browser.d.ts → browser/browser.d.ts}

@@ -1,6 +1,7 @@
 // GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
 import { type RecentPage } from "./browserurl";
 import { type Bookmarks } from "./bookmarks";
+import "./webnotify";
 /**
  * `home`: the pane shows Deck's start page, and its webview (if it has one) is hidden. `back` and
  * `forward`: whether the page has history that way. `private`: nothing it visits is kept.
@@ -129,6 +130,7 @@ export declare function registerZoomTarget(pane: string, holds: () => boolean):
 export declare const activeBrowserPage: () => string | undefined;
 /** Zoom the pane's page a step in or out, or back to 100% (0). */
 export declare function stepZoom(pane: string, dir: -1 | 0 | 1): void;
+export declare const hostOf: (url: string) => string;
 /** The URL a just-opened browser pane should show, if a page asked for it. */
 export declare const takeWaitingUrl: () => {
     url: string;
@@ -138,7 +140,7 @@ export declare const takeWaitingUrl: () => {
 export declare const newBrowserTab: (url?: string, isPrivate?: boolean) => boolean | void;
 /**
  * A browser tab on `url` in a floating window, so the main window's view stays (Terminals'
- * deck-open-float, core/floatwin.ts openInFloat): `name` the window that collects them ("links"
+ * deck-open-float, core/workspaces/floatwin.ts openInFloat): `name` the window that collects them ("links"
  * from other programs, "agent" for an agent's pages), `beside` the window a pane is in.
  */
 export declare function browserInFloat(url: string, where: {

package/types/core/browser/sitenotify.d.ts

@@ -0,0 +1,11 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+export interface SiteNote {
+    title: string;
+    body: string;
+    /** Under the text: where it came from ("#hapster-tech · Slack"). */
+    source: string;
+    /** A person's message (the card shows them as one): a rule here found a sender. */
+    message: boolean;
+}
+/** How a page's notification (its host, title and text) is shown in Deck. */
+export declare function siteNote(host: string, title: string, body: string): SiteNote;

package/types/core/browser/webnotify.d.ts

@@ -0,0 +1,2 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+export {};

package/types/core/{editorsettings.d.ts → editor/editorsettings.d.ts}

@@ -115,6 +115,6 @@ export declare function modelOptionsFor(s: EditorSettings, languageId: string |
     tabSize: number;
     insertSpaces: boolean;
 };
-/** Whether the file tree shows an entry, under these settings (core/treehide.ts). */
+/** Whether the file tree shows an entry, under these settings (core/editor/treehide.ts). */
 export declare const treeShows: (s: EditorSettings, name: string) => boolean;
 export declare function monacoOptionsFrom(s: EditorSettings): MonacoNS.editor.IEditorOptions;

package/types/core/{icontheme.d.ts → editor/icontheme.d.ts}

@@ -1,6 +1,6 @@
 // GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
 import { type LucideIcon } from "lucide-react";
-import { type ImportedPack } from "./bridge";
+import { type ImportedPack } from "../bridge";
 export type IconRef = {
     kind: "lucide";
     icon: LucideIcon;

package/types/core/{notifications.d.ts → notifications/notifications.d.ts}

@@ -15,6 +15,8 @@ export interface NotifAction {
     nav?: string;
     act?: string;
     run?: () => void;
+    /** What a click on the card does (open the tab, the file): no button of its own. */
+    open?: boolean;
 }
 export interface Notif {
     id: string;
@@ -33,6 +35,14 @@ export interface Notif {
     /** Who posted it, shown beside the time: a plugin's name. */
     source?: string;
     actions?: NotifAction[];
+    /**
+     * A person's message (a chat, a mail): the card shows the sender, `title`, with their picture
+     * (`image`, else their initials) and the app's icon on it (`badge`), and the whole of `body`.
+     */
+    message?: {
+        image?: string;
+        badge?: string;
+    };
     /** Seen: the bell has been opened since it came. Read: the bell was closed after that. */
     seen?: boolean;
     read?: boolean;
@@ -79,8 +89,21 @@ 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;
+/**
+ * The tab of the plugin named `source`, where a click on its notification goes when the plugin
+ * gave it no open action. Set by the plugin loader (plugins.ts), so that this file and the plugin
+ * API in notifyapi.ts do not import the loader, which would put all of it in the SDK's types.
+ */
+declare let tabOfPlugin: (source: string) => string | undefined;
+export declare const setPluginTabs: (f: typeof tabOfPlugin) => void;
+export declare const pluginTabOf: (source: string) => string | undefined;
 /** 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. */
+/** Whether a click on the card or its row goes anywhere: it is drawn as clickable only then. */
+export declare const opens: (n: Notif) => boolean;
+/** The actions shown as buttons: all but the one the card's click runs. */
+export declare const buttons: (n: Notif) => NotifAction[];
+/** A click on the card or the row itself: its open action, or where it is about; then the card goes. */
 export declare function openNotif(n: Notif): void;
 export declare function runAction(n: Notif, a: NotifAction): void;
+export {};

package/types/core/{notifyapi.d.ts → notifications/notifyapi.d.ts}

@@ -23,12 +23,22 @@ export interface PluginNotification {
     /**
      * 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.
+     * `open`: what a click anywhere on the card does (open the mail, the build); it has no button.
+     * Without one, a click opens the plugin's own tab, when it has one.
      */
     actions?: {
         label: string;
         primary?: boolean;
+        open?: boolean;
         run: () => void;
     }[];
+    /**
+     * A person's message (new mail, a chat): the card shows `title` as the sender, with their picture
+     * (`image`, an https: or data: address; else their initials), and the whole of `body`.
+     */
+    message?: {
+        image?: string;
+    };
 }
 /**
  * Post a notification: a card in the corner and a row in the bell, as Settings › Notifications

package/types/core/workspaces/layout.d.ts

@@ -0,0 +1,168 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import { TabGroup } from "./zones";
+export type SplitDir = "h" | "v";
+export type LayoutNode = {
+    kind: "leaf";
+    id: string;
+    label?: string;
+    view?: string;
+} | {
+    kind: "split";
+    dir: SplitDir;
+    a: LayoutNode;
+    b: LayoutNode;
+    ratio: number;
+};
+/**
+ * A tab, and — with `x`/`y` — a zone on the canvas.
+ *
+ * The coordinates are OPTIONAL and nothing writes them on load: a tab saved before zones
+ * existed has none, and `zoneAt` places it by its index instead. That keeps every layout ever
+ * written valid and means the tab strip and the canvas are two views of one list, not two
+ * models to keep in sync.
+ */
+export interface LayoutTab {
+    id: string;
+    title: string;
+    root: LayoutNode;
+    x?: number;
+    y?: number;
+    /**
+     * Behind another tab in the same zone. Tabs sharing a cell are one zone, and the one without
+     * this flag is the one it shows — so a zone reopens on the tab you left it on. Absent on every
+     * tab that has a cell to itself, which is every tab written before zones held several.
+     */
+    hidden?: boolean;
+    /** The tab group it is in (LayoutWorkspace.groups); a group's tabs sit together in one zone. */
+    group?: string;
+    /** A colour of its own, an index into GROUP_COLORS: a faint tint behind the tab. */
+    color?: number;
+    /**
+     * Torn off into a window of its own (core/workspaces/floatwin.ts): the window's id. Such a tab is in no
+     * zone, though it keeps its x/y to go back to. A restart reopens the window (Layout.floats has
+     * where it was).
+     */
+    window?: string;
+    /**
+     * Opened straight into a floating window by Deck (openInFloat: a link, a page an agent opened, a
+     * file Ctrl+clicked in a terminal), so closing that window closes it rather than docking it into
+     * the main window. Dropped the moment the tab is moved by hand: then it is one of yours.
+     */
+    transient?: true;
+}
+export interface LayoutWorkspace {
+    id: string;
+    name: string;
+    cwd: string;
+    tabs: LayoutTab[];
+    activeTab: string;
+    /** Tab groups: a name and colour over tabs that sit together in a zone's row, folded or not. */
+    groups?: TabGroup[];
+    /** Its colour on the sidebar's collapsed rail, by index (Terminals' TONES); none picks one from the name. */
+    color?: number;
+}
+/** Where a floating window was, in physical screen pixels (its size and place before any maximise), to reopen it there. */
+export interface FloatBounds {
+    id: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    max?: boolean;
+    /** A window things are sent to by name (core/workspaces/floatwin.ts openInFloat): "links", "agent". */
+    name?: string;
+}
+export interface Layout {
+    workspaces: LayoutWorkspace[];
+    activeWs: string;
+    floats?: FloatBounds[];
+}
+export declare let currentLayout: Layout | null;
+export declare const layoutSubs: Set<() => void>;
+export declare let notifyQueued: boolean;
+export declare function publishLayout(l: Layout): void;
+export declare function getLayout(): Layout | null;
+export declare const uuid: () => `${string}-${string}-${string}-${string}-${string}`;
+export declare function defaultLayout(): Layout;
+export declare function allLeafIds(l: Layout): string[];
+/** Views that were Deck's own and are now a plugin's, old id to new. */
+export declare const MOVED_VIEWS: Record<string, string>;
+export declare let loadPromise: Promise<void> | null;
+export declare let liveAtLoad: Set<string> | null;
+export declare function loadLayoutOnce(): Promise<void>;
+/**
+ * What every layout write leaves true of a workspace: its active tab is one the main window draws
+ * (a tab in a floating window is not; going to one leaves the main window on a neighbour), its zone
+ * shows it (showActiveTab), a folded group holding it opens (openActiveGroup), and a tab group
+ * whose last tab went goes with it (pruneGroups).
+ */
+export declare function tidy(w: LayoutWorkspace): LayoutWorkspace;
+export declare let saveTimer: ReturnType<typeof setTimeout> | undefined;
+export declare function mutateLayout(fn: (l: Layout) => Layout): void;
+export declare function useLayout(): Layout | null;
+export declare function activeWorkspaceCwd(): string;
+/** Switch the active workspace (+ optionally its active tab) — used by agent-notification clicks. */
+export declare function switchWorkspace(wsId: string, tabId?: string): void;
+/** The workspace whose cwd matches (case/slash-insensitive), for routing an agent hook to a tab. */
+export declare function workspaceByCwd(cwd: string): LayoutWorkspace | undefined;
+/** The folder a pane's shell was spawned in — its workspace's cwd. */
+export declare function paneCwd(paneId: string): string;
+/**
+ * A pane's display name: its own label, else the title of the tab holding it.
+ *
+ * Here rather than in the footer that first needed it, because Settings lists the same pinned
+ * panes and a second copy of this walk would be a second answer to one question.
+ */
+export declare function paneLabel(paneId: string): string;
+/** Which workspace + tab holds a pane, for jumping to an agent from outside Terminals. */
+export declare function paneLocation(paneId: string): {
+    wsId: string;
+    wsName: string;
+    tabId: string;
+} | undefined;
+export declare const termSpawn: (id: string, cwd: string, cols: number, rows: number) => Promise<void>;
+export declare const termWrite: (id: string, data: string) => Promise<void>;
+export declare const termResize: (id: string, cols: number, rows: number) => Promise<void>;
+export declare const termKill: (id: string) => Promise<void>;
+export declare const termList: () => Promise<string[]>;
+/** Delete scrollback logs for panes not in `keep`. Returns how many were removed. */
+export declare const termSweepScrollback: (keep: string[]) => Promise<number>;
+export declare const termScrollback: (id: string) => Promise<string>;
+export declare const newLeaf: () => LayoutNode;
+export declare function leafIds(n: LayoutNode): string[];
+export declare function splitLeaf(n: LayoutNode, id: string, dir: SplitDir, ratio?: number, view?: string): LayoutNode;
+export declare function setLeafLabel(n: LayoutNode, id: string, label: string): LayoutNode;
+/**
+ * Turn a pane into a view, or back into a terminal when `view` is empty.
+ *
+ * The pane keeps its id, so the layout, the splits around it and its place in the tab are
+ * untouched — only what it renders changes. Its label goes with the old contents: a terminal
+ * named "server" that becomes a notes pane is not the server any more.
+ */
+export declare function setLeafView(n: LayoutNode, id: string, view: string): LayoutNode;
+export declare function closeLeaf(n: LayoutNode, id: string): LayoutNode | null;
+export declare const baseName: (p: string) => string;
+export type DropSide = "left" | "right" | "top" | "bottom";
+/** The leaf node itself (not just its id) — a move carries the pane's label with it. */
+export declare function findLeaf(n: LayoutNode, id: string): LayoutNode | null;
+/** Replace a leaf with a split holding it and `leaf`, ordered by which side `leaf` lands on. */
+export declare function insertBeside(n: LayoutNode, targetId: string, leaf: LayoutNode, side: DropSide): LayoutNode;
+/**
+ * Move a pane next to another within one tab. The leaf keeps its id, so the xterm instance (and
+ * therefore the running shell and its scrollback) survives — attach() re-parents it on remount.
+ * closeLeaf already collapses the split the pane leaves behind.
+ */
+export declare function moveLeaf(root: LayoutNode, srcId: string, targetId: string, side: DropSide): LayoutNode;
+export declare function newTab(title: string): LayoutTab;
+export declare function newWorkspace(name: string, cwd: string): LayoutWorkspace;
+/**
+ * Open a new tab in a workspace and return the id of the pane it contains.
+ *
+ * applyDtCommand's "new-tab" does the same thing but returns nothing, which is fine for an agent
+ * driving Deck over HTTP (it can look the pane up afterwards) and useless in-process, where the
+ * caller wants to type into the pane it just made. Pair it with queueInput: the pane has no PTY
+ * until it is attached to a sized element, so anything written before then is dropped.
+ */
+export declare function openTabInWorkspace(wsId: string, title: string, opts?: {
+    besideActive?: boolean;
+}): string | null;