deck-plugin-sdk 0.22.0 → 1.2.0

package/types/core/p2p.d.ts

@@ -0,0 +1,117 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** What can travel: anything JSON can carry. */
+export type Json = string | number | boolean | null | Json[] | {
+    [k: string]: Json;
+};
+/** Whether someone may change what is shared, or only watch. */
+export type Mode = "edit" | "view";
+/** Who may change things: a default for everyone, and a choice per person that wins over it. */
+export interface Roles {
+    def: Mode;
+    per: Record<string, Mode>;
+}
+/** Why a share ended for a joiner: the host stopped, vanished, removed this Deck, turned it away,
+ *  or speaks another version. */
+export type Gone = "ended" | "lost" | "removed" | "denied" | "version";
+export interface Person {
+    id: string;
+    name: string; /** Round trip in ms, once measured. */
+    ms?: number;
+}
+/** What a share's bar and dialogs show. Replaced, never mutated, so React sees a change. */
+export interface ShareView {
+    /** Who is in and connected: on the host, everyone let in; on a joiner, the host and the others. */
+    peers: Person[];
+    /** On the host: who is asking to be let in. */
+    knocking: Person[];
+    /** On a joiner: the host is there but has not let this Deck in yet. */
+    waiting: boolean;
+    /** On a joiner: no host heard from for a while (wrong code, or a network that blocks it). */
+    stuck: boolean;
+    gone: Gone | null;
+    hostName: string;
+    /** A passing line: someone on another version, or whatever the plugin `say`s. */
+    note: string;
+    roles: Roles;
+    /** Whether this Deck may change things. */
+    canEdit: boolean;
+}
+export interface ShareOptions {
+    /** What the share is for, e.g. "canvas-share". Decks only meet others using the same one. */
+    app: string;
+    /** The share code, which names the room (see newCode). */
+    code: string;
+    /** Optional extra secret, needed with the code to connect at all. Sharing works without one. */
+    password?: string;
+    /** The plugin's message channel, at most 12 bytes (Trystero's cap). Defaults to "msg". */
+    channel?: string;
+    /** Whether this Deck is the one sharing. */
+    host: boolean;
+    /** Shown to the others: in the host's knock, on cursors, in the list of who is here. */
+    name: string;
+    /** The plugin's own protocol version. Decks on different versions do not share. */
+    version: number;
+    /** The host's default for who may change things. Joiners may until the host says otherwise. */
+    mode?: Mode;
+}
+export interface ShareHandlers<T> {
+    /** A plugin message, only ever from someone let in (and the host). Check `mayEdit(peer)` before
+     *  applying a change: a view-only person's edits are to be dropped by every Deck. */
+    message: (msg: T, peer: string) => void;
+    /** On the host: someone was just let in. Send them what they need to start, e.g. the board. */
+    welcome?: (peer: string) => void;
+    /** Someone left or was removed: forget what was kept for them (a cursor). */
+    left?: (peer: string) => void;
+}
+export interface P2pShare<T> {
+    readonly host: boolean;
+    /** Send a plugin message to everyone let in, or to one of them. Sends nothing before this Deck is
+     *  let in. Settles once handed to the connection, so awaiting it paces the sender. */
+    send(msg: T, to?: string): Promise<void>;
+    /** Whether a peer may change things: the host always, anyone else by the roles. */
+    mayEdit(peer: string): boolean;
+    /** The host: let someone in, or turn them away. */
+    allow(peer: string): void;
+    deny(peer: string): void;
+    /** The host: remove someone who was let in. They cannot come back with the same Deck. */
+    kick(peer: string): void;
+    /** The host: everyone's default, and one person's own choice (`null` follows the default). */
+    setDefault(mode: Mode): void;
+    setPerson(peer: string, mode: Mode | null): void;
+    /** Show a passing line in the view for a few seconds. */
+    say(note: string): void;
+    /** Leave. With `announce` (the host ending on purpose) everyone is told first, so they end at
+     *  once rather than when the connection times out. Safe to call twice. */
+    close(announce?: boolean): Promise<void>;
+    /** For useSyncExternalStore. */
+    subscribe(fn: () => void): () => void;
+    getView(): ShareView;
+}
+/** The part of a Trystero room a share uses: a seam, so the check can run a share without a network. */
+export interface RoomLike {
+    /** This Deck's id in the room; Trystero's own is `selfId()`. */
+    selfId?: string;
+    makeAction(name: string, config: {
+        onMessage: (data: any, ctx: {
+            peerId: string;
+        }) => void;
+    }): {
+        send(data: any, options?: {
+            target?: string | string[];
+        }): Promise<void>;
+    };
+    ping(peer: string): Promise<number>;
+    leave(): Promise<void>;
+    getPeers(): Record<string, unknown>;
+    onPeerJoin: ((peer: string) => void) | null;
+    onPeerLeave: ((peer: string) => void) | null;
+}
+/** This Deck's id in every share: the one the others know it by. The same for the whole session,
+ *  so someone let in who rejoins after a dropped connection is let straight back in. */
+export declare function selfId(): string;
+/** Start sharing (`host`), or ask to join someone's share. */
+export declare function share<T extends Json>(opts: ShareOptions, on: ShareHandlers<T>, room?: RoomLike): P2pShare<T>;
+/** A share code: 16 random characters in four groups, easy to read out or paste. */
+export declare function newCode(random?: (n: number) => Uint8Array): string;
+/** A pasted code, tidied: spaces dropped, case folded. Empty when it is not a code. */
+export declare function cleanCode(text: string): string;

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,4 +13,5 @@ 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;
+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;