deck-plugin-sdk 1.11.0 → 1.11.1

package/template/AGENTS.md

@@ -1,81 +1,81 @@
-# __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
-npx deck-plugin publish --dry-run   # everything the registry checks, nothing published
-```
-
-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`, and `permissions`:
-  what it uses of Deck (`files`, `processes`, `git`, `network`, `terminals`, `browser`,
-  `secrets`, `system`, `deck`; the table is `node_modules/deck-plugin-sdk/permissions.json`). A
-  bridge call outside them throws, naming the one to add: add it rather than working around it.
-- `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.
+# __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
+npx deck-plugin publish --dry-run   # everything the registry checks, nothing published
+```
+
+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`, and `permissions`:
+  what it uses of Deck (`files`, `processes`, `git`, `network`, `terminals`, `browser`,
+  `secrets`, `system`, `deck`; the table is `node_modules/deck-plugin-sdk/permissions.json`). A
+  bridge call outside them throws, naming the one to add: add it rather than working around it.
+- `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

@@ -1 +1 @@
-@AGENTS.md
+@AGENTS.md

package/template/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) __YEAR__ __AUTHOR__
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) __YEAR__ __AUTHOR__
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template/README.md

@@ -1,20 +1,20 @@
-# __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.
+# __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/
-# What the build writes. A release carries plugin.json and these; the repository holds the source.
-plugin.js
-mcp.js
+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,10 +1,10 @@
-{
-  "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.11.0",
-  "permissions": []
-}
+{
+  "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.11.1",
+  "permissions": []
+}

package/template/src/assets.d.ts

@@ -1,16 +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; }
+// 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; }

package/template/src/plugin.tsx

@@ -1,65 +1,65 @@
-// __NAME__ — a Deck plugin.
-//
-// The default export is the tab. A plugin can export more than that — a footer readout, a
-// settings panel, palette commands, a pane view — and `docs/guide/api.md` in the Deck repository
-// lists every slot. One export is enough to start.
-import { useState } from "react";
-import { Sparkles } from "lucide-react";
-import { configRead, configWrite } from "deck-plugin-sdk/bridge";
-
-/** This plugin's own settings. Deck keeps a plugin's configs in its own folder, so a plain name. */
-const CONFIG = "settings";
-
-export default function __COMPONENT__() {
-  const [note, setNote] = useState("");
-  const [saved, setSaved] = useState(false);
-
-  // Deck's config store, the same one its own modules use. Reading a key that has never been
-  // written resolves to an empty string rather than throwing.
-  const load = async () => {
-    const raw = await configRead(CONFIG).catch(() => "");
-    setNote(raw.trim() ? (JSON.parse(raw) as { note?: string }).note ?? "" : "");
-  };
-
-  const save = async () => {
-    await configWrite(CONFIG, JSON.stringify({ note }));
-    setSaved(true);
-    setTimeout(() => setSaved(false), 1500);
-  };
-
-  return (
-    <div className="flex h-full flex-col gap-4 p-6">
-      <header className="flex items-center gap-3">
-        <Sparkles size={18} style={{ color: "var(--accent)" }} />
-        <h1 className="text-base font-semibold text-text-primary">__NAME__</h1>
-      </header>
-
-      <p className="max-w-[60ch] text-sm text-text-secondary">
-        Edit <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">src/plugin.tsx</code>,
-        run <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">npm run dev</code>,
-        and Deck reloads the plugin as you save.
-      </p>
-
-      <div className="flex max-w-md items-center gap-2">
-        <input
-          value={note}
-          onChange={(e) => setNote(e.target.value)}
-          onFocus={() => void load()}
-          placeholder="Type something, then save it"
-          className="min-w-0 flex-1 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-primary outline-none focus:border-accent"
-        />
-        <button
-          onClick={() => void save()}
-          className="shrink-0 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-secondary hover:border-accent hover:text-text-primary"
-        >
-          {saved ? "Saved" : "Save"}
-        </button>
-      </div>
-
-      <p className="text-xs text-text-muted">
-        That writes to Deck's config store under <code>{CONFIG}</code>, which stays on this
-        machine.
-      </p>
-    </div>
-  );
-}
+// __NAME__ — a Deck plugin.
+//
+// The default export is the tab. A plugin can export more than that — a footer readout, a
+// settings panel, palette commands, a pane view — and `docs/guide/api.md` in the Deck repository
+// lists every slot. One export is enough to start.
+import { useState } from "react";
+import { Sparkles } from "lucide-react";
+import { configRead, configWrite } from "deck-plugin-sdk/bridge";
+
+/** This plugin's own settings. Deck keeps a plugin's configs in its own folder, so a plain name. */
+const CONFIG = "settings";
+
+export default function __COMPONENT__() {
+  const [note, setNote] = useState("");
+  const [saved, setSaved] = useState(false);
+
+  // Deck's config store, the same one its own modules use. Reading a key that has never been
+  // written resolves to an empty string rather than throwing.
+  const load = async () => {
+    const raw = await configRead(CONFIG).catch(() => "");
+    setNote(raw.trim() ? (JSON.parse(raw) as { note?: string }).note ?? "" : "");
+  };
+
+  const save = async () => {
+    await configWrite(CONFIG, JSON.stringify({ note }));
+    setSaved(true);
+    setTimeout(() => setSaved(false), 1500);
+  };
+
+  return (
+    <div className="flex h-full flex-col gap-4 p-6">
+      <header className="flex items-center gap-3">
+        <Sparkles size={18} style={{ color: "var(--accent)" }} />
+        <h1 className="text-base font-semibold text-text-primary">__NAME__</h1>
+      </header>
+
+      <p className="max-w-[60ch] text-sm text-text-secondary">
+        Edit <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">src/plugin.tsx</code>,
+        run <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">npm run dev</code>,
+        and Deck reloads the plugin as you save.
+      </p>
+
+      <div className="flex max-w-md items-center gap-2">
+        <input
+          value={note}
+          onChange={(e) => setNote(e.target.value)}
+          onFocus={() => void load()}
+          placeholder="Type something, then save it"
+          className="min-w-0 flex-1 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-primary outline-none focus:border-accent"
+        />
+        <button
+          onClick={() => void save()}
+          className="shrink-0 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-secondary hover:border-accent hover:text-text-primary"
+        >
+          {saved ? "Saved" : "Save"}
+        </button>
+      </div>
+
+      <p className="text-xs text-text-muted">
+        That writes to Deck's config store under <code>{CONFIG}</code>, which stays on this
+        machine.
+      </p>
+    </div>
+  );
+}