deck-plugin-sdk 1.4.0 → 1.5.0

package/packages.mjs

@@ -0,0 +1,107 @@
+// What a plugin's npm packages need from the build. Shared by Deck's own plugin build
+// (sdk/shim-builder.mjs, which makes the shim) and the SDK's (sdk/build-plugin.mjs), so the two cannot disagree.
+//
+// A plugin is installed as plugin.json and one plugin.js, so everything a package brings has to
+// end up inside that one file: a sidecar image, font or stylesheet would never be installed.
+//
+// "The plugin's own code" is what is under its src/. Anything else is a package, whether it sits
+// in node_modules or is linked in from another folder (`npm install ../my-lib`).
+import { build } from "esbuild";
+import { readFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+
+/** Images and fonts the plugin or a package imports, inlined as data: URLs. */
+export const assetLoaders = Object.fromEntries(
+  [".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".bmp", ".ico", ".svg", ".woff", ".woff2", ".ttf", ".otf", ".eot"]
+    .map((ext) => [ext, "dataurl"]),
+);
+
+const under = (path, dir) => !!path && (path + sep).toLowerCase().startsWith((dir + sep).toLowerCase());
+
+/**
+ * Whether an import of Deck's shared icons or animation library comes from a package rather than
+ * the plugin's own code. The plugin's own imports go to Deck's copies, through a shim that names
+ * only the exports its `src/` uses; a package's would find its names missing there, so a package
+ * gets the real library, bundled and tree-shaken like any other dependency.
+ */
+export const fromPackage = (args, dir) =>
+  (args.path === "lucide-react" || args.path === "framer-motion") && !!args.importer && !under(args.importer, join(dir, "src"));
+
+/** `import "x.css"` with nothing bound: imported for its effect, so it is applied. */
+function importedBare(importer, spec) {
+  let text;
+  try { text = readFileSync(importer, "utf8"); } catch { return false; }
+  const q = spec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(^|[;\\n])\\s*import\\s*["']${q}["']`).test(text);
+}
+
+/**
+ * CSS imported for its effect is applied: CSS a package imports, and CSS any code imports with
+ * nothing bound (`import "some-lib/styles.css"`, `import "@fontsource/inter"`). It is bundled
+ * with its `@import`s and the images and fonts its `url()`s name, and added to the page as one
+ * <style> per file, replaced rather than duplicated when the plugin reloads.
+ *
+ * `import css from "./x.css"` in the plugin's own code still gives it the text, to inject where and
+ * when it wants (the canvas plugin does that with Excalidraw's stylesheet).
+ */
+export function packageCss(pluginId, dir) {
+  const src = join(dir, "src");
+  return {
+    name: "deck-package-css",
+    setup(b) {
+      b.onResolve({ filter: /.*/ }, async (args) => {
+        if (args.pluginData?.css || (args.kind !== "import-statement" && args.kind !== "require-call")) return undefined;
+        // The plugin's own code: a bare import, which may name a package whose entry is a
+        // stylesheet (@fontsource/inter). A package's: any import of a .css file.
+        const own = under(args.importer, src);
+        if (!(own ? importedBare(args.importer, args.path) : /\.css$/.test(args.path))) return undefined;
+        const r = await b.resolve(args.path, { kind: args.kind, resolveDir: args.resolveDir, importer: args.importer, pluginData: { css: true } });
+        if (r.errors.length) return { errors: r.errors };
+        if (!/\.css$/.test(r.path)) return undefined;
+        return { path: r.path, namespace: "deck-package-css" };
+      });
+      b.onLoad({ filter: /.*/, namespace: "deck-package-css" }, async (args) => {
+        const out = await build({ entryPoints: [args.path], outfile: "package.css", bundle: true, write: false, minify: true, loader: assetLoaders, logLevel: "silent" });
+        const css = out.outputFiles.find((f) => f.path.endsWith(".css"))?.text ?? "";
+        // Named by where it is inside the project, not on this machine: the bundle is shared.
+        const where = /[\\/]node_modules[\\/]/.test(args.path) ? args.path.replace(/^.*[\\/]node_modules[\\/]/, "") : relative(dir, args.path);
+        const key = `${pluginId}:${where.replace(/\\/g, "/")}`;
+        return {
+          resolveDir: dirname(args.path),
+          loader: "js",
+          contents: `const css = ${JSON.stringify(css)};
+if (typeof document !== "undefined") {
+  const key = ${JSON.stringify(key)};
+  let s = [...document.head.querySelectorAll("style[data-deck-css]")].find((e) => e.dataset.deckCss === key);
+  if (!s) { s = document.createElement("style"); s.dataset.deckCss = key; document.head.appendChild(s); }
+  s.textContent = css;
+}
+export default css;
+`,
+        };
+      });
+    },
+  };
+}
+
+/**
+ * `import text from "some/file?raw"` gives a file's contents as a string, the convention Vite
+ * uses. What a library needs as text rather than as code: PDF.js's worker, which a plugin starts
+ * from a Blob URL because only plugin.js is installed (see the Requests plugin's script worker).
+ *
+ * `?base64` gives any file's bytes as a base64 string instead: data a library asks for only
+ * sometimes (PDF.js's font files and image decoders), decoded when it does rather than every time
+ * Deck starts, as a `.wasm` import would be.
+ */
+export const rawImports = {
+  name: "deck-raw",
+  setup(b) {
+    b.onResolve({ filter: /\?(raw|base64)$/ }, async (args) => {
+      const as = args.path.endsWith("?raw") ? "text" : "base64";
+      const r = await b.resolve(args.path.replace(/\?(raw|base64)$/, ""), { kind: args.kind, resolveDir: args.resolveDir, importer: args.importer });
+      if (r.errors.length) return { errors: r.errors };
+      return { path: r.path, namespace: "deck-raw", pluginData: { as } };
+    });
+    b.onLoad({ filter: /.*/, namespace: "deck-raw" }, (args) => ({ contents: readFileSync(args.path), loader: args.pluginData?.as === "base64" ? "base64" : "text" }));
+  },
+};

package/shim/bridge.js

@@ -3,6 +3,7 @@
 // Deck's bridge. Everything resolves at USE time, never at import time: a plugin module is
 // evaluated during loadPlugins, and a reference copied out then would capture a half-built
 // object. Functions forward their arguments; plain values are proxied.
+import { pluginId, scoped } from "./scope.js";
 const b = () => {
   const x = window.__deck?.bridge;
   if (!x) throw new Error("window.__deck.bridge is missing — this plugin only runs inside Deck");
@@ -15,20 +16,18 @@ export const askSudoPassword = (...a) => b().askSudoPassword(...a);
 export const backupExport = (...a) => b().backupExport(...a);
 export const backupInspect = (...a) => b().backupInspect(...a);
 export const backupRestore = (...a) => b().backupRestore(...a);
-export const claudeMcpEntry = (...a) => b().claudeMcpEntry(...a);
-export const claudeMcpStatus = (...a) => b().claudeMcpStatus(...a);
 export const claudePlanLimits = (...a) => b().claudePlanLimits(...a);
 export const claudeUsage = (...a) => b().claudeUsage(...a);
 export const clearWallpaper = (...a) => b().clearWallpaper(...a);
-export const closeApp = (...a) => b().closeApp(...a);
-export const configRead = (...a) => b().configRead(...a);
-export const configWrite = (...a) => b().configWrite(...a);
+export const configDelete = (name, ...a) => b().configDelete(scoped(name), ...a);
+export const configRead = (name, ...a) => b().configRead(scoped(name), ...a);
+export const configWrite = (name, ...a) => b().configWrite(scoped(name), ...a);
 export const convertFileSrc = (...a) => b().convertFileSrc(...a);
+export const dataDir = () => b().dataDir(pluginId);
 export const dbConnect = (...a) => b().dbConnect(...a);
 export const dbDisconnect = (...a) => b().dbDisconnect(...a);
 export const dbQuery = (...a) => b().dbQuery(...a);
 export const dbSchema = (...a) => b().dbSchema(...a);
-export const defaultDownloadDir = (...a) => b().defaultDownloadDir(...a);
 export const deleteIconPack = (...a) => b().deleteIconPack(...a);
 export const dirsDownload = (...a) => b().dirsDownload(...a);
 export const exec = (...a) => b().exec(...a);
@@ -57,82 +56,35 @@ export const fsTrash = (...a) => b().fsTrash(...a);
 export const fsWrite = (...a) => b().fsWrite(...a);
 export const fsWriteBytes = (...a) => b().fsWriteBytes(...a);
 export const getAutostart = (...a) => b().getAutostart(...a);
-export const getVaultRoot = (...a) => b().getVaultRoot(...a);
 export const ghPrLineComment = (...a) => b().ghPrLineComment(...a);
 export const ghPrThreads = (...a) => b().ghPrThreads(...a);
 export const ghRun = (...a) => b().ghRun(...a);
 export const ghThreadReply = (...a) => b().ghThreadReply(...a);
 export const ghThreadResolve = (...a) => b().ghThreadResolve(...a);
-export const gitAbortOp = (...a) => b().gitAbortOp(...a);
 export const gitAiCommitMsg = (...a) => b().gitAiCommitMsg(...a);
 export const gitBlameLine = (...a) => b().gitBlameLine(...a);
-export const gitBranchAt = (...a) => b().gitBranchAt(...a);
-export const gitBranchDelete = (...a) => b().gitBranchDelete(...a);
-export const gitBranchDeleteRemote = (...a) => b().gitBranchDeleteRemote(...a);
-export const gitBranchRename = (...a) => b().gitBranchRename(...a);
-export const gitBranches = (...a) => b().gitBranches(...a);
 export const gitCheckout = (...a) => b().gitCheckout(...a);
 export const gitCheckoutDetach = (...a) => b().gitCheckoutDetach(...a);
 export const gitCheckoutNew = (...a) => b().gitCheckoutNew(...a);
 export const gitCheckoutTrack = (...a) => b().gitCheckoutTrack(...a);
-export const gitCherryPick = (...a) => b().gitCherryPick(...a);
-export const gitCommit = (...a) => b().gitCommit(...a);
-export const gitCommitAmend = (...a) => b().gitCommitAmend(...a);
 export const gitCommitFiles = (...a) => b().gitCommitFiles(...a);
-export const gitContinueOp = (...a) => b().gitContinueOp(...a);
 export const gitDiscard = (...a) => b().gitDiscard(...a);
-export const gitFetch = (...a) => b().gitFetch(...a);
-export const gitFetchPr = (...a) => b().gitFetchPr(...a);
 export const gitFileBytes = (...a) => b().gitFileBytes(...a);
 export const gitFileDiff = (...a) => b().gitFileDiff(...a);
-export const gitHead = (...a) => b().gitHead(...a);
-export const gitHeadFile = (...a) => b().gitHeadFile(...a);
-export const gitIndexFile = (...a) => b().gitIndexFile(...a);
 export const gitInfo = (...a) => b().gitInfo(...a);
 export const gitLogGraph = (...a) => b().gitLogGraph(...a);
-export const gitMerge = (...a) => b().gitMerge(...a);
-export const gitMergeAs = (...a) => b().gitMergeAs(...a);
-export const gitMergeBase = (...a) => b().gitMergeBase(...a);
-export const gitPendingOp = (...a) => b().gitPendingOp(...a);
 export const gitPoll = (...a) => b().gitPoll(...a);
-export const gitPull = (...a) => b().gitPull(...a);
-export const gitPullRebase = (...a) => b().gitPullRebase(...a);
-export const gitPush = (...a) => b().gitPush(...a);
-export const gitPushBranch = (...a) => b().gitPushBranch(...a);
 export const gitRangeFiles = (...a) => b().gitRangeFiles(...a);
-export const gitRangeSubjects = (...a) => b().gitRangeSubjects(...a);
-export const gitRebase = (...a) => b().gitRebase(...a);
 export const gitRefs = (...a) => b().gitRefs(...a);
-export const gitRemoteUrl = (...a) => b().gitRemoteUrl(...a);
-export const gitRemotes = (...a) => b().gitRemotes(...a);
 export const gitRepos = (...a) => b().gitRepos(...a);
-export const gitResetTo = (...a) => b().gitResetTo(...a);
-export const gitRevert = (...a) => b().gitRevert(...a);
-export const gitShowFile = (...a) => b().gitShowFile(...a);
-export const gitStage = (...a) => b().gitStage(...a);
-export const gitStageContent = (...a) => b().gitStageContent(...a);
-export const gitStash = (...a) => b().gitStash(...a);
-export const gitStashApply = (...a) => b().gitStashApply(...a);
-export const gitStashClear = (...a) => b().gitStashClear(...a);
-export const gitStashDrop = (...a) => b().gitStashDrop(...a);
-export const gitStashList = (...a) => b().gitStashList(...a);
-export const gitStashPop = (...a) => b().gitStashPop(...a);
-export const gitStashShow = (...a) => b().gitStashShow(...a);
+export const gitRun = (...a) => b().gitRun(...a);
 export const gitStatus = (...a) => b().gitStatus(...a);
-export const gitTag = (...a) => b().gitTag(...a);
-export const gitTagDelete = (...a) => b().gitTagDelete(...a);
-export const gitTagDeleteRemote = (...a) => b().gitTagDeleteRemote(...a);
-export const gitTagPush = (...a) => b().gitTagPush(...a);
-export const gitUndoCommit = (...a) => b().gitUndoCommit(...a);
-export const gitUnstage = (...a) => b().gitUnstage(...a);
 export const glabApi = (...a) => b().glabApi(...a);
 export const glabRun = (...a) => b().glabRun(...a);
 export const googleAccount = (...a) => b().googleAccount(...a);
 export const googleSignIn = (...a) => b().googleSignIn(...a);
 export const googleSignOut = (...a) => b().googleSignOut(...a);
 export const googleToken = (...a) => b().googleToken(...a);
-export const historyClear = (...a) => b().historyClear(...a);
-export const historyDelete = (...a) => b().historyDelete(...a);
 export const httpCancel = (...a) => b().httpCancel(...a);
 export const httpSend = (...a) => b().httpSend(...a);
 export const httpSendAs = (...a) => b().httpSendAs(...a);
@@ -141,29 +93,21 @@ export const importIconPack = (...a) => b().importIconPack(...a);
 export const installAgentHooks = (...a) => b().installAgentHooks(...a);
 export const installAgentMcp = (...a) => b().installAgentMcp(...a);
 export const installAgentSkills = (...a) => b().installAgentSkills(...a);
-export const installClaudeHooks = (...a) => b().installClaudeHooks(...a);
-export const installClaudeMcp = (...a) => b().installClaudeMcp(...a);
 export const installFromRegistry = (...a) => b().installFromRegistry(...a);
-export const installPlugin = (...a) => b().installPlugin(...a);
 export const isFullscreen = (...a) => b().isFullscreen(...a);
 export const languagesDir = (...a) => b().languagesDir(...a);
 export const launchFiles = (...a) => b().launchFiles(...a);
 export const listApps = (...a) => b().listApps(...a);
 export const listInstalled = (...a) => b().listInstalled(...a);
+export const logLatest = (...a) => b().logLatest(...a);
 export const mediaMeta = (...a) => b().mediaMeta(...a);
 export const mediaSetNowPlaying = (...a) => b().mediaSetNowPlaying(...a);
 export const mediaSetPlayback = (...a) => b().mediaSetPlayback(...a);
 export const memUsage = (...a) => b().memUsage(...a);
-export const notesDelete = (...a) => b().notesDelete(...a);
-export const notesList = (...a) => b().notesList(...a);
-export const notesRead = (...a) => b().notesRead(...a);
-export const notesRename = (...a) => b().notesRename(...a);
-export const notesScope = (...a) => b().notesScope(...a);
-export const notesWrite = (...a) => b().notesWrite(...a);
 export const notifyOs = (...a) => b().notifyOs(...a);
-export const openApp = (...a) => b().openApp(...a);
 export const openExternal = (...a) => b().openExternal(...a);
 export const openFile = (...a) => b().openFile(...a);
+export const openTestDeck = (...a) => b().openTestDeck(...a);
 export const pickAnyFile = (...a) => b().pickAnyFile(...a);
 export const pickExe = (...a) => b().pickExe(...a);
 export const pickFile = (...a) => b().pickFile(...a);
@@ -172,24 +116,15 @@ export const pickImage = (...a) => b().pickImage(...a);
 export const pickSavePath = (...a) => b().pickSavePath(...a);
 export const pickScript = (...a) => b().pickScript(...a);
 export const pluginsDir = (...a) => b().pluginsDir(...a);
-export const powerAction = (...a) => b().powerAction(...a);
 export const procKill = (...a) => b().procKill(...a);
 export const procStream = (...a) => b().procStream(...a);
 export const procWrite = (...a) => b().procWrite(...a);
-export const readDownloads = (...a) => b().readDownloads(...a);
 export const readIconPackTheme = (...a) => b().readIconPackTheme(...a);
-export const readLibrary = (...a) => b().readLibrary(...a);
-export const readMusicSuggestions = (...a) => b().readMusicSuggestions(...a);
-export const readMusicTaste = (...a) => b().readMusicTaste(...a);
 export const readTermLayout = (...a) => b().readTermLayout(...a);
 export const readTrackMeta = (...a) => b().readTrackMeta(...a);
 export const remoteHome = (...a) => b().remoteHome(...a);
 export const remoteStat = (...a) => b().remoteStat(...a);
 export const remoteSudoPassword = (...a) => b().remoteSudoPassword(...a);
-export const removeAgentHooks = (...a) => b().removeAgentHooks(...a);
-export const removeAgentMcp = (...a) => b().removeAgentMcp(...a);
-export const removeClaudeHooks = (...a) => b().removeClaudeHooks(...a);
-export const removeClaudeMcp = (...a) => b().removeClaudeMcp(...a);
 export const removeLanguage = (...a) => b().removeLanguage(...a);
 export const restartApp = (...a) => b().restartApp(...a);
 export const revealInFolder = (...a) => b().revealInFolder(...a);
@@ -197,37 +132,20 @@ export const runScriptNow = (...a) => b().runScriptNow(...a);
 export const sessionList = (...a) => b().sessionList(...a);
 export const setAutostart = (...a) => b().setAutostart(...a);
 export const setDebugTargets = (...a) => b().setDebugTargets(...a);
-export const setVaultRoot = (...a) => b().setVaultRoot(...a);
 export const setWallpaper = (...a) => b().setWallpaper(...a);
 export const sshHosts = (...a) => b().sshHosts(...a);
 export const sshTunnelClose = (...a) => b().sshTunnelClose(...a);
-export const sshTunnelList = (...a) => b().sshTunnelList(...a);
 export const sshTunnelOpen = (...a) => b().sshTunnelOpen(...a);
 export const startupMarks = (...a) => b().startupMarks(...a);
-export const startupRead = (...a) => b().startupRead(...a);
-export const startupWrite = (...a) => b().startupWrite(...a);
 export const toggleFullscreen = (...a) => b().toggleFullscreen(...a);
-export const vaultDataRead = (...a) => b().vaultDataRead(...a);
-export const vaultDataWrite = (...a) => b().vaultDataWrite(...a);
-export const vaultRelativize = (...a) => b().vaultRelativize(...a);
-export const vaultResolve = (...a) => b().vaultResolve(...a);
 export const vpsRunsPull = (...a) => b().vpsRunsPull(...a);
 export const watchFiles = (...a) => b().watchFiles(...a);
-export const writeDownloads = (...a) => b().writeDownloads(...a);
-export const writeLibrary = (...a) => b().writeLibrary(...a);
-export const writeMusicTaste = (...a) => b().writeMusicTaste(...a);
-export const writeTermLayout = (...a) => b().writeTermLayout(...a);
 
 export const DEFAULT_SETTINGS = new Proxy({}, {
   get: (_t, k) => b().DEFAULT_SETTINGS[k],
   ownKeys: () => Reflect.ownKeys(b().DEFAULT_SETTINGS),
   getOwnPropertyDescriptor: (_t, k) => ({ ...Object.getOwnPropertyDescriptor(b().DEFAULT_SETTINGS, k), configurable: true }),
 });
-export const EMPTY_LIBRARY = new Proxy({}, {
-  get: (_t, k) => b().EMPTY_LIBRARY[k],
-  ownKeys: () => Reflect.ownKeys(b().EMPTY_LIBRARY),
-  getOwnPropertyDescriptor: (_t, k) => ({ ...Object.getOwnPropertyDescriptor(b().EMPTY_LIBRARY, k), configurable: true }),
-});
 export const FOOTER_ITEMS = new Proxy({}, {
   get: (_t, k) => b().FOOTER_ITEMS[k],
   ownKeys: () => Reflect.ownKeys(b().FOOTER_ITEMS),

package/shim/event.js

@@ -2,4 +2,9 @@
 //
 // @tauri-apps/api/event. Only listen: a plugin subscribing to Deck's events is expected, one
 // emitting into them is not.
-export const listen = (event, handler) => window.__deck.listen(event, handler);
+//
+// config-changed names the configs that changed, folders and all. A plugin's own come to it as it
+// names them, without its data/<id>/ folder, so `payload.includes("boards")` keeps working.
+import { unscoped } from "./scope.js";
+export const listen = (event, handler) => window.__deck.listen(event, event !== "config-changed" ? handler
+  : (e) => handler({ ...e, payload: Array.isArray(e.payload) ? e.payload.map(unscoped) : e.payload }));

package/shim/scope.js

@@ -0,0 +1,6 @@
+// GENERATED by sdk/gen-shim.mjs — do not edit.
+const id = (() => { try { return new URL(import.meta.url).searchParams.get("deck-id") ?? ""; } catch { return ""; } })();
+export const pluginId = id;
+const own = id ? `data/${id}/` : "";
+export const scoped = (name) => (own && !String(name).includes("/") ? own + name : name);
+export const unscoped = (name) => (own && typeof name === "string" && name.startsWith(own) ? name.slice(own.length) : name);

package/shim/terminals.js

@@ -39,6 +39,7 @@ export const moveZone = (...a) => t().moveZone(...a);
 export const mutateLayout = (...a) => t().mutateLayout(...a);
 export const nextActiveAfterClose = (...a) => t().nextActiveAfterClose(...a);
 export const nextZoneSpot = (...a) => t().nextZoneSpot(...a);
+export const openFile = (...a) => t().openFile(...a);
 export const openTabInWorkspace = (...a) => t().openTabInWorkspace(...a);
 export const paneCwd = (...a) => t().paneCwd(...a);
 export const paneHasAgent = (...a) => t().paneHasAgent(...a);

package/shim/ui.js

@@ -63,7 +63,6 @@ export const normalizeChord = (...a) => u().normalizeChord(...a);
 export const onKey = (...a) => u().onKey(...a);
 export const onKeys = (...a) => u().onKeys(...a);
 export const parseChord = (...a) => u().parseChord(...a);
-export const parseDirty = (...a) => u().parseDirty(...a);
 export const pushScope = (...a) => u().pushScope(...a);
 export const repoLabel = (...a) => u().repoLabel(...a);
 export const resolve = (...a) => u().resolve(...a);

package/template/AGENTS.md

@@ -0,0 +1,77 @@
+# __NAME__: notes for AI agents
+
+This is a plugin for Deck, a Windows app (Tauri, React 19). It is
+bundled into one `plugin.js` that Deck imports at run time, inside Deck's own window. Read this
+before changing anything.
+
+## Commands
+
+```sh
+npm run dev            # build on every save and install into the test Deck, which reloads it
+npm run build          # build once into plugin.js
+npm run install-local  # build and install into the user's real Deck
+npx deck-plugin check  # validate plugin.json
+```
+
+The test Deck is a second Deck with its own data, started with
+`& "$env:LOCALAPPDATA\Deck\deck.exe" --test` (PowerShell). Develop against it, never the real
+Deck: `npm run dev` only ever writes there. Run `npm run install-local` only when the user asks
+for the plugin to be installed for real. Its log is `%APPDATA%\Deck-Dev\logs\deck-<date>.log`;
+the plugin's `console.warn` and `console.error` lines land there.
+
+## Files
+
+- `plugin.json`: `id` (letters, digits, dashes; it is a folder name and a config key), `name`,
+  `description`, `icon` (a lucide icon name), `color`, `version`, `minDeck`.
+- `src/plugin.tsx`: the entry. Its exports are what Deck uses (below).
+- `src/mcp.ts`, if present: tools for Deck's MCP server, built to `mcp.js`.
+- `plugin.js` (and `mcp.js`): the build's output, gitignored. Never edit them.
+- **The API is `node_modules/deck-plugin-sdk/types/core/bridge.d.ts`**: every function Deck
+  exposes, with its documentation, generated from Deck's own source. Read it rather than guessing
+  a name. A plugin imports it as `deck-plugin-sdk/bridge`.
+
+## What the plugin can export
+
+`default` (a tab), `PaneView` (a view that can sit in a split pane, given `{ cwd, runInTerminal }`),
+`Status` (a footer readout), `Panel` (a footer drawer tab), `commands` (palette entries),
+`Settings` (a settings panel), `keybindings`, `Provider` (wraps the app, for state that must
+survive the tab closing), `Bar`, and `dispose`. At least one; none is required on its own.
+
+## Rules that are easy to break
+
+- **Import Deck's copies.** `react`, `lucide-react` and the `deck-plugin-sdk/*` modules resolve to
+  Deck's own at run time. Never add a second React, or a UI library that bundles one: two
+  Reacts in one tree break hooks.
+- **No native code.** A plugin can only call what Deck already exposes (`deck-plugin-sdk/bridge`).
+  To run a program, use `exec` or `procStream`; to read and write files, the `fs*` calls.
+- **Opening files**: `export const opens = [".ext"]` with a `PaneView` makes Deck open those files
+  in the plugin, each as its own tab, given as the `file` prop. Open one yourself with `openFile`
+  from `deck-plugin-sdk/terminals`; save with `fsWriteBytes`.
+- **npm packages are fine** (`npm install` and import): the build bundles them, their images,
+  fonts and CSS included, into `plugin.js`. `?raw` on an import gives a file's text (a worker).
+  A build step of your own (an esbuild plugin) goes in `deck-plugin.config.mjs` as
+  `export const esbuildPlugins = [...]`. Not a package that needs Node (`fs`, `child_process`),
+  one that bundles its own React, or one that starts a Web Worker from a file.
+- **Storage goes through `configRead` / `configWrite`** with plain names (`"settings"`, or
+  `"notes.md"` for a plain file). Deck keeps them in the plugin's own folder. A name never
+  written reads as `""`. Do not write a config whose text has not changed: every write wakes
+  every config listener in Deck.
+- **`listen("config-changed", ...)` gets a `string[]` of names**: act only when it includes one
+  of yours.
+- **Deck reloads the plugin on every rebuild.** Anything module scope starts (a `setInterval`,
+  a `listen`, a window listener) must be stopped in an exported `dispose()`, or the old copy keeps
+  running beside the new one. Anything a component creates outside the DOM (an `Audio`, a timer,
+  a socket) is stopped in its effect's cleanup.
+- **A poll stops when nobody can see it**: skip ticks while `document.hidden`, and do not run it
+  while the readout it feeds is switched off.
+- **Styling uses Deck's stylesheet.** Tailwind classes Deck does not already use do not exist.
+  Use Deck's semantic tokens (`text-text-primary`, `text-text-secondary`, `text-text-muted`,
+  `bg-elev`, `border-subtle`, `var(--accent)`) and Deck's components from `deck-plugin-sdk/ui`, so
+  the plugin follows the user's theme.
+- **No error is dropped silently.** A failed save, load or action logs
+  `console.warn("[__ID__] what failed", e)`.
+
+## More
+
+The full guide (exports, storage, testing, publishing) is in Deck's **Docs** tab, which also has
+the API reference for the Deck that is installed.

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/README.md

@@ -1,17 +1,20 @@
-# __NAME__
-
-A plugin for [Deck](https://deck.hasan-zarif.com).
-
-## Developing
-
-```sh
-npm run dev            # build, and rebuild as you edit
-npm run install-local  # copy it into Deck, which loads it without a restart
-```
-
-`src/plugin.tsx` is the entry point; its default export is the tab.
-
-## What it does
-
-Say what this plugin is for. This file is what the registry shows on its page, so it is worth
-writing for somebody deciding whether to install it rather than for yourself.
+# __NAME__
+
+A plugin for Deck.
+
+## Developing
+
+```sh
+npm run dev            # rebuild as you edit; each save shows in your test Deck
+npm run install-local  # when it is done: install it into your real Deck
+```
+
+Start a test Deck from Settings › Plugins › Open a test Deck: it keeps its own settings and data,
+so trying the plugin never touches your real Deck.
+
+`src/plugin.tsx` is the entry point; its default export is the tab.
+
+## What it does
+
+Say what this plugin is for. This file is what the registry shows on its page, so it is worth
+writing for somebody deciding whether to install it rather than for yourself.

package/template/gitignore

@@ -1,4 +1,4 @@
-node_modules/
-# Copied in by the build from the SDK — not yours to edit, and not worth committing.
-shim/
-types/
+node_modules/
+# What the build writes. A release carries plugin.json and these; the repository holds the source.
+plugin.js
+mcp.js

package/template/plugin.json

@@ -1,9 +1,9 @@
-{
-  "id": "__ID__",
-  "name": "__NAME__",
-  "description": "One line on what this is for, shown under its name in Settings.",
-  "icon": "Sparkles",
-  "color": "#a78bfa",
-  "version": "0.1.0",
-  "minDeck": "0.17.0"
-}
+{
+  "id": "__ID__",
+  "name": "__NAME__",
+  "description": "One line on what this is for, shown under its name in Settings.",
+  "icon": "Sparkles",
+  "color": "#a78bfa",
+  "version": "0.1.0",
+  "minDeck": "1.5.0"
+}

package/template/src/assets.d.ts

@@ -0,0 +1,16 @@
+// What importing a file that is not code gives you, so the editor knows. The build inlines each
+// into plugin.js: an image or font as a data: URL, a stylesheet as its text (or, imported with
+// nothing bound — `import "x.css"` — applied to the page), a .wasm file as its bytes.
+declare module "*.png" { const url: string; export default url; }
+declare module "*.jpg" { const url: string; export default url; }
+declare module "*.jpeg" { const url: string; export default url; }
+declare module "*.gif" { const url: string; export default url; }
+declare module "*.webp" { const url: string; export default url; }
+declare module "*.svg" { const url: string; export default url; }
+declare module "*.woff2" { const url: string; export default url; }
+declare module "*.css" { const text: string; export default text; }
+declare module "*.wasm" { const bytes: Uint8Array; export default bytes; }
+// `import text from "some/file?raw"`: any file, as its text.
+declare module "*?raw" { const text: string; export default text; }
+// `import data from "some/file?base64"`: any file's bytes, as a base64 string.
+declare module "*?base64" { const base64: string; export default base64; }