deck-plugin-sdk 1.7.0 → 1.9.0

package/types/core/browser.d.ts

@@ -217,6 +217,8 @@ export declare function noteTermOutput(pane: string, chunk: string): void;
 export declare function forgetTermPane(pane: string): void;
 /** Where a pane's page is on screen, in Deck's CSS pixels, while it shows one. */
 export declare const pageBox: (pane: string) => DOMRect | null;
+/** The Deck window a pane's page is drawn in: the main one, or a floating tab window's. */
+export declare const paneWindow: (pane: string) => Window;
 /** Close the pane's webview to give back its memory, keeping the tab and its address. */
 export declare function discardBrowserPane(pane: string): Promise<void>;
 export declare function trackBrowser(pane: string, el: HTMLElement, url: string): () => void;

package/types/core/portal.d.ts

@@ -0,0 +1,3 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import { type ReactNode } from "react";
+export declare function createPortal(children: ReactNode, container: Element | DocumentFragment, key?: string | null): ReactNode;

package/types/core/terminals.d.ts

@@ -45,6 +45,12 @@ export interface LayoutTab {
     hidden?: boolean;
     /** The tab group it is in (LayoutWorkspace.groups); a group's tabs sit together in one zone. */
     group?: string;
+    /**
+     * Torn off into a window of its own (core/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;
 }
 export interface LayoutWorkspace {
     id: string;
@@ -57,9 +63,19 @@ export interface LayoutWorkspace {
     /** 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;
+}
 export interface Layout {
     workspaces: LayoutWorkspace[];
     activeWs: string;
+    floats?: FloatBounds[];
 }
 export declare function publishLayout(l: Layout): void;
 export declare function getLayout(): Layout | null;
@@ -202,6 +218,20 @@ export declare function showActiveTab(w: LayoutWorkspace): LayoutWorkspace;
  * the zone nor back to its first tab; otherwise the first zone left.
  */
 export declare function nextActiveAfterClose(tabs: readonly LayoutTab[], closing: string): string | undefined;
+/**
+ * Tear a tab off into window `win`, or (`win` undefined) dock it back. A workspace always keeps
+ * one docked tab: floating its last one leaves a fresh terminal behind, as the main window has
+ * to show something. Tearing off the active tab makes its neighbour active.
+ */
+export declare function setTabWindow(w: LayoutWorkspace, tabId: string, win: string | undefined, keepGroup?: boolean): LayoutWorkspace;
+/**
+ * Merge floating window `from`'s tabs into another window: floating window `into`, or (`into`
+ * null) the main window, into the active zone of the project it shows. They go in behind the tab
+ * that window shows, which stays shown: a tab dropped somewhere does not take you away from the one
+ * you were on. The tabs move between projects when the window they land in shows another one's,
+ * since a window holds one project's tabs.
+ */
+export declare function mergeWindow(l: Layout, from: string, into: string | null): Layout;
 /** The first free spot on the top row, for a zone created without a position of its own. */
 export declare function nextZoneSpot(tabs: readonly LayoutTab[], cols?: number, rows?: number): {
     x: number;
@@ -431,6 +461,12 @@ export declare function sendInput(paneId: string, text: string): void;
  * layout and re-fires the observer that called us. Measuring first and resizing once — only when
  * the size actually differs — means the observer's next pass finds nothing to do and it settles.
  */
+/**
+ * The terminals drawn in `doc` take its window's scale again: its window moved onto a monitor of
+ * other scaling (a floating window reopened where it was, or dragged there). The same hand-over
+ * as a move between windows (see attach).
+ */
+export declare function rebindTerminals(doc: Document): void;
 export declare function refit(id: string): void;
 /**
  * Clear the screen, the way the shell expects.

package/types/core/windows.d.ts

@@ -0,0 +1,52 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+type Cleanup = void | (() => void);
+type Hook = (win: Window) => Cleanup;
+/** Every Deck window: the main one, then each floating one. */
+export declare const allWindows: () => Window[];
+/**
+ * A Deck window's Tauri label: "main", or a floating window's (floatwin.rs). A floating window is
+ * only registered here once its label exists, so every hook can rely on it.
+ */
+export declare function windowLabel(w: Window): string;
+/**
+ * Whether `x` is an element, in any Deck window. Not `instanceof Element`: an element in a
+ * floating window is an instance of THAT window's Element, so the main window's check is false.
+ */
+export declare function isElement(x: unknown): x is Element;
+/**
+ * A ResizeObserver from the window `el` is drawn in. One made by the main window watches an element
+ * in a floating window only when the main window next draws, so a terminal opened in a float that
+ * waited for its size could sit blank for seconds.
+ */
+export declare function resizeObserverFor(el: Element, cb: ResizeObserverCallback): ResizeObserver;
+/** The window an element is drawn in: the main one, or a floating window's. */
+export declare function winOf(el: Element | null | undefined): Window;
+/**
+ * The Deck window the user is in: the one they last clicked, typed or moved focus in. Not
+ * document.hasFocus() alone: with a floating window in front, the main window's document still
+ * says it has focus too (WebView2, for a popup it opened), so the first match was always main.
+ */
+export declare function activeWindow(): Window;
+/** What has focus in the window the user is in: what `document.activeElement` means in one window. */
+export declare function activeElement(): Element | null;
+/** Run `fn` for every Deck window, now and as floats open; what it returns runs when that window goes, or on the returned unsubscribe. */
+export declare function onEachWindow(fn: Hook): () => void;
+/** A floating window opened (floatwin.ts), its label known: every hook runs for it. */
+export declare function addWindow(win: Window): void;
+/** A floating window is going: what each hook installed in it is undone. */
+export declare function removeWindow(win: Window): void;
+/**
+ * Listen on every Deck window (or every window's document), now and as floats open; returns the
+ * unsubscribe. For what closes a menu or a dialog wherever the user is: Escape, a click outside.
+ */
+export declare function onAll<K extends keyof WindowEventMap>(type: K, fn: (e: WindowEventMap[K]) => void, opts?: boolean | AddEventListenerOptions, on?: "window" | "document"): () => void;
+/**
+ * Make the main realm's `navigator.clipboard` work from every Deck window. The browser refuses a
+ * clipboard call from a document that does not have focus ("Document is not focused"), and the
+ * realm's clipboard is the MAIN window's: while the user works in a floating window, every copy and
+ * paste failed, a terminal's Ctrl+C clearing the selection with nothing copied. Each call now goes
+ * to the clipboard of the window the user is in, which is main's own when that is where they are.
+ * Installed once, before plugins load, so their copies and pastes get it too.
+ */
+export declare function routeClipboard(): void;
+export {};

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

@@ -13,6 +13,12 @@ export declare function fileUri(path: string): monaco.Uri;
 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;
+/**
+ * Put `value` into `m` as the one edit between their common start and end, rather than replacing
+ * the whole text: a cursor outside the change stays where it is. A whole-text replace (setValue, or
+ * an edit over the full range) moved every cursor to the top of the file, mid-typing.
+ */
+export declare function replaceText(m: monaco.editor.ITextModel, value: string): void;
 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;

package/validate.mjs

@@ -0,0 +1,112 @@
+// The checks a package must pass to be published, that need nothing but its files: shared by
+// `deck-plugin publish` (which runs them before anything leaves the machine) and the registry's
+// own validation (deck-registry's tools/validate.mjs, which adds what needs GitHub: who owns it,
+// the release, the rebuild). One copy, so the two cannot disagree about what is valid.
+//
+// Pure: no network, no filesystem.
+
+/** Deck's own modules and the view prefixes: a plugin with one of these ids could never load. */
+export const RESERVED = new Set(["terminals", "editor", "docs", "settings", "deck", "module", "plugin", "browser"]);
+/**
+ * Packages the registry's rebuild executes. Each must be the real one from npm, since the rebuild
+ * runs on a machine that can merge; see the SECURITY note in deck-registry's tools/validate.mjs.
+ */
+export const BUILD_RUNS = ["deck-plugin-sdk", "esbuild", "react", "lucide-react", "framer-motion"];
+export const MAX_FILE = 10 * 1024 * 1024, MAX_TOTAL = 15 * 1024 * 1024;
+export const ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+export const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+
+/** A file's name as a release asset: flat, so a language's snippets/x.json is snippets--x.json. */
+export const assetName = (name) => name.replace(/\//g, "--");
+
+export function compareVersions(a, b) {
+  const x = SEMVER.exec(a), y = SEMVER.exec(b);
+  for (let i = 1; i <= 3; i++) if (Number(x[i]) !== Number(y[i])) return Number(x[i]) - Number(y[i]);
+  if (x[4] === y[4]) return 0;
+  return x[4] === undefined ? 1 : y[4] === undefined ? -1 : x[4] < y[4] ? -1 : 1;
+}
+
+/** An id: its shape, and not one of Deck's own. */
+export function checkId(id) {
+  const errors = [];
+  if (!ID.test(id)) errors.push(`the id \`${id}\` must be lowercase letters, digits and dashes, 40 at most`);
+  if (RESERVED.has(id)) errors.push(`\`${id}\` is one of Deck's own names and cannot be a package id`);
+  return errors;
+}
+
+/** A plugin's plugin.json, for publishing: what the registry shows and what Deck needs. */
+export function checkManifest(m) {
+  const errors = [];
+  if (typeof m.name !== "string" || !m.name.trim() || m.name.length > 60) errors.push("the name must be 1 to 60 characters");
+  if (typeof m.description !== "string" || m.description.trim().length < 10 || m.description.length > 300) {
+    errors.push("the description must be 10 to 300 characters");
+  }
+  if (typeof m.version !== "string" || !SEMVER.test(m.version)) errors.push("`version` must be a version, such as \"1.0.0\"");
+  if (typeof m.minDeck !== "string" || !SEMVER.test(m.minDeck)) errors.push("`minDeck` must say which Deck it needs, such as \"1.8.0\"");
+  if (m.color !== undefined && !/^#[0-9a-f]{6}$/i.test(m.color)) errors.push("`color` must be #rrggbb");
+  return errors;
+}
+
+/** The release's files: the allowed names, the required ones, and the size limits. */
+export function checkAssets(kind, assets) {
+  const errors = [];
+  const ok = (n) => kind === "plugin" ? ["plugin.json", "plugin.js", "mcp.js"].includes(n) : n === "language.json" || /^snippets--[\w.-]+\.json$/.test(n);
+  for (const a of assets) if (!ok(a.name)) errors.push(`the release has \`${a.name}\`, which a ${kind} cannot contain`);
+  for (const need of kind === "plugin" ? ["plugin.json", "plugin.js"] : ["language.json"]) {
+    if (!assets.some((a) => a.name === need)) errors.push(`the release has no \`${need}\``);
+  }
+  for (const a of assets) if (a.size > MAX_FILE) errors.push(`\`${a.name}\` is ${(a.size / 1048576).toFixed(1)} MB; a file may be 10 MB at most`);
+  const total = assets.reduce((n, a) => n + a.size, 0);
+  if (total > MAX_TOTAL) errors.push(`the release is ${(total / 1048576).toFixed(1)} MB; a package may be 15 MB at most`);
+  for (const a of assets) if ("digest" in a && !/^sha256:[0-9a-f]{64}$/.test(a.digest ?? "")) errors.push(`GitHub gives no sha256 for \`${a.name}\`; upload it again`);
+  return errors;
+}
+
+/** Whether a lockfile lets `npm ci` install only published npm packages. */
+export function checkLockfile(lock) {
+  const errors = [];
+  if (!lock || lock.lockfileVersion < 2 || typeof lock.packages !== "object") return ["package-lock.json must be npm 7 or newer (lockfileVersion 2 or 3)"];
+  for (const [path, p] of Object.entries(lock.packages)) {
+    if (path === "") continue;
+    if (p.link) { errors.push(`\`${path}\` is a link to a folder; publish it to npm or bundle it`); continue; }
+    if (!p.resolved?.startsWith("https://registry.npmjs.org/") || !/^sha(512|384|256)-/.test(p.integrity ?? "")) {
+      errors.push(`\`${path}\` does not come from registry.npmjs.org with an integrity hash`);
+    }
+    const name = path.replace(/^.*node_modules\//, "");
+    const runs = BUILD_RUNS.includes(name) || name.startsWith("@esbuild/");
+    if (runs && p.name && p.name !== name) errors.push(`\`${name}\` is an alias of \`${p.name}\`; the build runs it, so it must be the real package`);
+  }
+  if (!lock.packages["node_modules/deck-plugin-sdk"]) errors.push("the lockfile has no deck-plugin-sdk; a plugin is built with it");
+  return errors;
+}
+
+/**
+ * What a plugin's permissions must be, from its manifest and its bundle (`table` is the SDK's
+ * permissions.json): only known names, and covering every bridge call the bundle makes. The shim
+ * calls the bridge as `b().fsWrite(`, which minifying keeps, so `().fn(` is the pattern, and a
+ * method of the same name on something else (a RegExp's .exec) does not count. Reaching Deck's
+ * internals directly, around the bridge, is refused outright.
+ */
+export function checkPermissions(declared, bundle, table) {
+  const errors = [], notes = [];
+  if (!Array.isArray(declared)) {
+    return { errors: ['plugin.json must say what it uses: "permissions": [...], or [] when it needs nothing beyond its own data and settings'], notes };
+  }
+  const unknown = declared.filter((p) => !(p in table.permissions));
+  if (unknown.length) errors.push(`unknown permission${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")} (known: ${Object.keys(table.permissions).join(", ")})`);
+  if (/__TAURI_INTERNALS__|__TAURI_IPC__|window\.__TAURI__\b/.test(bundle)) {
+    errors.push("its bundle reaches Deck's internals directly, around the bridge its permissions apply to");
+  }
+  const needs = new Map();
+  for (const [fn, p] of Object.entries(table.bridge)) {
+    if (new RegExp(`\\(\\)\\.${fn}\\(`).test(bundle)) needs.set(p, [...(needs.get(p) ?? []), fn]);
+  }
+  for (const [mod, p] of Object.entries(table.modules)) {
+    if (new RegExp(`__deck\\?\\.${mod}\\b`).test(bundle)) needs.set(p, [...(needs.get(p) ?? []), mod]);
+  }
+  for (const [p, fns] of needs) {
+    if (!declared.includes(p)) errors.push(`it uses ${fns.slice(0, 4).join(", ")}${fns.length > 4 ? ` and ${fns.length - 4} more` : ""}, which ${fns.length > 1 ? "need" : "needs"} the "${p}" permission; add it to "permissions"`);
+  }
+  if (/\beval\(|new Function\(/.test(bundle)) notes.push("Its bundle uses eval or new Function, which runs code made at run time; a library may do this legitimately.");
+  return { errors, notes };
+}