deck-plugin-sdk 0.21.0 → 1.1.0

package/types/core/lsp.d.ts

@@ -0,0 +1,190 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import { monaco } from "./monaco";
+/** How to launch the server — passed straight to Rust, which implements the strategies. */
+interface ServerSpec {
+    /** "path" | "node-module" | "exe-search" — see resolve_server() in lsp.rs. */
+    strategy: string;
+    command?: string;
+    module?: string;
+    args?: string[];
+    /** How to install the server, for the Install button in Settings › Languages. */
+    install?: Install;
+}
+/**
+ * What to install for a server or a debugger, as one of a few kinds Deck turns into a command
+ * itself (tools.rs): a definition from the registry never names a command to run.
+ */
+export type InstallSpec = {
+    kind: "pip" | "npm";
+    packages: string[];
+} | {
+    kind: "github-release";
+    name: string;
+    repo: string;
+    tag: string;
+    asset: string;
+    sha256: string;
+};
+/** A structured install, or a sentence for what Deck cannot install itself (an SDK). */
+export type Install = InstallSpec | string;
+/** An install as one sentence, for where a button would not fit or there is nothing to run. */
+export declare function installText(i: Install): string;
+/** Whether Deck can run it (an Install button), rather than only describe it. */
+export declare const canInstall: (i: Install | undefined) => i is InstallSpec;
+/** A language's server or debugger install entry, if its definition has one. */
+export declare function installFor(languageId: string, what: "server" | "debug"): Install | undefined;
+/** A language's debug adapter, or null when its definition names none (or there is no such language). */
+export declare function debugAdapterFor(languageId: string): {
+    adapter: ServerSpec;
+    type: string;
+    rootMarker: string;
+    launch?: Record<string, unknown>;
+    launchUnless?: string;
+    install?: Install;
+} | null;
+/**
+ * Whether a language's debug adapter runs on this machine: starts it and sees whether it is still
+ * running a moment later. Resolves to what was run, rejects with why not (the adapter's first line
+ * of output: Python's "No module named debugpy", Node's "Cannot find module"). Null when the
+ * language names no adapter.
+ */
+export declare function probeDebugger(languageId: string): Promise<string | null>;
+/**
+ * Load every language definition from %APPDATA%\Deck\languages.
+ *
+ * This is the ONLY source of languages. Deck used to compile a few in from src/languages/, which
+ * meant the shipped ones and a user's own obeyed different rules — one needed a rebuild to
+ * change, the other a restart, and only the first could carry snippets. Now there is one kind of
+ * language definition, and Deck ships none: an empty folder means Monaco's own highlighting and
+ * no language server, which is a coherent state rather than a broken one.
+ *
+ * Never rejects. A language that fails to load is one language that does not work; it is not a
+ * reason for the editor not to start, and the same contract loadPlugins states.
+ */
+export declare function loadExternalLanguages(): Promise<void>;
+/** One language, as Settings lists it. Flattened from its LangDef — the panel shows what a
+ *  definition claims, not the definition itself. */
+export interface LoadedLanguage {
+    languageId: string;
+    serverId: string;
+    extensions: string[];
+    rootMarker: string;
+    strategy: string;
+    /** The command or node module the strategy will look for. */
+    command: string;
+    /** The folder it came from, which is the name to look for on disk. */
+    folder: string;
+    /** language.json's version, or "" when it has none (a pack from before versions). */
+    version: string;
+    snippets?: number;
+}
+export interface LanguageError {
+    folder: string;
+    message: string;
+}
+/** Every language definition that loaded. */
+export declare function loadedLanguages(): readonly LoadedLanguage[];
+/**
+ * Re-read the languages folder whenever it changes on disk. Called once at startup.
+ *
+ * What makes installing a language from the registry take effect without a restart, the same way
+ * the plugin watcher does for a plugin. Debounced: writing a definition and its snippets emits
+ * several events, and each would otherwise re-read the whole folder.
+ *
+ * Only NEW definitions and changed data are picked up. A language whose server is already
+ * running keeps that session — lsp.rs owns it, and restarting one because a snippet file changed
+ * would lose whatever it had analysed.
+ */
+export declare function watchLanguages(): void;
+/**
+ * Whether a language's server is actually installed, without opening a file of that type.
+ *
+ * Until this existed, a definition naming a server you do not have was only discoverable by
+ * opening such a file and reading the error — so "Python needs basedpyright installed" was
+ * something Deck knew and never said.
+ *
+ * `root` is optional and usually empty: a node module resolves from the project's node_modules
+ * first, so a check with no project answers "is it installed globally".
+ */
+export declare function probeLanguage(languageId: string, root?: string): Promise<string>;
+/**
+ * Folders that failed to load, and why.
+ *
+ * The point of surfacing these: a definition with a typo is otherwise completely silent — the
+ * language simply does not work, with nothing on screen to say a file was even read.
+ */
+export declare function languageErrors(): readonly LanguageError[];
+export declare function lspSupports(languageId: string): boolean;
+export type LspPhase = "starting" | "ready" | "error" | "stopped";
+export interface LspStatus {
+    id: string;
+    serverId: string;
+    root: string;
+    phase: LspPhase;
+    detail: string;
+    log: string[];
+}
+/** React hook: current LSP server statuses (for the editor indicator). */
+export declare function useLspStatus(): LspStatus[];
+export declare function lspErrorVersion(): number;
+/** Live path -> error count. Read after subscribing to changes with subscribeLspErrors. */
+export declare function lspErrorCounts(): Map<string, number>;
+export declare function subscribeLspErrors(cb: () => void): () => void;
+/** Notify the server a document is open. Call when a file tab opens. */
+export declare function lspOpenDoc(path: string, content: string, root: string): Promise<void>;
+/**
+ * Notify the server a document changed. Call for EVERY Monaco change, synchronously — no
+ * debounce.
+ *
+ * Under incremental sync each notification describes one edit relative to the server's current
+ * copy, so dropping or reordering any of them desynchronizes the document permanently. That is
+ * also why this is no longer debounced: a debounce necessarily drops intermediate states, which
+ * is only legal when every message carries the whole file. Sending immediately has the better
+ * property anyway — completion and hover fire on the keystroke, so under the old 300ms debounce
+ * they queried a server whose buffer was up to 300ms stale and answered for a position that did
+ * not exist there yet.
+ *
+ * `changes` comes straight from Monaco's content-change event. Its ranges are in pre-edit
+ * coordinates and it orders them end-of-document first, which is exactly what LSP expects for a
+ * sequentially-applied batch: applying a later-in-document edit never shifts an earlier range.
+ * Do not sort them.
+ */
+export declare function lspChangeDoc(path: string, content: string, root: string, changes?: readonly monaco.editor.IModelContentChange[]): Promise<void>;
+/** Notify the server a document closed. Call when a tab closes. */
+export declare function lspCloseDoc(path: string, root: string): Promise<void>;
+/** One result of a project-wide symbol search (Ctrl+T). `line` and `col` are 1-based. */
+export interface ProjectSymbol {
+    name: string;
+    kind: number;
+    container: string;
+    path: string;
+    line: number;
+    col: number;
+}
+/**
+ * Classes, functions and the rest whose name matches `query`, from every language server running
+ * for `root` (a TypeScript and a Python server can share one), each server's own ranking kept and
+ * the lists joined. Only servers already running answer: Ctrl+T does not start one. [] for an
+ * empty query.
+ */
+export declare function workspaceSymbols(root: string, query: string): Promise<ProjectSymbol[]>;
+/** A file's outline from its language server, or [] when no server has it open. Also what the
+ *  debugger's inline values use to find the function a frame is in. */
+export declare function documentSymbols(model: monaco.editor.ITextModel): Promise<monaco.languages.DocumentSymbol[]>;
+type OpenFileHandler = (path: string, line: number, column: number) => void;
+export declare function setLspOpenFileHandler(fn: OpenFileHandler): void;
+/** Stop the servers no project has touched for IDLE_STOP_MS. Exported for the check. */
+export declare function stopIdleServers(now?: number): string[];
+/** Stop all sessions (e.g. on workspace close). */
+export declare function lspStopAll(): void;
+/** Restart one server (UI action from the status popover). */
+/**
+ * Stop a language server. The next file opened for that root starts a fresh one, which is why
+ * this is both the Restart action and the memory readout's stop button — there is no difference
+ * between the two beyond what the caller says about it.
+ *
+ * Deleting the frontend session alongside the process matters: leaving it would send didOpen to
+ * a dead pipe on the next open, and the editor would sit at "ready" with no diagnostics.
+ */
+export declare function lspRestart(id: string): Promise<void>;
+export {};

package/types/core/patterntokens.d.ts

@@ -0,0 +1,24 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import * as monaco from "monaco-editor";
+/** One pattern, from a language definition. */
+export interface TokenPattern {
+    /** The semantic token type to emit — the name an extraTokenColors rule matches. */
+    token: string;
+    /**
+     * A regular expression, as a string, with ONE capturing group: the part to colour.
+     *
+     * The group is what makes `new\s+(\w+)` colour the class and not the keyword. A pattern with
+     * no group is ignored rather than colouring its whole match, because the whole match is almost
+     * never what was meant.
+     */
+    pattern: string;
+    /** Regex flags. `g` is added if absent; `i` is the only one usually wanted beyond it. */
+    flags?: string;
+}
+/**
+ * Register pattern-based semantic tokens for one language.
+ *
+ * Returns a disposable, so reloading a definition does not leave the previous provider behind
+ * emitting the old patterns alongside the new ones.
+ */
+export declare function registerPatternTokens(languageId: string, patterns: TokenPattern[]): monaco.IDisposable | null;

package/types/core/remotepath.d.ts

@@ -0,0 +1,17 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+export interface RemotePath {
+    host: string;
+    /** File access runs through sudo on the server. */
+    sudo: boolean;
+    /** Absolute POSIX path on the server. */
+    path: string;
+}
+export declare const isRemote: (p: string) => boolean;
+export declare function parseRemote(p: string): RemotePath | null;
+export declare function formatRemote(r: RemotePath): string;
+/** What a remote workspace is called: `vps:project`, or `vps:/` for the server's root. */
+export declare function remoteLabel(p: string): string;
+/** The ssh arguments that open an interactive shell in the folder. The path is single-quoted for
+ *  the remote shell, so spaces and `$` in it are taken literally. A server that sets no $SHELL
+ *  (minimal Alpine images) gets /bin/sh. */
+export declare function sshShellArgs(p: string): string[] | null;

package/types/core/settingsstore.d.ts

@@ -13,7 +13,4 @@ export declare function publishSettings(s: Settings): void;
 export declare function saveSettings(next: Settings): void;
 /** Current settings for non-React callers (the palette's providers). */
 export declare const getSettings: () => Settings;
-/** The OS account name — the home directory's last segment. "" if it can't be read. */
-export declare function osAccountName(): Promise<string>;
-export declare function userName(): Promise<string>;
 export declare function useSettings(): Settings;

package/types/core/snippets.d.ts

@@ -0,0 +1,15 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+export interface Snippet {
+    prefix: string;
+    body: string;
+    detail?: string;
+}
+/**
+ * Load every snippet file in one language folder's `snippets/` subfolder.
+ *
+ * Never rejects, and never throws: a language with no snippets folder is the normal case, not an
+ * error, and one malformed file must not cost the others in the same folder.
+ */
+export declare function loadSnippets(languageId: string, languageDir: string): Promise<void>;
+/** Snippets for a language id (empty if none dropped in for it). */
+export declare function snippetsFor(languageId: string): Snippet[];

package/types/core/timeFormat.d.ts

@@ -0,0 +1,12 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** Format an "HH:mm" (24h storage) string for display in 12h or 24h. */
+export declare function fmtTime(hhmm: string, is12h: boolean): string;
+/** Format an epoch-ms timestamp's clock time (with seconds) for display. */
+export declare function fmtClock(ms: number, is12h: boolean): string;
+/** The app displays 12-hour time everywhere. */
+export declare function useTimeFormat(): boolean;
+/** Coarse relative time from an epoch-ms timestamp, e.g. "5 months ago", "just now". */
+export declare function fmtRelative(ms: number): string;
+export declare const useSettingBool: (key: string, fallback?: boolean) => boolean;
+export declare const useSettingString: (key: string, fallback?: string) => string;
+export declare const useSettingNumber: (key: string, fallback?: number) => number;

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

@@ -0,0 +1,80 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import { monaco } from "../../core/monaco";
+import { type EditorSettings } from "../../core/editorsettings";
+import type { DirtyRange } from "./tree";
+declare function MonacoEditorInner({ path, rel, value, onChange, onSave, gotoLine, gotoCol, gotoNonce, highlight, dirty, settings, onEditor }: {
+    path: string;
+    rel?: string | null;
+    value: string;
+    onChange: (v: string) => void;
+    onSave?: () => void;
+    gotoLine?: number;
+    gotoCol?: number;
+    gotoNonce?: number;
+    highlight?: {
+        query: string;
+        caseSensitive: boolean;
+        isRegex: boolean;
+        wholeWord: boolean;
+    } | null;
+    dirty?: DirtyRange[];
+    settings: EditorSettings;
+    /** Hands the live editor out, and null on unmount. For a formatting toolbar, which has to
+     *  dispatch into this instance rather than rewrite the string around it. */
+    onEditor?: (e: monaco.editor.IStandaloneCodeEditor | null) => void;
+}): import("react").JSX.Element;
+/**
+ * Monaco owns its buffer, so this component re-rendering achieves nothing on its own — yet it was
+ * re-rendering on every keystroke, because Editor re-renders per character and passes a new
+ * `value` and freshly-defined callbacks each time.
+ *
+ * The comparator ignores exactly the props that cannot affect what is on screen: every callback
+ * (each is read through a ref that is reassigned on render, so identity is already irrelevant) and
+ * `value` itself (the editor's text comes from its model, never from this prop after mount).
+ * What remains are the props that really do drive an effect.
+ */
+export declare const MonacoEditor: import("react").MemoExoticComponent<typeof MonacoEditorInner>;
+export declare function applyLineChanges(original: monaco.editor.ITextModel, modified: monaco.editor.ITextModel, diffs: monaco.editor.ILineChange[]): string;
+export interface HunkAction {
+    label: string;
+    unstage: boolean;
+    run: (change: monaco.editor.ILineChange, models: {
+        original: monaco.editor.ITextModel;
+        modified: monaco.editor.ITextModel;
+    }) => void;
+}
+/** A side of a diff: LEFT the old version, RIGHT the new — GitHub's names, which line comments use. */
+export type DiffSide = "LEFT" | "RIGHT";
+/**
+ * Line comments on a diff (a pull request's): a mark in the gutter for each thread, a click on a
+ * line number to start one, and a line to bring into view when a thread is picked from the list.
+ */
+export interface LineComments {
+    marks: {
+        line: number;
+        side: DiffSide;
+        resolved: boolean;
+    }[];
+    /** `other`: the same line on the other side when this one is unchanged, else null. */
+    onPick: (line: number, side: DiffSide, other: number | null) => void;
+    /** `n` changes to reveal again, even the same line. */
+    reveal?: {
+        line: number;
+        side: DiffSide;
+        n: number;
+    };
+}
+export declare function MonacoDiff({ path, head, work, sideBySide, readOnly, rev, onChange, onSave, hunkAction, lineComments }: {
+    path: string;
+    head: string;
+    work: string;
+    sideBySide: boolean;
+    readOnly: boolean;
+    rev: number;
+    onChange: (v: string) => void;
+    /** Ctrl+S from inside the diff. Without it an editable diff took edits and silently lost them. */
+    onSave?: () => void;
+    hunkAction?: HunkAction;
+    lineComments?: LineComments;
+}): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,2 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+export declare const GAP = "\u00A0\u00A0\u00A0\u00A0";

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

@@ -0,0 +1,13 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** A line change as Monaco's diff reports it: an end of 0 means that side's range is empty. */
+export interface LineChange {
+    originalStartLineNumber: number;
+    originalEndLineNumber: number;
+    modifiedStartLineNumber: number;
+    modifiedEndLineNumber: number;
+}
+/**
+ * The line on the other side of the diff that `line` on `side` is the same line as, or null when
+ * it is inside a change. GitLab needs both numbers to place a comment on an unchanged line.
+ */
+export declare function counterpartLine(changes: readonly LineChange[], line: number, side: "LEFT" | "RIGHT"): number | null;

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

@@ -0,0 +1,16 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+export interface EditorStatus {
+    line: number;
+    col: number;
+    errors: number;
+    warnings: number;
+    /** Blame for the cursor's line, for the status bar. null when unknown or uncommitted. */
+    blame?: {
+        hash: string;
+        author: string;
+        summary: string;
+    } | null;
+}
+export declare let editorStatus: EditorStatus;
+export declare function setEditorStatus(patch: Partial<EditorStatus>): void;
+export declare function useEditorStatus(): EditorStatus;

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

@@ -0,0 +1,8 @@
+// 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>;
+export declare function fileUri(path: string): monaco.Uri;
+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;
+export declare function remapModel(oldPath: string, newPath: string): void;

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

@@ -0,0 +1,59 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import type { GitStatusRow } from "../../core/bridge";
+/** Last path segment, trailing separators ignored. */
+export declare const baseName: (p: string) => string;
+/** Windows paths use both separators; normalize to "/" for comparison and display. */
+export declare const normPath: (p: string) => string;
+/** The folder a path is in. */
+export declare const dirName: (p: string) => string;
+/** A repo as a picker names it: its path under `root`, or its own name when it is not under it. */
+export declare function repoLabel(root: string, repo: string): string;
+export interface ChangeDir<T> {
+    kind: "dir";
+    name: string;
+    children: TreeNodeOf<T>[];
+}
+export interface ChangeFile<T> {
+    kind: "file";
+    row: T;
+    name: string;
+}
+export type TreeNodeOf<T> = ChangeDir<T> | ChangeFile<T>;
+export type ChangeTreeNode = TreeNodeOf<GitStatusRow>;
+/**
+ * Whether two git-status lists are the same, field by field.
+ *
+ * The poll returns a fresh array every few seconds, and a new reference re-renders the whole
+ * Changes list even when nothing changed. Order is part of the comparison: git reports a stable
+ * order, so a positional walk is enough and sorting first would cost more than the render.
+ */
+export declare function sameRows(a: readonly {
+    path: string;
+    rel: string;
+    letter: string;
+    staged: boolean;
+}[], b: readonly {
+    path: string;
+    rel: string;
+    letter: string;
+    staged: boolean;
+}[]): boolean;
+/**
+ * Group rows into a folder tree by their `rel` path.
+ *
+ * Generic in the leaf payload so the Commit panel builds the same tree from a commit's files
+ * (CommitFile) that Source Control builds from working-tree changes (GitStatusRow) — the shape
+ * and the single-child compression are identical, only the row type differs.
+ */
+export declare function buildChangeTree<T extends {
+    rel: string;
+}>(rows: T[]): TreeNodeOf<T>[];
+export interface DirtyRange {
+    start: number;
+    end: number;
+    type: "added" | "modified" | "deleted";
+}
+export declare function statusColor(letter: string): string;
+/** Flatten a tree node to the file rows underneath it (a file node is just itself). */
+export declare function collectFiles(node: ChangeTreeNode): GitStatusRow[];
+export declare function parseDirty(diff: string): DirtyRange[];

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

@@ -0,0 +1,41 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+export declare function mediaKind(path: string): "image" | "video" | "audio" | "font" | null;
+export declare function MediaViewer({ path, src: srcOverride }: {
+    path: string;
+    src?: string;
+}): import("react").JSX.Element;
+/**
+ * A media file's two versions, side by side: the committed one and the one on disk.
+ *
+ * Each side is a full MediaViewer, so an image still zooms and pans and a font still shows its
+ * specimen. A side with no bytes — the file was added, or deleted — says so rather than rendering
+ * a broken image, which is the difference between "no old version" and "it failed to load".
+ */
+export declare function MediaDiff({ path, oldBytes, newBytes, gone, oldLabel, newLabel }: {
+    path: string;
+    /** The committed bytes, or null when the file is not in that revision. */
+    oldBytes: Uint8Array | null;
+    /** The new side's bytes, when it is a revision too (a commit's diff) rather than the file on
+     *  disk. Empty: the file is not in that revision. Omitted: read the file at `path`. */
+    newBytes?: Uint8Array;
+    /** The working file was deleted — there is nothing on disk to show on the new side. */
+    gone: boolean;
+    oldLabel: string;
+    newLabel: string;
+}): import("react").JSX.Element;
+export declare function FontViewer({ src, name }: {
+    src: string;
+    name: string;
+}): import("react").JSX.Element;
+export declare function ImageViewer({ src, alt, bg }: {
+    src: string;
+    alt: string;
+    bg: string;
+}): import("react").JSX.Element;
+export declare const MarkdownPreview: import("react").NamedExoticComponent<{
+    text: string;
+}>;
+export declare function MonacoViewer({ content, language }: {
+    content: string;
+    language: string;
+}): import("react").JSX.Element;