deck-plugin-sdk 1.12.2 → 1.13.0

package/README.md

@@ -94,4 +94,6 @@ needs a newer one, with a sentence rather than an error from inside your module.
 ## Publishing
 
 A plugin is published by being listed in Deck's registry, which points at a release in your own
-repository. Until that is open to submissions, ask.
+repository. `deck-plugin publish` makes the release and submits it; `deck-plugin publish --dry-run`
+runs every check the registry will and prints the points the version will get, check by check.
+Everything else is in [Publishing](../docs/guide/publishing.md).

package/bin/deck-plugin.mjs

@@ -82,7 +82,8 @@ function copyInto(manifest, defaultTarget) {
   const { target, dir: plugins } = pluginsDir(defaultTarget);
   const dest = join(plugins, manifest.id);
   mkdirSync(dest, { recursive: true });
-  for (const f of ["plugin.json", "plugin.js", "mcp.js"]) {
+  // icon.svg only when plugin.json names it: Deck reads it from beside the manifest.
+  for (const f of ["plugin.json", "plugin.js", "mcp.js", ...(manifest.icon === "icon.svg" ? ["icon.svg"] : [])]) {
     if (existsSync(join(dir, f))) cpSync(join(dir, f), join(dest, f));
   }
   return { target, dest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deck-plugin-sdk",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "description": "Build a plugin for Deck, outside the Deck repository.",
   "type": "module",
   "license": "MIT",

package/publish.mjs

@@ -8,6 +8,7 @@
 //   the manifest, README, LICENSE and package-lock.json; a clean, pushed git tree; a build from
 //   the lockfile exactly as the registry will repeat it (npm ci, then this SDK's build); the
 //   release's files and sizes; and that its permissions cover what the bundle calls.
+// It also prints the points the registry will give this version (validate.mjs, points()).
 // Then it tags v<version>, makes the GitHub release with the built files, and opens a pull
 // request to the registry adding submissions/<id>.json, through the author's fork. The registry's
 // checks run on that PR and merge it when they pass.
@@ -17,7 +18,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkAssets, checkId, checkLockfile, checkManifest, checkPermissions } from "./validate.mjs";
+import { checkAssets, checkIcon, checkId, checkLockfile, checkManifest, checkPermissions, fileFacts, ICON_FILE, points } from "./validate.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const REGISTRY = "deck-desktop/deck-registry";
@@ -38,6 +39,10 @@ export async function publish(dir, manifest, { dryRun, buildPlugin }) {
   // ---- what is in the folder ----
   errors.push(...checkId(manifest.id ?? ""), ...checkManifest(manifest));
   if (!existsSync(join(dir, "README.md"))) errors.push("no README.md: it is the plugin's page in Deck and on the website");
+  if (manifest.icon === ICON_FILE) {
+    if (!existsSync(join(dir, ICON_FILE))) errors.push(`plugin.json's icon is ${ICON_FILE}, and there is none beside it`);
+    else errors.push(...checkIcon(readFileSync(join(dir, ICON_FILE), "utf8")));
+  }
   if (!["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"].some((f) => existsSync(join(dir, f)))) errors.push("no LICENSE: say how others may use it (the scaffold's is MIT)");
   if (existsSync(join(dir, ".npmrc"))) errors.push("there is an .npmrc: the registry installs from registry.npmjs.org only, so remove it");
   const lockAt = join(dir, "package-lock.json");
@@ -72,10 +77,10 @@ export async function publish(dir, manifest, { dryRun, buildPlugin }) {
   if (!npm) { console.error("  ✗ npm was not found beside node"); process.exit(1); }
   run(process.execPath, [npm, "ci", "--ignore-scripts", "--no-audit", "--no-fund"]);
   await buildPlugin(dir);
-  const files = ["plugin.json", "plugin.js", "mcp.js"].filter((f) => existsSync(join(dir, f)));
+  const files = ["plugin.json", "plugin.js", "mcp.js", ...(manifest.icon === ICON_FILE ? [ICON_FILE] : [])].filter((f) => existsSync(join(dir, f)));
   errors.push(...checkAssets("plugin", files.map((f) => ({ name: f, size: statSync(join(dir, f)).size }))));
   const table = JSON.parse(readFileSync(join(here, "permissions.json"), "utf8"));
-  const perms = checkPermissions(manifest.permissions, readFileSync(join(dir, "plugin.js"), "utf8"), table);
+  const perms = checkPermissions(manifest.permissions, readFileSync(join(dir, "plugin.js"), "utf8"), table, manifest.id);
   errors.push(...perms.errors);
   notes.push(...perms.notes);
   if (errors.length) {
@@ -85,6 +90,17 @@ export async function publish(dir, manifest, { dryRun, buildPlugin }) {
 
   say(`\n${manifest.name} ${manifest.version} is ready: ${files.join(", ")}${manifest.permissions.length ? `; it uses ${manifest.permissions.join(", ")}` : ""}.`);
   for (const n of notes) say(`  note: ${n}`);
+
+  // ---- its points, as the registry will give them ----
+  const read = (f) => (existsSync(join(dir, f)) ? readFileSync(join(dir, f), "utf8") : null);
+  const tsc = join(dir, "node_modules", "typescript", "bin", "tsc");
+  let typechecks = null;
+  if (!custom && existsSync(join(dir, "tsconfig.json")) && existsSync(tsc)) typechecks = ok(process.execPath, [tsc, "--noEmit", "-p", "."]);
+  let newestSdk = null;
+  try { newestSdk = (await (await fetch("https://registry.npmjs.org/deck-plugin-sdk/latest")).json()).version ?? null; } catch { /* offline: scored as not current */ }
+  const score = points({ ...fileFacts(read), buildVerified: !custom, typechecks, permissions: manifest.permissions, used: perms.used, newestSdk });
+  say(`\nPoints: ${score.total} of 100`);
+  for (const c of score.checks) say(`  ${c.got ? "✓" : "✗"} ${c.label} (${c.got}/${c.max})${c.fix ? ` — ${c.fix}` : ""}`);
   if (dryRun) {
     say(`\nDry run: nothing was tagged, released or submitted. Without --dry-run this tags ${tag}, releases it on ${repo}, and opens a PR to ${REGISTRY}.`);
     return;

package/template/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- First version.

package/template/plugin.json

@@ -5,6 +5,6 @@
   "icon": "Sparkles",
   "color": "#a78bfa",
   "version": "0.1.0",
-  "minDeck": "1.12.2",
+  "minDeck": "1.13.0",
   "permissions": []
 }

package/types/components/MarkdownToolbar.d.ts

@@ -26,10 +26,20 @@ export interface TextSurface {
     focus(): void;
     /** Whether the keyboard is in this text, for the markdown keys (Ctrl+B, Ctrl+I). */
     hasFocus(): boolean;
+    /** Where the selection is on screen (window coordinates), or null when nothing is selected or
+     *  it is out of view: where a floating toolbar goes. A surface without it never floats. */
+    selectionBox?(): {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    } | null;
+    /** Calls `fn` whenever the selection or the scroll changes; returns the unsubscribe. */
+    watch?(fn: () => void): () => void;
 }
 /** A TextSurface over a CodeMirror EditorView. */
 export declare function cmSurface(view: EditorView): TextSurface;
-export declare function MarkdownToolbar({ surface, zoom, onZoom, floating, view }: {
+export declare function MarkdownToolbar({ surface, zoom, onZoom, floating }: {
     /** The editor to drive. Null disables every button — there is nothing to type into. */
     surface: TextSurface | null;
     /** Current text size in px. Omit to hide the zoom controls entirely. */
@@ -41,10 +51,11 @@ export declare function MarkdownToolbar({ surface, zoom, onZoom, floating, view
      *
      * Omit it and the editor's own "Floating markdown toolbar" setting decides, which is what
      * every caller should do — this exists only for a surface that has a reason to override it.
-     * Needs `view`, which is what turns a document offset into screen coordinates.
+     * Needs a surface that says where its selection is (selectionBox: both of Deck's do). The bar is
+     * placed in its own positioned parent, which should be the box the editor fills.
      */
     floating?: boolean;
-    /** The CodeMirror view, for positioning a floating bar. Ignored otherwise. */
+    /** No longer needed: the surface says where its selection is. Kept so plugins passing it still compile. */
     view?: EditorView | null;
 }): import("react").JSX.Element;
 export default MarkdownToolbar;

package/types/core/bridge.d.ts

@@ -844,7 +844,8 @@ export declare const remoteHome: (host: string, sudo: boolean) => Promise<string
 export declare const sshHosts: () => Promise<string[]>;
 export declare const fsWrite: (path: string, content: string) => Promise<void>;
 /** Raw bytes — a PDF, an image, a response — which a string would corrupt. Sent as the raw body,
- *  the path percent-encoded in a header; a remote path writes over SSH. */
+ *  the path percent-encoded in a header; a remote path writes over SSH. A local write makes a
+ *  missing folder first, so a plugin's dataDir() needs no fsCreateDir. */
 export declare const fsWriteBytes: (path: string, bytes: Uint8Array) => Promise<void>;
 /** Write bytes without ever clobbering: dedupes the name on collision, returns the path used. */
 export declare const fsSaveUnique: (saveTo: string, defaultName: string, bytes: Uint8Array) => Promise<string>;

package/types/core/editor/conflictlens.d.ts

@@ -0,0 +1,3 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** Once, at startup: the command the buttons run, the buttons, and the tints on every file model. */
+export declare function installConflictLens(): void;

package/types/core/editor/conflicts.d.ts

@@ -0,0 +1,23 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** One block, by the 1-based line numbers of its markers. */
+export interface ConflictBlock {
+    start: number;
+    /** The `|||||||` line of a diff3 block, else null. */
+    base: number | null;
+    mid: number;
+    end: number;
+}
+export type ConflictPick = "current" | "incoming" | "both";
+/** Every complete block, in order. A block left unclosed is not one: nothing is offered for it. */
+export declare function findConflicts(lines: string[]): ConflictBlock[];
+/** The lines a block resolves to: one side, or both with the current change first. The base never. */
+export declare function resolution(lines: string[], b: ConflictBlock, pick: ConflictPick): string[];
+/**
+ * The edit replacing block `b` with `with`, as a 1-based range (start line and column, end line
+ * and column) and its text. Whole lines go, end marker included; when nothing is kept the block's
+ * lines are removed rather than left as one empty line. `lastCol(n)` is line n's last column.
+ */
+export declare function conflictEdit(lineCount: number, lastCol: (n: number) => number, b: ConflictBlock, keep: string[], eol: string): {
+    range: readonly [number, number, number, number];
+    text: string;
+};

package/types/core/editor/lsp.d.ts

@@ -182,14 +182,13 @@ export declare function setLspOpenFileHandler(fn: OpenFileHandler): void;
 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.
+ * this is the Restart action, the popover's × and the memory readout's stop button. `forget`
+ * (the last two) shows it as stopped rather than restarting, and lets an edit start it again.
  *
  * 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 declare function lspRestart(id: string, forget?: boolean): Promise<void>;
 export {};

package/types/core/workspaces/layout.d.ts

@@ -49,6 +49,9 @@ export interface LayoutTab {
      * the main window. Dropped the moment the tab is moved by hand: then it is one of yours.
      */
     transient?: true;
+    /** Pinned from its menu (tabops.ts): only its icon, before the unpinned tabs beside it, and left
+     *  open by Close others, Close to the right and Close all. */
+    pinned?: true;
 }
 export interface LayoutWorkspace {
     id: string;

package/types/core/workspaces/zones.d.ts

@@ -84,6 +84,12 @@ export declare function reorderTab(tabs: readonly LayoutTab[], srcId: string, ov
  *  (null: none, held over a tab outside any group or over a group's chip). Left out, the tabs
  *  either side decide (settleGroup). */
 group?: string | null): LayoutTab[];
+/**
+ * Each strip's pinned tabs (tabops.ts) before its unpinned ones, each side kept in its order: a drag
+ * can neither take a pinned tab among the others nor put another before the pinned ones. Takes a
+ * placed list (placeAll), whose zones a reorder of the list cannot change.
+ */
+export declare function pinnedFirst(tabs: LayoutTab[]): LayoutTab[];
 /**
  * A tab group's tabs sit together in their zone's row: a tab dropped between two of one group's
  * tabs joins it, and one moved away from every other tab of its own group leaves it. Next to one
@@ -170,9 +176,10 @@ export declare function showActiveTab(w: LayoutWorkspace): LayoutWorkspace;
 /**
  * Which tab becomes active when `closing` goes: the one beside it in the same zone (the next, or
  * the one before when it was last), as a browser does, so closing a tab neither throws you out of
- * the zone nor back to its first tab; otherwise the first zone left.
+ * the zone nor back to its first tab; otherwise the first zone left. A tab in a folded group is
+ * passed over for the nearest one that is not, so closing a tab does not open a group.
  */
-export declare function nextActiveAfterClose(tabs: readonly LayoutTab[], closing: string): string | undefined;
+export declare function nextActiveAfterClose(tabs: readonly LayoutTab[], closing: string, groups?: readonly TabGroup[]): 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

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

@@ -1,10 +1,13 @@
 // GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
 import { EditorView } from "@codemirror/view";
-export declare function MarkdownLive({ value, path, onChange, onSave, onView, flush, fontSize, onWikiLink, resolveWikiLink, wikiLinkOptions, mermaid, resolveEmbed }: {
+export declare function MarkdownLive({ value, path, onChange, onSave, onView, flush, fontSize, onWikiLink, resolveWikiLink, wikiLinkOptions, mermaid, resolveEmbed, onOpenLink }: {
     value: string;
     path?: string;
     onChange: (v: string) => void;
     onSave?: () => void;
+    /** A click on a `[text](url)` link or a bare address, with its address as written. Omit it and a
+     *  web address opens in Deck's browser, another scheme (mailto:) with the system, a path not at all. */
+    onOpenLink?: (href: string) => void;
     /** Hands the live EditorView out, and null on unmount. For a formatting toolbar, which has to
      *  dispatch into this editor rather than rewrite the string around it. */
     onView?: (v: EditorView | null) => void;

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

@@ -0,0 +1,36 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import { type Extension } from "@codemirror/state";
+import { EditorView, WidgetType } from "@codemirror/view";
+/**
+ * A rendered mermaid diagram in place of its ```mermaid fence.
+ *
+ * A StateField rather than part of the ViewPlugin above, because CodeMirror refuses a
+ * plugin-supplied decoration that replaces a line break or sets `block: true` — and a fenced
+ * block is several lines. A StateField is the documented exception (see decorateTable, which
+ * hits the same wall from the other side).
+ *
+ * Rendering is asynchronous: mermaid parses and lays out, so the widget draws a placeholder of
+ * the same width and swaps the SVG in when it resolves, calling requestMeasure so CodeMirror's
+ * height map learns the real height rather than staying short by the diagram.
+ */
+export declare class MermaidWidget extends WidgetType {
+    readonly code: string;
+    constructor(code: string);
+    eq(o: MermaidWidget): boolean;
+    toDOM(view: EditorView): HTMLDivElement;
+    destroy(dom: HTMLElement): void;
+    ignoreEvent(): boolean;
+    get estimatedHeight(): number;
+}
+/** Text from inside a `> ` quote (or a callout) without the quote markers that start each line. */
+export declare const unquote: (s: string) => string;
+/** Load mermaid on first use and render one diagram to SVG. */
+export declare function renderMermaid(id: string, code: string): Promise<string>;
+/**
+ * The block-level widgets: a mermaid fence and a `$$maths$$` block.
+ *
+ * Both live here rather than in the live-preview ViewPlugin because CodeMirror refuses a
+ * plugin-supplied decoration that replaces a line break or sets `block: true`, and both span
+ * lines. `mermaid` gates only the diagrams — maths is drawn wherever this file is used.
+ */
+export declare function blockWidgetField(mermaid: boolean): Extension;

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

@@ -0,0 +1,9 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import { ViewPlugin, type DecorationSet, type EditorView, type ViewUpdate } from "@codemirror/view";
+/** The code-block colours and copy buttons, as a ViewPlugin beside the live preview's own. */
+export declare function codeBlocksExt(): ViewPlugin<{
+    decorations: DecorationSet;
+    readonly view: EditorView;
+    destroy(): void;
+    update(u: ViewUpdate): void;
+}, undefined>;

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

@@ -0,0 +1,20 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import { Decoration, type DecorationSet, type EditorView } from "@codemirror/view";
+import type { Extension, Range } from "@codemirror/state";
+import type { SyntaxNode } from "@lezer/common";
+export declare const replaceHide: Decoration;
+/**
+ * Decorate one GFM Table: hide its syntax and line the columns up.
+ *
+ * Column widths are applied as `min-width` in `ch` units on the cells, so nothing is written
+ * into the document — no padding spaces to undo, and any other editor sees exactly what was typed.
+ * That only measures correctly because `.cm-table-l` is monospace.
+ *
+ * ponytail: assumes leading and trailing pipes (`| a | b |`), which is what the toolbar
+ * generates and what Obsidian writes. A borderless `a | b` table still parses, but its first
+ * and last columns will not align.
+ */
+export declare function decorateTable(view: EditorView, table: SyntaxNode, ranges: Range<Decoration>[]): void;
+/** `trash`: moves a local image's file to the Recycle Bin, for its delete button (MarkdownLive passes bridge.fsTrash). */
+export declare function decorate(view: EditorView, baseDir: string, resolveWiki?: (target: string) => boolean, resolveEmbed?: (name: string) => string | null, trash?: (file: string) => Promise<void>): DecorationSet;
+export declare function livePreviewExt(baseDir: string, resolveWiki?: () => ((target: string) => boolean) | undefined, resolveEmbed?: () => ((name: string) => string | null) | undefined, trash?: (file: string) => Promise<void>): Extension;

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

@@ -0,0 +1,16 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** `Pasted image 20261029143005.png`: the time it was pasted, to the second, as Obsidian names them. */
+export declare function pastedImageName(at: Date, mime: string): string;
+/** The link for an image saved beside the note: its name, spaces and all, encoded as a link must be. */
+export declare const imageLink: (savedPath: string) => string;
+export type LinkTarget = {
+    url: string;
+} | {
+    path: string;
+} | null;
+/**
+ * `href` from a note at `notePath`. A web or mail address as it is; a link to a heading in this
+ * note (`#part`) is nothing to open; anything else is a file: decoded (`my%20note.md`), its
+ * `#heading` dropped, and joined to the note's folder unless it is absolute.
+ */
+export declare function linkTarget(href: string, notePath: string): LinkTarget;

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

@@ -0,0 +1,3 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** The paste handler, given the note's path (read at the paste, since a new note gets one on its first save). */
+export declare function imagePaste(notePath: () => string | undefined): import("@codemirror/state").Extension;

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

@@ -0,0 +1,30 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import type { MarkdownConfig } from "@lezer/markdown";
+/**
+ * `[[Note]]`, `[[Note|alias]]`, `[[Note#heading]]` as a first-class inline node.
+ *
+ * A Lezer extension rather than a regex over the text, because CommonMark already claims the
+ * brackets: `[[Note]]` parses as a Link whose LinkMark is one bracket per side, and LinkMark is
+ * in HIDE_MARKS — so without this a wikilink renders as a literal `[Note]`. Claiming the whole
+ * `[[...]]` at PARSE time is what stops that.
+ *
+ * The alias/heading rule is the one in the Vault plugin's src/vault.ts, which is where it is tested:
+ * the alias splits on the LAST pipe, the heading on the FIRST hash of what is left.
+ */
+export declare const WikiLinkExt: MarkdownConfig;
+/**
+ * `==highlighted==`, Obsidian's marker syntax. Not part of GFM, so it needs its own rule.
+ *
+ * Two equals signs on each side, no newline between them — the same shape as Strikethrough's
+ * `~~`, which is what this is modelled on.
+ */
+export declare const HighlightExt: MarkdownConfig;
+/**
+ * `$inline$` and `$$block$$` maths, and `#tag`, as Obsidian writes them.
+ *
+ * Neither is in CommonMark or GFM, so each needs its own inline rule. The dollar rules are
+ * deliberately strict about what opens one: a lone `$` in prose ("costs $5") must not start a
+ * formula that runs to the end of the paragraph.
+ */
+export declare const MathExt: MarkdownConfig;
+export declare const TagExt: MarkdownConfig;

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

@@ -0,0 +1,20 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** One table line: its start offset and its text. */
+export interface TableLine {
+    from: number;
+    text: string;
+}
+/**
+ * The edits that add a column at the right of every line, the rule line `---`, the others empty.
+ * A line without a closing pipe gets one first, so the new cell is a cell.
+ */
+export declare function addColumn(lines: TableLine[], ruleIndex: number): {
+    from: number;
+    insert: string;
+}[];
+/** The edit that adds an empty row after the last line, as many cells wide as the header; and where its first cell's text starts. */
+export declare function addRow(lines: TableLine[]): {
+    from: number;
+    insert: string;
+    caret: number;
+};

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

@@ -0,0 +1,110 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import { EditorView, WidgetType } from "@codemirror/view";
+/**
+ * Obsidian's callout kinds, folded onto the handful that actually differ in appearance.
+ *
+ * Obsidian ships around a dozen names, several of which are aliases for the same colour and icon
+ * (`error` is `danger`, `tip` is `hint`). Keeping the alias table rather than a class per name
+ * means an unknown kind still renders, as a note, instead of falling back to a plain quote.
+ */
+export declare const CALLOUT_ALIAS: Record<string, string>;
+/** The glyph for each kind. Text, not an icon font — the editor has no icon set of its own. */
+export declare const CALLOUT_ICON: Record<string, string>;
+/** `[!warning]` with no title shows "Warning". */
+export declare function defaultTitle(raw: string): string;
+/** The icon and, when the callout has no title of its own, the kind's name. */
+export declare class CalloutIcon extends WidgetType {
+    readonly kind: string;
+    readonly title: string;
+    constructor(kind: string, title: string);
+    eq(o: CalloutIcon): boolean;
+    toDOM(): HTMLSpanElement;
+}
+/** A rendered KaTeX formula in place of its `$...$`. */
+export declare class MathWidget extends WidgetType {
+    readonly src: string;
+    readonly block: boolean;
+    constructor(src: string, block: boolean);
+    eq(o: MathWidget): boolean;
+    toDOM(view: EditorView): HTMLDivElement | HTMLSpanElement;
+    ignoreEvent(): boolean;
+}
+/** Load KaTeX on first use and render one formula. */
+export declare function renderMath(src: string, block: boolean): Promise<string>;
+/** Split `target#heading|alias` the way Obsidian does. See the Vault plugin's src/vault.ts. */
+export declare function splitWikiLink(body: string): {
+    target: string;
+    heading: string;
+    text: string;
+};
+export declare class BulletWidget extends WidgetType {
+    readonly ch: string;
+    constructor(ch: string);
+    eq(o: BulletWidget): boolean;
+    toDOM(): HTMLSpanElement;
+}
+export declare class TaskWidget extends WidgetType {
+    readonly checked: boolean;
+    readonly pos: number;
+    constructor(checked: boolean, pos: number);
+    eq(o: TaskWidget): boolean;
+    toDOM(view: EditorView): HTMLInputElement;
+    ignoreEvent(): boolean;
+}
+/**
+ * An inline image, with the controls Obsidian puts on one: open it full size, and drag its
+ * corner to resize.
+ *
+ * A resize writes the width back into the link itself (`![[img.png|400]]`), so it travels with
+ * the note — Obsidian shows the same width. `from`/`to`
+ * are the link's bounds so the widget can rewrite it; `width` is what it currently says.
+ */
+export declare class ImageWidget extends WidgetType {
+    readonly src: string;
+    readonly from: number;
+    readonly to: number;
+    readonly width: number | null;
+    /** Rewrite the link with a new width, or remove the width when null. */
+    readonly setWidth: (view: EditorView, from: number, to: number, width: number | null) => void;
+    /** Drawn below the revealed link text rather than in place of it. */
+    readonly below: boolean;
+    /** A file on this PC and how to put it in the Recycle Bin, for the delete button; null for a web image. */
+    readonly del: {
+        file: string;
+        trash: (file: string) => Promise<void>;
+    } | null;
+    constructor(src: string, from: number, to: number, width: number | null, 
+    /** Rewrite the link with a new width, or remove the width when null. */
+    setWidth: (view: EditorView, from: number, to: number, width: number | null) => void, 
+    /** Drawn below the revealed link text rather than in place of it. */
+    below?: boolean, 
+    /** A file on this PC and how to put it in the Recycle Bin, for the delete button; null for a web image. */
+    del?: {
+        file: string;
+        trash: (file: string) => Promise<void>;
+    } | null);
+    eq(o: ImageWidget): boolean;
+    toDOM(view: EditorView): HTMLSpanElement;
+}
+/** Show one image full size, over everything in window `win` (the editor's: a floating one too), until it is dismissed. */
+export declare function openLightbox(src: string, win: Window): void;
+/**
+ * Rewrite an image link's width in place.
+ *
+ * Both spellings: `![[file.png|400]]` for an embed and `![alt|400](path)` for a standard link,
+ * which is what Obsidian writes for each.
+ */
+export declare function writeImageWidth(view: EditorView, from: number, to: number, width: number | null): void;
+/**
+ * A table's + : at the right of its header row it adds a column, under its last row a row
+ * (tableedit.ts). The table is found from where the button is at the click, so the widget needs no
+ * position of its own and is the same widget wherever the table moves.
+ */
+export declare class TableAddWidget extends WidgetType {
+    readonly kind: "col" | "row";
+    readonly edge: boolean;
+    /** `edge`: the column + sits on its row's bottom edge, which is the table's middle when it has an even number of rows. */
+    constructor(kind: "col" | "row", edge?: boolean);
+    eq(o: TableAddWidget): boolean;
+    toDOM(view: EditorView): HTMLButtonElement;
+}

package/validate.mjs

@@ -11,7 +11,7 @@ export const RESERVED = new Set(["terminals", "editor", "docs", "settings", "dec
  * 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 BUILD_RUNS = ["deck-plugin-sdk", "esbuild", "react", "lucide-react", "framer-motion", "typescript"];
 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.-]+))?$/;
@@ -44,13 +44,41 @@ export function checkManifest(m) {
   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");
+  if (typeof m.icon === "string" && m.icon.endsWith(".svg") && m.icon !== ICON_FILE) errors.push(`an icon of its own must be named ${ICON_FILE}`);
+  return errors;
+}
+
+// ---- a plugin's own icon ----
+// `"icon": "icon.svg"` in plugin.json, in place of a lucide name: a file in the package, drawn in
+// one colour (the plugin's) as a mask, the way Deck draws its own icons, so it never runs and
+// follows the theme. Only shapes are allowed in it.
+
+/** The one file name a plugin's own icon may have. */
+export const ICON_FILE = "icon.svg";
+/** The largest icon accepted: an icon is a few shapes, and the catalogue carries it inline. */
+export const MAX_ICON = 16 * 1024;
+const ICON_TAGS = new Set(["svg", "g", "path", "circle", "rect", "line", "polyline", "polygon", "ellipse", "title", "desc"]);
+
+/** What is wrong with an icon.svg's text: [] when it is only shapes, with a viewBox, small enough. */
+export function checkIcon(svg) {
+  const errors = [];
+  if (Buffer.byteLength(svg) > MAX_ICON) errors.push(`${ICON_FILE} is ${(Buffer.byteLength(svg) / 1024).toFixed(1)} KB; an icon may be 16 KB at most`);
+  const body = svg.replace(/^\uFEFF?\s*(<\?xml[^>]*\?>\s*)?/, "").replace(/<!--[\s\S]*?-->/g, "").trim();
+  if (!/^<svg[\s>]/.test(body)) errors.push(`${ICON_FILE} must be an <svg> element`);
+  if (!/<svg[^>]*\sviewBox\s*=/.test(body)) errors.push(`${ICON_FILE} needs a viewBox, so it scales to the size it is drawn at`);
+  if (/<!|<\?/.test(body)) errors.push(`${ICON_FILE} may not hold a DOCTYPE, an entity or a processing instruction`);
+  const tags = [...new Set([...body.matchAll(/<\/?\s*([\w:-]+)/g)].map((m) => m[1]))].filter((t) => !ICON_TAGS.has(t));
+  if (tags.length) errors.push(`${ICON_FILE} may hold only shapes; remove ${tags.map((t) => `<${t}>`).join(", ")}`);
+  const attrs = [...new Set([...body.matchAll(/\s([\w:-]+)\s*=/g)].map((m) => m[1]))].filter((a) => /^on|^(href|xlink:href|style)$/i.test(a));
+  if (attrs.length) errors.push(`${ICON_FILE} may not have ${attrs.join(", ")}: no scripts, links or styles`);
+  if (/url\s*\(|javascript:|data:/i.test(body)) errors.push(`${ICON_FILE} may not point at anything outside itself (url(), data: or javascript:)`);
   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);
+  const ok = (n) => kind === "plugin" ? ["plugin.json", "plugin.js", "mcp.js", ICON_FILE].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}\``);
@@ -86,8 +114,14 @@ export function checkLockfile(lock) {
  * 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.
+ *
+ * With the plugin's `id`, a config named in full (`"state/term-procs"`, another
+ * plugin's `data/<id>/…`) needs "deck", as Deck's bridge asks at run time: a plain name is kept in
+ * the plugin's own folder, a name with a "/" is one of Deck's or another plugin's. Only names
+ * written out whole are seen (a name built at run time is not), and one only compared against, as
+ * a config-changed listener does, counts too: such a plugin almost always reads it.
  */
-export function checkPermissions(declared, bundle, table) {
+export function checkPermissions(declared, bundle, table, id) {
   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 };
@@ -104,9 +138,89 @@ export function checkPermissions(declared, bundle, table) {
   for (const [mod, p] of Object.entries(table.modules)) {
     if (new RegExp(`__deck\\?\\.${mod}\\b`).test(bundle)) needs.set(p, [...(needs.get(p) ?? []), mod]);
   }
+  if (id) {
+    // A minified bundle keeps the name but not the call's, so the names are what is looked for.
+    for (const [, name] of bundle.matchAll(/["'`]((?:settings|state|cache|secrets|logs)\/[\w./-]+|data\/[\w-]+\/[\w./-]*)["'`]/g)) {
+      const seen = needs.get("deck") ?? [], what = `the config "${name}"`;
+      if (!name.startsWith(`data/${id}/`) && !seen.includes(what)) needs.set("deck", [...seen, what]);
+    }
+  }
   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 };
+  return { errors, notes, used: [...needs.keys()] };
+}
+
+// ---- points ----
+// A version's points: advice for whoever is choosing a plugin, never a gate (the checks above are
+// that). Worked out once when it is published, by the registry for a submission and by
+// `deck-plugin publish --dry-run` on the author's machine, from the same facts, so they agree.
+
+/** The files a licence may be in, in the order they are looked for. */
+export const LICENSE_FILES = ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"];
+/** Open-source licences, each by a phrase its text always has. */
+const LICENSES = [
+  ["MIT", /Permission is hereby granted, free of charge/i],
+  ["Apache-2.0", /Apache License[\s\S]{0,40}Version 2\.0/i],
+  ["BSD", /Redistribution and use in source and binary forms/i],
+  ["ISC", /Permission to use, copy, modify, and\/or distribute this software for any\s+purpose/i],
+  ["MPL-2.0", /Mozilla Public License,? (?:v\. |Version )2\.0/i],
+  ["GPL", /GNU (?:Affero |Lesser )?General Public License/i],
+  ["Unlicense", /This is free and unencumbered software released into the public domain/i],
+];
+export const licenseOf = (text) => LICENSES.find(([, re]) => re.test(text))?.[0] ?? null;
+/** A README that shows the plugin: a markdown or HTML image, or a video. */
+export const showsMedia = (md) => /!\[[^\]]*\]\(\s*[^)\s]|<img\s[^>]*src=|<video\s/i.test(md);
+
+/**
+ * The facts that need only the package's files. `read(name)` gives a file's text at the tag, or
+ * null when there is none.
+ */
+export function fileFacts(read) {
+  const licence = LICENSE_FILES.map(read).find((t) => t != null);
+  let lock = null;
+  try { lock = JSON.parse(read("package-lock.json") ?? "null"); } catch { /* not a lockfile, so none */ }
+  return {
+    license: licence == null ? null : licenseOf(licence),
+    changelog: read("CHANGELOG.md") != null,
+    readmeMedia: showsMedia(read("README.md") ?? ""),
+    lockfile: !!lock && !checkLockfile(lock).length,
+    sdk: lock?.packages?.["node_modules/deck-plugin-sdk"]?.version ?? null,
+  };
+}
+
+/** How many minor versions `v` is behind `newest`: Infinity across a major. */
+function minorsBehind(v, newest) {
+  const [a, b] = [v, newest].map((x) => x.split("-")[0].split(".").map(Number));
+  if (a[0] !== b[0]) return a[0] > b[0] ? 0 : Infinity;
+  return Math.max(0, b[1] - a[1]);
+}
+
+/**
+ * A version's points out of 100, check by check. `f` is fileFacts plus what the registry learns by
+ * building it: buildVerified, typechecks (true, false, or null when it could not be run), the
+ * permissions declared (null when plugin.json has none) and used, and the newest SDK on npm.
+ * A check not earned says how to earn it.
+ */
+export function points(f) {
+  const unused = f.permissions ? f.permissions.filter((p) => !f.used.includes(p)) : [];
+  const checks = [
+    ["readme-media", "The README shows it, with a screenshot or other image", 10, f.readmeMedia,
+      "Add a screenshot to README.md"],
+    ["changelog", "It has a changelog", 10, f.changelog, "Add a CHANGELOG.md saying what each version changed"],
+    ["license", "It has an open-source licence", 10, !!f.license, "Add a LICENSE with an open-source licence, such as MIT"],
+    ["lockfile", "Its lockfile installs only from npm, every package with a hash", 10, f.lockfile,
+      "Commit a package-lock.json made by npm 7 or newer, with nothing linked or from elsewhere"],
+    ["build-verified", "The registry rebuilt it from its source and got the same files", 10, f.buildVerified,
+      "Release what `npm ci && npm run build` makes at the tag, with no deck-plugin.config.mjs"],
+    ["permissions", "It says what it uses", 10, Array.isArray(f.permissions), "List what it uses in plugin.json's \"permissions\""],
+    ["least-privilege", "It asks for nothing it does not use", 10, Array.isArray(f.permissions) && !unused.length,
+      unused.length ? `Remove ${unused.join(", ")} from "permissions": its code never uses ${unused.length > 1 ? "them" : "it"}` : "List what it uses in plugin.json's \"permissions\""],
+    ["typechecks", "It type-checks", 20, f.typechecks === true,
+      f.typechecks === null ? "Let the registry rebuild it, with a tsconfig.json, so it can be type-checked" : "Make `npx tsc --noEmit` pass"],
+    ["up-to-date", "It is built with a current SDK", 10, !!(f.sdk && f.newestSdk && minorsBehind(f.sdk, f.newestSdk) <= 1),
+      `Build it with deck-plugin-sdk ${f.newestSdk ?? "at its newest"}`],
+  ].map(([id, label, max, ok, fix]) => ({ id, label, max, got: ok ? max : 0, ...(ok ? {} : { fix }) }));
+  return { total: checks.reduce((n, c) => n + c.got, 0), checks };
 }