deck-plugin-sdk 1.12.3 → 1.14.0

package/README.md

@@ -62,8 +62,22 @@ actually exposes rather than a hand-written approximation that has drifted.
 Any other npm package is `npm install` and import: the build bundles it into `plugin.js`, with the
 images, fonts and CSS it brings. Writing a plugin, in the Docs, says what cannot work that way.
 
-When the build needs more than that (a worker bundled into the plugin, a dependency's locales left
-out), export esbuild plugins from `deck-plugin.config.mjs` beside `plugin.json`:
+Two things a build often needs are settings, which the registry can still rebuild:
+
+- **A worker of your own:** `import code from "./job.worker.ts?worker"` bundles that file and what
+  it imports into one script and gives its text, to start with
+  `new Worker(URL.createObjectURL(new Blob([code])))`.
+- **Files a package brings that you never use** (a library's translations into every language):
+  regular expressions in `package.json`, matched against each file's path, and each match is
+  bundled empty:
+
+  ```json
+  "deckPlugin": { "leaveOut": ["/locales/(?!en-)[^/]+\\.js$"] }
+  ```
+
+When the build needs more than that, export esbuild plugins from `deck-plugin.config.mjs` beside
+`plugin.json`. The registry does not run your code, so it cannot rebuild a plugin that has one:
+it is listed as build not verified, and misses those points.
 
 ```js
 export const esbuildPlugins = [{ name: "my-step", setup(build) { /* ... */ } }];
@@ -94,4 +108,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/build-plugin.mjs

@@ -17,7 +17,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, write
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { assetLoaders, fromPackage, packageCss, rawImports } from "./packages.mjs";
+import { assetLoaders, fromPackage, leaveOut, packageCss, rawImports, workerImports } from "./packages.mjs";
 
 const sdk = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -58,11 +58,15 @@ export async function buildPlugin(dir, { entry = "plugin.tsx" } = {}) {
   }
   const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
 
-  // A plugin that needs more from esbuild than this build gives (a worker bundled into it, a
-  // dependency's locales left out) exports `esbuildPlugins` from deck-plugin.config.mjs beside
-  // plugin.json. They run after Deck's own, so they never take over react or the shim.
+  // What a plugin needs beyond the plain build is a setting where it can be: `?worker` imports, and
+  // `"deckPlugin": { "leaveOut": [...] }` in package.json (packages.mjs). Those run none of the
+  // plugin's code, so the registry can rebuild it. Anything more exports `esbuildPlugins` from
+  // deck-plugin.config.mjs beside plugin.json, which runs after Deck's own, so it never takes over
+  // react or the shim, and which the registry will not run.
   const configPath = join(dir, "deck-plugin.config.mjs");
   const config = existsSync(configPath) ? await import(pathToFileURL(configPath).href) : {};
+  const pkgPath = join(dir, "package.json");
+  const settings = (existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, "utf8")).deckPlugin : null) ?? {};
 
   const sources = readdirSync(join(dir, "src"), { recursive: true })
     .filter((f) => typeof f === "string" && /\.tsx?$/.test(f))
@@ -150,7 +154,7 @@ ${names.map((n) => `export const ${n} = __src.${n};`).join("\n")}
           .map((k) => k.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&")).join("|")})$`);
         b.onResolve({ filter }, (a) => (fromPackage(a, dir) ? undefined : { path: shims[a.path] }));
       },
-    }, rawImports, packageCss(manifest.id, dir), ...(config.esbuildPlugins ?? [])],
+    }, rawImports, workerImports, leaveOut(settings.leaveOut), packageCss(manifest.id, dir), ...(config.esbuildPlugins ?? [])],
     logLevel: "info",
   });
 

package/package.json

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

package/packages.mjs

@@ -105,3 +105,47 @@ export const rawImports = {
     b.onLoad({ filter: /.*/, namespace: "deck-raw" }, (args) => ({ contents: readFileSync(args.path), loader: args.pluginData?.as === "base64" ? "base64" : "text" }));
   },
 };
+
+/**
+ * `import code from "./x.worker.ts?worker"` bundles that file and what it imports into one script
+ * and gives its text, for a Worker started from a Blob URL: a plugin is one plugin.js, so the
+ * worker cannot be a file beside it. Only esbuild runs, as for the plugin itself.
+ */
+export const workerImports = {
+  name: "deck-worker",
+  setup(b) {
+    b.onResolve({ filter: /\?worker$/ }, async (args) => {
+      const r = await b.resolve(args.path.slice(0, -"?worker".length), { kind: args.kind, resolveDir: args.resolveDir, importer: args.importer });
+      if (r.errors.length) return { errors: r.errors };
+      return { path: r.path, namespace: "deck-worker" };
+    });
+    b.onLoad({ filter: /.*/, namespace: "deck-worker" }, async (args) => {
+      const out = await b.esbuild.build({ entryPoints: [args.path], bundle: true, write: false, format: "iife", target: "es2022", minify: true, metafile: true });
+      return { contents: out.outputFiles[0].text, loader: "text", watchFiles: Object.keys(out.metafile.inputs) };
+    });
+  },
+};
+
+/**
+ * `"deckPlugin": { "leaveOut": [...] }` in package.json: regular expressions, and a file whose path
+ * (with forward slashes) matches one is bundled as an empty module. For what a package bundles but
+ * the plugin never uses, such as a library's translations into every language. Matched on load
+ * rather than on import, so a file reached by a pattern import (`import(\`./locales/${l}.js\`)`) is
+ * left out too. A setting rather than code, so the registry can still rebuild the plugin.
+ */
+export function leaveOut(patterns = []) {
+  if (!Array.isArray(patterns) || patterns.some((p) => typeof p !== "string" || p.length > 200)) {
+    throw new Error('package.json\'s "deckPlugin.leaveOut" must be a list of regular expressions, each under 200 characters');
+  }
+  const res = patterns.map((p) => new RegExp(p));
+  return {
+    name: "deck-leave-out",
+    setup(b) {
+      if (!res.length) return;
+      b.onLoad({ filter: /.*/ }, (a) => {
+        const path = a.path.replace(/\\/g, "/");
+        return res.some((r) => r.test(path)) ? { contents: "export default {};", loader: "js" } : undefined;
+      });
+    },
+  };
+}

package/permissions.json

@@ -112,6 +112,7 @@
     "fsTrash": "files",
     "fsWrite": "files",
     "fsWriteBytes": "files",
+    "ghAvatar": "network",
     "ghPrLineComment": "network",
     "ghPrThreads": "network",
     "ghRun": "processes",

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/shim/bridge.js

@@ -121,6 +121,7 @@ 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 ghAvatar = (...a) => b().ghAvatar(...a);
 export const ghPrLineComment = (...a) => b().ghPrLineComment(...a);
 export const ghPrThreads = (...a) => b().ghPrThreads(...a);
 export const ghRun = (...a) => b().ghRun(...a);

package/shim/p2p.js

@@ -10,7 +10,7 @@ const t = () => {
   return x;
 };
 
-export const cleanCode = (...a) => t().cleanCode(...a);
-export const newCode = (...a) => t().newCode(...a);
-export const selfId = (...a) => t().selfId(...a);
-export const share = (...a) => t().share(...a);
+export const myTeamId = (...a) => t().myTeamId(...a);
+export const subscribeTeams = (...a) => t().subscribeTeams(...a);
+export const teamChannel = (...a) => t().teamChannel(...a);
+export const teamsView = (...a) => t().teamsView(...a);

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.3",
+  "minDeck": "1.14.0",
   "permissions": []
 }

package/template/src/assets.d.ts

@@ -14,3 +14,5 @@ declare module "*.wasm" { const bytes: Uint8Array; export default bytes; }
 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; }
+// `import code from "./job.worker.ts?worker"`: that worker, bundled, as the text of a script.
+declare module "*?worker" { const code: string; export default code; }

package/types/core/app/p2p.d.ts

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

package/types/core/app/p2pshare.d.ts

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

package/types/core/app/settingsstore.d.ts

@@ -23,4 +23,6 @@ export declare function stepZoom(dir: -1 | 0 | 1): void;
 /** Current settings for non-React callers (the palette's providers). */
 export declare const getSettings: () => Settings;
 export declare function userName(): Promise<string>;
+/** Told after every change to the settings, from anywhere (Settings, a file edited elsewhere). */
+export declare const subscribeSettings: (cb: () => void) => () => void;
 export declare function useSettings(): Settings;

package/types/core/app/teams.d.ts

@@ -0,0 +1,122 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+import { share, type Json, type RoomLike, type P2pShare } from "./p2pshare";
+export type Member = {
+    id: string;
+    pub: string;
+    name: string;
+};
+/** A team's members, as the owner signed them. */
+export type MemberList = {
+    team: string;
+    name: string;
+    owner: string;
+    ownerPub: string;
+    rev: number;
+    members: Member[];
+    sig: string; /** The owner ended the team. */
+    ended?: boolean;
+};
+/** What this Deck keeps for a team. The key is secret: it names and encrypts the room. */
+export type Team = {
+    id: string;
+    key: string;
+    list: MemberList; /** Each member's name as last heard from them: theirs to change. */
+    seen?: Record<string, string>; /** When this Deck heard the team was ended: kept as a tombstone until ENDED_DAYS after. */
+    endedAt?: number;
+};
+/** A team as the Teams page shows it. */
+export interface TeamView {
+    id: string;
+    name: string;
+    owner: boolean;
+    ownerId: string;
+    members: (Member & {
+        me: boolean;
+        online: boolean;
+    })[];
+}
+export interface TeamChannel<T> {
+    /** Send to every member online, or to one (`to`: a member id). Nothing goes to anyone else. */
+    send(msg: T, to?: string): Promise<void>;
+    /** The members connected and checked right now, this Deck not included. */
+    online(): Member[];
+    close(): void;
+}
+export interface ChannelHandlers<T> {
+    message: (msg: T, from: Member) => void;
+    /** A member connected and was checked: send them what they need to catch up. */
+    joined?: (m: Member) => void;
+    left?: (m: Member) => void;
+}
+/** Where teams keep things and how they reach the network: a seam, so the check runs without either. */
+export interface TeamDeps {
+    read(name: string): Promise<string>;
+    write(name: string, text: string): Promise<void>;
+    /** This Deck's name, as the others see it. */
+    name(): Promise<string>;
+    /** A team's room: Trystero's, or a fake one. */
+    room(key: string, id: string): RoomLike;
+    /** Told when this Deck's name may have changed (the settings changed). */
+    watchName(cb: () => void): void;
+    share: typeof share;
+}
+/** For the check: replace the storage, the name and the network. */
+export declare function _setTeamDeps(d: Partial<TeamDeps>): void;
+/** A short code for an identity, to read out and compare: whoever invites shows theirs, whoever joins sees it. */
+export declare const fingerprint: (id: string) => string;
+/** A member's id: the first half of the hash of their public key. */
+export declare function idOf(pub: string): Promise<string>;
+/** Whether a list is the owner's own: signed by them, for this team, with ids that match the keys. */
+export declare function validList(l: MemberList, ownerPub?: string): Promise<boolean>;
+/** A plugin's line to a team: its messages, only to and from checked members. */
+export declare function teamChannel<T extends Json>(teamId: string, app: string, on: ChannelHandlers<T>): TeamChannel<T>;
+export declare function teamsView(): TeamView[];
+export declare function subscribeTeams(fn: () => void): () => void;
+/** This Deck's member id. */
+export declare const myTeamId: () => Promise<string>;
+/** Start a team, with this Deck as its owner and only member. */
+export declare function createTeam(name: string): Promise<string>;
+/** The owner takes someone off the team. */
+export declare function removeMember(teamId: string, memberId: string): Promise<void>;
+/**
+ * Leave a team: this Deck forgets it, and the others still list it until the owner removes it. The
+ * owner leaving ends the team for everyone: a last signed list says so, sent to those online now
+ * and, through the tombstones, to the others when they come back.
+ */
+export declare function leaveTeam(teamId: string): Promise<void>;
+type InviteMsg = {
+    t: "join";
+    id: string;
+    pub: string;
+    name: string;
+} | {
+    t: "team";
+    team: Team;
+};
+/**
+ * The owner invites: a code to give someone, and a share where they knock and are let in, as a
+ * live share's people are (`share.allow`). Whoever is let in is added to the team and sent it.
+ */
+export declare function inviteToTeam(teamId: string): Promise<{
+    code: string;
+    share: P2pShare<InviteMsg>;
+    fingerprint: string;
+    joined: Promise<string>;
+}>;
+/**
+ * Join a team with the code its owner gave you: knock, and once let in, say who you are and take
+ * the team the owner sends. Resolves with the team's id.
+ */
+/** A team offered by an invite: who owns it, to compare, and keeping it. */
+export interface TeamOffer {
+    id: string;
+    name: string;
+    owner: string;
+    fingerprint: string;
+    keep: () => Promise<string>;
+}
+export declare function joinTeam(code: string): Promise<{
+    share: P2pShare<InviteMsg>;
+    done: Promise<TeamOffer>;
+}>;
+export {};

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>;
@@ -1076,6 +1077,8 @@ export declare const gitAiCommitMsg: (dir: string, command: string, args: string
 export declare const ghRun: (dir: string, args: string[]) => Promise<string>;
 /** Pull request N's review threads, as GitHub's GraphQL JSON (parsed by prs.ts parseThreads). */
 export declare const ghPrThreads: (dir: string, number: number) => Promise<string>;
+/** The GitHub profile picture's address of whoever commits as `email` in this repo, "" when none. */
+export declare const ghAvatar: (dir: string, email: string) => Promise<string>;
 /** Comment on one line of a PR's diff: side "RIGHT" is the new version, "LEFT" the old. */
 export declare const ghPrLineComment: (dir: string, number: number, commit: string, path: string, line: number, side: "LEFT" | "RIGHT", body: string) => Promise<string>;
 export declare const ghThreadReply: (dir: string, thread: string, body: string) => Promise<string>;
@@ -1083,8 +1086,8 @@ export declare const ghThreadResolve: (dir: string, thread: string, resolve: boo
 /** The GitLab CLI, `glab mr …` only. Rejects with "glab-missing" when glab is not installed. */
 export declare const glabRun: (dir: string, args: string[]) => Promise<string>;
 /**
- * One GitLab REST request about this repo's merge requests (`projects/:id/merge_requests…` or
- * `user`). `fields` go as strings; `json` values must be objects or arrays.
+ * One GitLab REST request about this repo's merge requests (`projects/:id/merge_requests…`, `user`,
+ * or `avatar?email=` for someone's picture). `fields` go as strings; `json` values must be objects or arrays.
  */
 export declare const glabApi: (dir: string, method: "GET" | "POST" | "PUT", path: string, fields?: [string, string][], json?: Record<string, object>) => Promise<string>;
 /** The files that differ between two revisions. */

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/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 };
 }