@danxbot/plugin-sdk 0.2.41 → 0.2.42

package/README.md

@@ -1,6 +1,6 @@
 # @danxbot/plugin-sdk
 
-Build a 50 Arms **card-type plugin**: a small React bundle that gives a card type its own card view (`CardView`) and/or card-list view (`CardListView`), loaded into 50 Arms' own page with `import()`.
+Build a 50 Arms **plugin**: a small React bundle that gives a card type its own card view (`CardView`), adds a card-list view (`CardListView`), and/or adds **Widgets** to the Dashboard's Widget Library, loaded into 50 Arms' own page with `import()`.
 
 A plugin does not bundle React, `@danxbot/ui` or the card features. The app serves them under fixed import specifiers through an import map, so a plugin shares the app's single React and renders the app's own components:
 
@@ -45,6 +45,52 @@ A plugin styles itself with its own CSS (import a `.css` file; the build emits i
 
 The build refuses to bundle a copy of React, React DOM, `@danxbot/ui` or `react-router`: import only the specifiers above. For routing, use the kit's `Link` and `useNavigate`; `StandardCardPage` reads the plan the page was opened from out of the URL, so a view that wraps it passes only `{card, mutation}`.
 
+## Widgets
+
+A plugin can add Widgets: tiles a person places on their Dashboard from the Widget Library. A Widget is a component the entry exports plus a declaration, the built-in Widgets' own shape, from `@danxbot/plugin-sdk/widgets`:
+
+- `key`: the Widget's own key inside the plugin, lowercase words joined by `-` (a placement stores `plugin:<plugin key>:<key>`);
+- `size`: its `default`, `min` and `max` size in cells of the 24-column grid;
+- `config` and `settings`: the fields a placement may set (`config`, fixed by whoever edits the surface) and a viewer may override (`settings`). Each field is a `string`, `number` or `boolean` with a `default` and a `label` (`{ text: "..." }`, the words the Configure form shows); a `string` with `enum` also needs `optionLabels`, a label for every option;
+- `readsSurfaceSettings`: which surface-wide settings it reads (`date_range`, `keyword`);
+- `needsHostContext`: the host facts it cannot draw without (none on the Dashboard).
+
+`src/widgets.ts`:
+
+```ts
+import { declareWidget, type PluginWidget } from "@danxbot/plugin-sdk/widgets";
+
+export const OPEN_BUGS = declareWidget({
+  key: "open-bugs",
+  size: { default: { w: 6, h: 4 }, min: { w: 3, h: 2 }, max: { w: 24, h: 12 } },
+  config: {},
+  settings: { board: { type: "string", label: { text: "Board" }, default: "", maxLength: 200 } },
+  readsSurfaceSettings: [],
+  needsHostContext: [],
+});
+
+export const WIDGETS: PluginWidget[] = [
+  { export: "OpenBugs", title: "Open bugs", description: "How many bugs are open on each board.", declaration: OPEN_BUGS },
+];
+```
+
+The entry exports the component, which receives `WidgetProps` (its `config` and `settings` with the defaults filled in, the surface settings it reads, and `saveSettings` for the viewer's own choices) and reads its data with the card kit's hooks:
+
+```tsx
+import type { WidgetProps } from "@danxbot/plugin-sdk/widgets";
+import { OPEN_BUGS } from "./widgets";
+
+export function OpenBugs({ settings }: WidgetProps<typeof OPEN_BUGS.config, typeof OPEN_BUGS.settings>) {
+  return <p>{settings.board === "" ? "Every board" : settings.board}</p>;
+}
+```
+
+`vite.config.ts` names them: `danxPlugin({ widgets: WIDGETS })`. The build records them in `danx-plugin.json` (`widgets`) and refuses a Widget whose declaration cannot work or whose component the entry does not export; the upload checks the declarations again. A plugin may declare only Widgets and export no view; it then publishes without a screenshot (the preview draws views only).
+
+Who sees a plugin's Widget is who it runs for: a revision you publish runs for nobody until you try it, so your Widget is listed in your own Widget Library as "Not approved", and choosing it asks before it runs in your session; it is private to you. Once an approver approves the revision and a team admin makes it active, it is the team's.
+
+**For an agent asked to make a widget** ("make me a widget that shows ..."): work in the person's own repo, in one of their plugin projects or a new one; add the declaration, the component and the `widgets` option as above; commit; publish with `plugin_publish` from the person's own session (the revision is then theirs); then tell them to open their Widget Library and pick it.
+
 ## The card kit is a contract
 
 A runtime export of `@danxbot/card-kit@1`, and its parameters, is never removed or changed in place; the keys of the exported data types follow the Versioning section below. A breaking change is `@danxbot/card-kit@2`, served beside `@1` until no approved plugin revision needs it. A plugin's manifest records the majors it was built against, and the app refuses to run a revision built for a major it no longer serves.

package/dist/cli.js

@@ -5932,7 +5932,7 @@ ${output.trim()}`));
 }
 function isManifest(value) {
   const manifest = value;
-  return typeof manifest === "object" && manifest !== null && typeof manifest.entry === "string" && Array.isArray(manifest.exports) && Array.isArray(manifest.files) && manifest.files.every((file) => typeof file?.path === "string");
+  return typeof manifest === "object" && manifest !== null && typeof manifest.entry === "string" && Array.isArray(manifest.exports) && Array.isArray(manifest.widgets) && Array.isArray(manifest.files) && manifest.files.every((file) => typeof file?.path === "string");
 }
 async function readBuiltPlugin(projectDir) {
   const distDir = join3(resolve2(projectDir), PLUGIN_DIST_DIR);
@@ -5942,7 +5942,7 @@ async function readBuiltPlugin(projectDir) {
   } catch (err) {
     throw new Error(`danx-plugin: the build left no readable ${PLUGIN_DIST_DIR}/${PLUGIN_MANIFEST_FILE} in ${projectDir} (is the danxPlugin() preset in vite.config?): ${err.message}`);
   }
-  if (!isManifest(manifest)) throw new Error(`danx-plugin: ${PLUGIN_DIST_DIR}/${PLUGIN_MANIFEST_FILE} in ${projectDir} has no entry, no exports list or no files list of paths`);
+  if (!isManifest(manifest)) throw new Error(`danx-plugin: ${PLUGIN_DIST_DIR}/${PLUGIN_MANIFEST_FILE} in ${projectDir} has no entry, no exports list, no widgets list or no files list of paths`);
   const files = await Promise.all(manifest.files.map(async (file) => ({ path: file.path, bytes: await readFile2(join3(distDir, file.path)) })));
   return { manifest, files };
 }

package/dist/publish.d.ts

@@ -8,6 +8,95 @@ declare function sourceFiles(projectDir: string): Promise<string[]>;
 /** The project's source as a gzip-compressed tar archive, ready for `source_archive_base64`. The same files give the same bytes (fixed mtime, `portable`). */
 declare function archiveSource(projectDir: string): Promise<Buffer>;
 
+/** The names of the surface-wide settings, one per member of {@link SurfaceWideSettings} (a new member fails `tsc` here). */
+declare const SURFACE_WIDE_SETTING_KEYS: readonly ["date_range", "keyword"];
+type SurfaceWideSettingKey = (typeof SURFACE_WIDE_SETTING_KEYS)[number];
+
+/**
+ * DX-6233 / DX-6269 (PLAN-96 G-6) - the schema a Widget's config and settings are declared in, and the check of a value against it. Import-free of Node: the
+ * app imports this module at runtime (`@backend/widget-surfaces/value-schema.js`) to draw a placement's form and to check what is stored, and the server
+ * imports the same module to refuse a write the schema rejects, so the two can never disagree about what a Widget accepts.
+ *
+ * Every field carries its default, so the schema is also where a Widget's defaults live. A value is checked as a (possibly partial) set of the schema's
+ * fields: a key the schema does not name, or a value of the wrong type, is an issue, never read as a default.
+ */
+/**
+ * DX-6254 - the words that name a field, or one option of a field: a built-in Widget's message id, which the app looks up in the person's language, or the text a
+ * plugin's author wrote (a plugin brings no message catalog). The Configure form shows these, never a field's key or an option's stored id.
+ */
+type FieldText = {
+    readonly messageId: string;
+} | {
+    readonly text: string;
+};
+type ValueField = {
+    readonly type: "string";
+    readonly label: FieldText;
+    readonly default: string;
+    readonly maxLength?: number;
+    readonly enum?: readonly string[];
+    /** The words for each option of `enum`, by option id; present exactly when `enum` is, naming every option and no other. The stored value is the id. */
+    readonly optionLabels?: Readonly<Record<string, FieldText>>;
+} | {
+    readonly type: "number";
+    readonly label: FieldText;
+    readonly default: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly integer?: boolean;
+} | {
+    readonly type: "boolean";
+    readonly label: FieldText;
+    readonly default: boolean;
+};
+type ValueSchema = Readonly<Record<string, ValueField>>;
+
+/**
+ * DX-6269 (PLAN-96 G-6) - the layout rules of a widget surface, as pure functions: snapping to whole cells, a Widget's size limits, collision, clamping and the
+ * first free space. Import-free of Node. The app runs them live while a placement is dragged or resized (so what the person sees while dragging is what is
+ * saved), and the server runs the same functions to check every layout write and to place a new or changed placement, so the two never disagree.
+ *
+ * Positions are 0-based cells; the grid is `GRID_COLUMNS` wide with unlimited rows. A layout never has two boxes overlapping: moving, resizing or changing a
+ * box pushes whatever it now overlaps down to just below it, and whatever that one now overlaps in turn. The box being edited never moves for another.
+ */
+
+interface Size {
+    w: number;
+    h: number;
+}
+
+/**
+ * DX-6269 (PLAN-96 G-6; DX-6233 finding (d)) - a Widget's DECLARATION: the part of a Widget that is data - its key, the sizes it may take, its config and
+ * settings schemas, the surface-wide settings it reads and the host context it needs. The component that draws it, its title and its description are the
+ * app's (`frontend/src/lib/widgets/catalog.ts`). Import-free of Node, so the app, the server and DX-6254's plugin SDK all read the one declaration: the app
+ * to draw the Widget and its forms, the server to refuse a placement write the declaration rejects.
+ */
+
+type CellSize = Size;
+interface WidgetDeclaration<C extends ValueSchema = ValueSchema, S extends ValueSchema = ValueSchema> {
+    /** Stable identity, stored on every placement: lowercase words joined by `-` for a built-in, `plugin:<plugin key>:<widget key>` for a plugin's (`pluginWidgetKey`). */
+    readonly key: string;
+    /** The size a new placement gets, and the smallest and largest one may take, in cells. */
+    readonly size: {
+        readonly default: CellSize;
+        readonly min: CellSize;
+        readonly max: CellSize;
+    };
+    readonly config: C;
+    readonly settings: S;
+    readonly readsSurfaceSettings: readonly SurfaceWideSettingKey[];
+    /** The host context keys the Widget cannot render without. */
+    readonly needsHostContext: readonly string[];
+}
+
+/**
+ * DX-5170 / DX-4679 section 2 - the shape of `danx-plugin.json`, the manifest `@danxbot/plugin-sdk` writes beside a built plugin and the
+ * upload validator (DX-5171) checks before a revision is stored: the entry module and every listed file present with the stated size and
+ * sha256, nothing unlisted, and `runtime` naming the majors the plugin was built against (`runtime-contract.ts`).
+ *
+ * Pure types and constants; the writer is the SDK's, the checks are the server's.
+ */
+
 /** One file of the built plugin, other than the manifest itself (a file cannot hold its own hash). */
 interface PluginManifestFile {
     /** Relative to the output folder, `/` separated. */
@@ -33,10 +122,22 @@ interface PluginManifest {
      * Where two plugins declare one type, the one activated first wins (`plugins.activated_at`).
      */
     readonly cardTypes?: readonly string[];
-    /** DX-5282: which view modules the entry exports (`PLUGIN_VIEW_EXPORTS`), recorded at build from the entry chunk's real exports; never empty. */
+    /** DX-5282: which view modules the entry exports (`PLUGIN_VIEW_EXPORTS`), recorded at build from the entry chunk's real exports; empty only for a plugin that declares Widgets. */
     readonly exports: readonly PluginViewExport[];
+    /** DX-6254: the Widgets the plugin adds to the Widget Library, each drawn by one of the entry's exports; empty when it adds none. Checked by `manifestWidgetIssues`. */
+    readonly widgets: readonly PluginManifestWidget[];
     readonly files: readonly PluginManifestFile[];
 }
+/** DX-6254: one Widget a plugin declares. Its words are the author's own text: a plugin brings no message catalog. */
+interface PluginManifestWidget {
+    /** The name of the entry's export that draws the Widget, recorded at build only when the entry chunk really exports it. */
+    readonly export: string;
+    readonly title: string;
+    /** One sentence for the Widget Library: what the Widget shows. */
+    readonly description: string;
+    /** The built-in Widgets' own declaration, with `key` the Widget's key inside the plugin; a placement stores `plugin:<plugin key>:<key>`. */
+    readonly declaration: WidgetDeclaration;
+}
 
 /** The project's build output folder: the SDK's Vite preset builds into Vite's default `dist`. */
 declare const PLUGIN_DIST_DIR = "dist";

package/dist/publish.js

@@ -5927,7 +5927,7 @@ ${output.trim()}`));
 }
 function isManifest(value) {
   const manifest = value;
-  return typeof manifest === "object" && manifest !== null && typeof manifest.entry === "string" && Array.isArray(manifest.exports) && Array.isArray(manifest.files) && manifest.files.every((file) => typeof file?.path === "string");
+  return typeof manifest === "object" && manifest !== null && typeof manifest.entry === "string" && Array.isArray(manifest.exports) && Array.isArray(manifest.widgets) && Array.isArray(manifest.files) && manifest.files.every((file) => typeof file?.path === "string");
 }
 async function readBuiltPlugin(projectDir) {
   const distDir = join3(resolve2(projectDir), PLUGIN_DIST_DIR);
@@ -5937,7 +5937,7 @@ async function readBuiltPlugin(projectDir) {
   } catch (err) {
     throw new Error(`danx-plugin: the build left no readable ${PLUGIN_DIST_DIR}/${PLUGIN_MANIFEST_FILE} in ${projectDir} (is the danxPlugin() preset in vite.config?): ${err.message}`);
   }
-  if (!isManifest(manifest)) throw new Error(`danx-plugin: ${PLUGIN_DIST_DIR}/${PLUGIN_MANIFEST_FILE} in ${projectDir} has no entry, no exports list or no files list of paths`);
+  if (!isManifest(manifest)) throw new Error(`danx-plugin: ${PLUGIN_DIST_DIR}/${PLUGIN_MANIFEST_FILE} in ${projectDir} has no entry, no exports list, no widgets list or no files list of paths`);
   const files = await Promise.all(manifest.files.map(async (file) => ({ path: file.path, bytes: await readFile2(join3(distDir, file.path)) })));
   return { manifest, files };
 }

package/dist/vite.d.ts

@@ -1,5 +1,105 @@
 import { Plugin } from 'vite';
 
+/** The names of the surface-wide settings, one per member of {@link SurfaceWideSettings} (a new member fails `tsc` here). */
+declare const SURFACE_WIDE_SETTING_KEYS: readonly ["date_range", "keyword"];
+type SurfaceWideSettingKey = (typeof SURFACE_WIDE_SETTING_KEYS)[number];
+
+/**
+ * DX-6233 / DX-6269 (PLAN-96 G-6) - the schema a Widget's config and settings are declared in, and the check of a value against it. Import-free of Node: the
+ * app imports this module at runtime (`@backend/widget-surfaces/value-schema.js`) to draw a placement's form and to check what is stored, and the server
+ * imports the same module to refuse a write the schema rejects, so the two can never disagree about what a Widget accepts.
+ *
+ * Every field carries its default, so the schema is also where a Widget's defaults live. A value is checked as a (possibly partial) set of the schema's
+ * fields: a key the schema does not name, or a value of the wrong type, is an issue, never read as a default.
+ */
+/**
+ * DX-6254 - the words that name a field, or one option of a field: a built-in Widget's message id, which the app looks up in the person's language, or the text a
+ * plugin's author wrote (a plugin brings no message catalog). The Configure form shows these, never a field's key or an option's stored id.
+ */
+type FieldText = {
+    readonly messageId: string;
+} | {
+    readonly text: string;
+};
+type ValueField = {
+    readonly type: "string";
+    readonly label: FieldText;
+    readonly default: string;
+    readonly maxLength?: number;
+    readonly enum?: readonly string[];
+    /** The words for each option of `enum`, by option id; present exactly when `enum` is, naming every option and no other. The stored value is the id. */
+    readonly optionLabels?: Readonly<Record<string, FieldText>>;
+} | {
+    readonly type: "number";
+    readonly label: FieldText;
+    readonly default: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly integer?: boolean;
+} | {
+    readonly type: "boolean";
+    readonly label: FieldText;
+    readonly default: boolean;
+};
+type ValueSchema = Readonly<Record<string, ValueField>>;
+
+/**
+ * DX-6269 (PLAN-96 G-6) - the layout rules of a widget surface, as pure functions: snapping to whole cells, a Widget's size limits, collision, clamping and the
+ * first free space. Import-free of Node. The app runs them live while a placement is dragged or resized (so what the person sees while dragging is what is
+ * saved), and the server runs the same functions to check every layout write and to place a new or changed placement, so the two never disagree.
+ *
+ * Positions are 0-based cells; the grid is `GRID_COLUMNS` wide with unlimited rows. A layout never has two boxes overlapping: moving, resizing or changing a
+ * box pushes whatever it now overlaps down to just below it, and whatever that one now overlaps in turn. The box being edited never moves for another.
+ */
+
+interface Size {
+    w: number;
+    h: number;
+}
+
+/**
+ * DX-6269 (PLAN-96 G-6; DX-6233 finding (d)) - a Widget's DECLARATION: the part of a Widget that is data - its key, the sizes it may take, its config and
+ * settings schemas, the surface-wide settings it reads and the host context it needs. The component that draws it, its title and its description are the
+ * app's (`frontend/src/lib/widgets/catalog.ts`). Import-free of Node, so the app, the server and DX-6254's plugin SDK all read the one declaration: the app
+ * to draw the Widget and its forms, the server to refuse a placement write the declaration rejects.
+ */
+
+type CellSize = Size;
+interface WidgetDeclaration<C extends ValueSchema = ValueSchema, S extends ValueSchema = ValueSchema> {
+    /** Stable identity, stored on every placement: lowercase words joined by `-` for a built-in, `plugin:<plugin key>:<widget key>` for a plugin's (`pluginWidgetKey`). */
+    readonly key: string;
+    /** The size a new placement gets, and the smallest and largest one may take, in cells. */
+    readonly size: {
+        readonly default: CellSize;
+        readonly min: CellSize;
+        readonly max: CellSize;
+    };
+    readonly config: C;
+    readonly settings: S;
+    readonly readsSurfaceSettings: readonly SurfaceWideSettingKey[];
+    /** The host context keys the Widget cannot render without. */
+    readonly needsHostContext: readonly string[];
+}
+
+/**
+ * DX-5170 / DX-4679 section 2 - the shape of `danx-plugin.json`, the manifest `@danxbot/plugin-sdk` writes beside a built plugin and the
+ * upload validator (DX-5171) checks before a revision is stored: the entry module and every listed file present with the stated size and
+ * sha256, nothing unlisted, and `runtime` naming the majors the plugin was built against (`runtime-contract.ts`).
+ *
+ * Pure types and constants; the writer is the SDK's, the checks are the server's.
+ */
+
+/** DX-6254: one Widget a plugin declares. Its words are the author's own text: a plugin brings no message catalog. */
+interface PluginManifestWidget {
+    /** The name of the entry's export that draws the Widget, recorded at build only when the entry chunk really exports it. */
+    readonly export: string;
+    readonly title: string;
+    /** One sentence for the Widget Library: what the Widget shows. */
+    readonly description: string;
+    /** The built-in Widgets' own declaration, with `key` the Widget's key inside the plugin; a placement stores `plugin:<plugin key>:<key>`. */
+    readonly declaration: WidgetDeclaration;
+}
+
 /** The entry module every plugin build produces; the manifest names it and the app `import()`s it. */
 declare const PLUGIN_ENTRY_FILE = "index.js";
 interface DanxPluginOptions {
@@ -10,6 +110,12 @@ interface DanxPluginOptions {
      * and active, and the team can always set the type back to it. Leave it out for a plugin made for no particular type.
      */
     readonly cardTypes?: readonly string[];
+    /**
+     * DX-6254: the Widgets the plugin adds to the Widget Library. Each names the entry's export that draws it (a component taking `WidgetProps`), its title and
+     * description as the Library shows them, and its declaration (`declareWidget` from `@danxbot/plugin-sdk/widgets`, `key` being the Widget's own key, lowercase
+     * words). The build refuses a Widget whose declaration cannot work or whose export the entry does not have.
+     */
+    readonly widgets?: readonly PluginManifestWidget[];
 }
 /**
  * The Vite preset for a 50 Arms card-type plugin: an ES-module library build whose output the app loads with `import()`.
@@ -19,7 +125,7 @@ interface DanxPluginOptions {
  * - Anything else is bundled. Bundling a copy of a shared package (`react-dom/client` or `react-router` are not in the contract) would run a second copy
  *   beside the app's, so that fails the build instead of shipping.
  * - Code-split chunks load by relative import from the entry's folder; CSS is emitted as one `index.css`.
- * - `danx-plugin.json` is written beside the output: every file's size and sha256, the entry, the view modules it exports, the stylesheets and the runtime majors.
+ * - `danx-plugin.json` is written beside the output: every file's size and sha256, the entry, the view modules it exports, its Widgets, the stylesheets and the runtime majors.
  */
 declare function danxPlugin(options?: DanxPluginOptions): Plugin;
 

package/dist/vite.js

@@ -32,6 +32,7 @@ import { readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 
 // ../../src/plugins/plugin-manifest.ts
+var PLUGIN_KEY_PATTERN = "^[a-z0-9][a-z0-9_-]{0,63}$";
 var PLUGIN_MANIFEST_FILE = "danx-plugin.json";
 var CARD_VIEW_EXPORT = "CardView";
 var CARD_LIST_VIEW_EXPORT = "CardListView";
@@ -49,7 +50,7 @@ function describeFile(root, file) {
     sha256: createHash("sha256").update(bytes).digest("hex")
   };
 }
-function buildManifest(outDir, entry, exports, cardTypes = []) {
+function buildManifest(outDir, entry, exports, cardTypes, widgets) {
   const files = filesUnder(outDir).map((file) => describeFile(outDir, file)).filter((file) => file.path !== PLUGIN_MANIFEST_FILE);
   if (!files.some((file) => file.path === entry)) throw new Error(`danx-plugin: the build produced no entry module ${entry} in ${outDir}`);
   return {
@@ -57,18 +58,177 @@ function buildManifest(outDir, entry, exports, cardTypes = []) {
     styles: files.filter((file) => file.path.endsWith(".css")).map((file) => file.path),
     runtime: pluginRuntimeContract().majors,
     exports: [...exports],
+    widgets: [...widgets],
     // DX-6178: the card types the plugin's card view is made for, written only when the author named some.
     ...cardTypes.length === 0 ? {} : { cardTypes: [...cardTypes] },
     files
   };
 }
-function writeManifest(outDir, entry, exports, cardTypes = []) {
-  const manifest = buildManifest(outDir, entry, exports, cardTypes);
+function writeManifest(outDir, entry, exports, cardTypes, widgets) {
+  const manifest = buildManifest(outDir, entry, exports, cardTypes, widgets);
   writeFileSync(join(outDir, PLUGIN_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}
 `);
   return manifest;
 }
 
+// ../../src/widget-surfaces/model.ts
+var GRID_COLUMNS = 24;
+var SURFACE_WIDE_SETTING_KEYS = ["date_range", "keyword"];
+
+// ../../src/widget-surfaces/value-schema.ts
+function fieldIssue(field, schema, value) {
+  switch (schema.type) {
+    case "string":
+      if (typeof value !== "string") return { field, rule: "notText" };
+      if (schema.maxLength !== void 0 && value.length > schema.maxLength) return { field, rule: "tooLong", limit: schema.maxLength };
+      if (schema.enum !== void 0 && !schema.enum.includes(value)) return { field, rule: "notOneOf", options: schema.enum };
+      return null;
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) return { field, rule: "notNumber" };
+      if (schema.integer === true && !Number.isInteger(value)) return { field, rule: "notWhole" };
+      if (schema.min !== void 0 && value < schema.min) return { field, rule: "tooSmall", limit: schema.min };
+      if (schema.max !== void 0 && value > schema.max) return { field, rule: "tooLarge", limit: schema.max };
+      return null;
+    case "boolean":
+      return typeof value === "boolean" ? null : { field, rule: "notBoolean" };
+  }
+}
+function valueIssues(schema, values) {
+  if (typeof values !== "object" || values === null || Array.isArray(values)) return [{ field: "", rule: "notObject" }];
+  const issues = [];
+  for (const [name, value] of Object.entries(values)) {
+    const field = schema[name];
+    if (field === void 0) issues.push({ field: name, rule: "unknownField" });
+    else {
+      const issue = fieldIssue(name, field, value);
+      if (issue !== null) issues.push(issue);
+    }
+  }
+  return issues;
+}
+var blank = (text) => ("messageId" in text ? text.messageId : text.text).trim() === "";
+function labelIssues(schema) {
+  const issues = [];
+  for (const [name, field] of Object.entries(schema)) {
+    if (blank(field.label)) issues.push(`field "${name}" has an empty label`);
+    if (field.type !== "string") continue;
+    const options = field.enum ?? [];
+    const labelled = Object.keys(field.optionLabels ?? {});
+    if (field.enum !== void 0 && field.optionLabels === void 0) issues.push(`field "${name}" offers options and labels none of them`);
+    if (field.enum === void 0 && field.optionLabels !== void 0) issues.push(`field "${name}" labels options it does not offer`);
+    for (const option of options) if (!labelled.includes(option)) issues.push(`field "${name}" has no label for option "${option}"`);
+    for (const option of labelled) if (!options.includes(option) && field.enum !== void 0) issues.push(`field "${name}" labels "${option}", which is not one of its options`);
+    for (const [option, text] of Object.entries(field.optionLabels ?? {})) if (blank(text)) issues.push(`field "${name}" has an empty label for option "${option}"`);
+  }
+  return issues;
+}
+function defaultsOf(schema) {
+  return Object.fromEntries(Object.entries(schema).map(([name, field]) => [name, field.default]));
+}
+
+// ../../src/widget-surfaces/declaration.ts
+var WIDGET_KEY_SHAPE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+var PLUGIN_KEY_SHAPE = new RegExp(PLUGIN_KEY_PATTERN);
+var WIDGET_KEY_MAX_LENGTH = 120;
+var PLUGIN_WIDGET_PREFIX = "plugin:";
+function pluginWidgetKey(pluginKey, widgetKey) {
+  return `${PLUGIN_WIDGET_PREFIX}${pluginKey}:${widgetKey}`;
+}
+function declarationBodyIssues(def) {
+  const issues = [];
+  const { min, max, default: initial } = def.size;
+  for (const [label, size] of [["min", min], ["default", initial], ["max", max]]) {
+    if (!Number.isInteger(size.w) || !Number.isInteger(size.h) || size.w < 1 || size.h < 1) issues.push(`${label} size ${size.w}x${size.h} is not whole cells`);
+    if (size.w > GRID_COLUMNS) issues.push(`${label} width ${size.w} is wider than the ${GRID_COLUMNS}-column grid`);
+  }
+  if (initial.w < min.w || initial.h < min.h || initial.w > max.w || initial.h > max.h) issues.push("the default size is outside the min and max sizes");
+  for (const scope of ["config", "settings"]) {
+    for (const issue of valueIssues(def[scope], defaultsOf(def[scope]))) issues.push(`${scope} default: ${JSON.stringify(issue)}`);
+    for (const issue of labelIssues(def[scope])) issues.push(`${scope}: ${issue}`);
+  }
+  for (const key of def.readsSurfaceSettings) {
+    if (!SURFACE_WIDE_SETTING_KEYS.includes(key)) issues.push(`"${key}" is not a surface-wide setting`);
+  }
+  if (new Set(def.readsSurfaceSettings).size !== def.readsSurfaceSettings.length) issues.push("readsSurfaceSettings names a setting twice");
+  return issues;
+}
+
+// ../../src/plugins/manifest-widgets.ts
+var EXPORT_SHAPE = /^[A-Z][A-Za-z0-9]*$/;
+var MAX_WIDGET_TITLE_LENGTH = 80;
+var MAX_WIDGET_DESCRIPTION_LENGTH = 300;
+var MAX_PLUGIN_WIDGETS = 32;
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var keysAre = (value, required, optional = []) => required.every((key) => key in value) && Object.keys(value).every((key) => required.includes(key) || optional.includes(key));
+var isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+var isFieldText = (value) => isObject(value) && (keysAre(value, ["messageId"]) && typeof value.messageId === "string" || keysAre(value, ["text"]) && typeof value.text === "string");
+var isSize = (value) => isObject(value) && keysAre(value, ["w", "h"]) && typeof value.w === "number" && typeof value.h === "number";
+var isOptionalNumber = (value) => value === void 0 || typeof value === "number";
+function fieldShapeIsValid(field) {
+  if (!isObject(field) || !isFieldText(field.label)) return false;
+  switch (field.type) {
+    case "string":
+      return keysAre(field, ["type", "label", "default"], ["maxLength", "enum", "optionLabels"]) && typeof field.default === "string" && isOptionalNumber(field.maxLength) && (field.enum === void 0 || isStringArray(field.enum)) && (field.optionLabels === void 0 || isObject(field.optionLabels) && Object.values(field.optionLabels).every(isFieldText));
+    case "number":
+      return keysAre(field, ["type", "label", "default"], ["min", "max", "integer"]) && typeof field.default === "number" && isOptionalNumber(field.min) && isOptionalNumber(field.max) && (field.integer === void 0 || typeof field.integer === "boolean");
+    case "boolean":
+      return keysAre(field, ["type", "label", "default"]) && typeof field.default === "boolean";
+    default:
+      return false;
+  }
+}
+function declarationShapeIssues(value) {
+  if (!isObject(value) || !keysAre(value, ["key", "size", "config", "settings", "readsSurfaceSettings", "needsHostContext"])) {
+    return ["the declaration must hold exactly key, size, config, settings, readsSurfaceSettings and needsHostContext"];
+  }
+  const issues = [];
+  if (typeof value.key !== "string") issues.push("the key must be text");
+  if (!isObject(value.size) || !keysAre(value.size, ["default", "min", "max"]) || ![value.size.default, value.size.min, value.size.max].every(isSize)) issues.push("size must hold default, min and max, each {w, h} in cells");
+  for (const scope of ["config", "settings"]) {
+    const schema = value[scope];
+    if (!isObject(schema)) issues.push(`${scope} must be an object of fields`);
+    else for (const [name, field] of Object.entries(schema)) if (!fieldShapeIsValid(field)) issues.push(`${scope} field "${name}" is not a string, number or boolean field with a label and a default`);
+  }
+  if (!isStringArray(value.readsSurfaceSettings)) issues.push("readsSurfaceSettings must be a list of setting names");
+  if (!isStringArray(value.needsHostContext)) issues.push("needsHostContext must be a list of host context keys");
+  return issues;
+}
+function manifestWidgetIssues(widgets, pluginKey) {
+  if (!Array.isArray(widgets)) return ["widgets must be a list"];
+  if (widgets.length > MAX_PLUGIN_WIDGETS) return [`a plugin declares at most ${MAX_PLUGIN_WIDGETS} Widgets`];
+  const issues = [];
+  const exports = /* @__PURE__ */ new Set();
+  const keys = /* @__PURE__ */ new Set();
+  widgets.forEach((widget, index) => {
+    if (!isObject(widget) || !keysAre(widget, ["export", "title", "description", "declaration"])) {
+      issues.push(`widget ${index + 1}: must hold exactly export, title, description and declaration`);
+      return;
+    }
+    const name = typeof widget.export === "string" ? widget.export : `widget ${index + 1}`;
+    const say = (issue) => issues.push(`${name}: ${issue}`);
+    if (typeof widget.export !== "string" || !EXPORT_SHAPE.test(widget.export) || PLUGIN_VIEW_EXPORTS.includes(widget.export)) {
+      say(`the export must be a component name (a capital letter, then letters and digits), and not ${PLUGIN_VIEW_EXPORTS.join(" or ")}`);
+    } else if (exports.has(widget.export)) say("two Widgets name this export");
+    else exports.add(widget.export);
+    for (const [field, max] of [["title", MAX_WIDGET_TITLE_LENGTH], ["description", MAX_WIDGET_DESCRIPTION_LENGTH]]) {
+      const text = widget[field];
+      if (typeof text !== "string" || text.trim() === "" || text.length > max) say(`the ${field} must be text of 1 to ${max} characters`);
+    }
+    const shape = declarationShapeIssues(widget.declaration);
+    if (shape.length > 0) {
+      for (const issue of shape) say(issue);
+      return;
+    }
+    const declaration = widget.declaration;
+    if (!WIDGET_KEY_SHAPE.test(declaration.key)) say(`the key "${declaration.key}" is not lowercase words joined by "-"`);
+    else if (keys.has(declaration.key)) say(`two Widgets have the key "${declaration.key}"`);
+    else keys.add(declaration.key);
+    if (pluginKey !== null && pluginWidgetKey(pluginKey, declaration.key).length > WIDGET_KEY_MAX_LENGTH) say(`its stored key ${pluginWidgetKey(pluginKey, declaration.key)} is longer than ${WIDGET_KEY_MAX_LENGTH} characters`);
+    for (const issue of declarationBodyIssues(declaration)) say(issue);
+  });
+  return issues;
+}
+
 // src/vite.ts
 var PLUGIN_ENTRY_FILE = "index.js";
 var STYLESHEET_FILE = "index.css";
@@ -78,6 +238,7 @@ function bundledNeverPackage(moduleId) {
 }
 function danxPlugin(options = {}) {
   const entry = options.entry ?? "src/index.tsx";
+  const widgets = options.widgets ?? [];
   let viewExports = [];
   return {
     name: "danx-plugin",
@@ -106,11 +267,15 @@ function danxPlugin(options = {}) {
       const entryChunk = Object.values(bundle).find((output) => output.type === "chunk" && output.isEntry);
       if (entryChunk?.type !== "chunk") throw new Error(`danx-plugin: the build produced no entry chunk for ${entry}`);
       viewExports = PLUGIN_VIEW_EXPORTS.filter((name) => entryChunk.exports.includes(name));
-      if (viewExports.length === 0) {
+      if (viewExports.length === 0 && widgets.length === 0) {
         throw new Error(
-          `danx-plugin: ${entry} must export ${PLUGIN_VIEW_EXPORTS.join(" and/or ")}, but it exports ${entryChunk.exports.length === 0 ? "nothing" : entryChunk.exports.join(", ")}.`
+          `danx-plugin: ${entry} must export ${PLUGIN_VIEW_EXPORTS.join(" and/or ")}, or the plugin must declare Widgets, but it exports ${entryChunk.exports.length === 0 ? "nothing" : entryChunk.exports.join(", ")}.`
         );
       }
+      const issues = manifestWidgetIssues(widgets, null);
+      if (issues.length > 0) throw new Error(`danx-plugin: the plugin's Widgets cannot be used: ${issues.join("; ")}`);
+      const missing = widgets.filter((widget) => !entryChunk.exports.includes(widget.export)).map((widget) => widget.export);
+      if (missing.length > 0) throw new Error(`danx-plugin: ${entry} does not export ${missing.join(", ")}, which the plugin's Widgets name as their components.`);
       for (const output of Object.values(bundle)) {
         if (output.type !== "chunk") continue;
         for (const id of output.moduleIds) {
@@ -124,7 +289,7 @@ function danxPlugin(options = {}) {
     },
     writeBundle(output) {
       if (output.dir === void 0) throw new Error("danx-plugin: the build has no output directory to write the manifest into");
-      writeManifest(output.dir, PLUGIN_ENTRY_FILE, viewExports, options.cardTypes ?? []);
+      writeManifest(output.dir, PLUGIN_ENTRY_FILE, viewExports, options.cardTypes ?? [], widgets);
     }
   };
 }

package/dist/widgets.d.ts

@@ -0,0 +1,142 @@
+declare const DATE_RANGES: readonly ["24h", "7d", "30d"];
+type DateRange = (typeof DATE_RANGES)[number];
+/** Every surface-wide setting a surface stores a default for. */
+interface SurfaceWideSettings {
+    date_range: DateRange;
+    keyword: string;
+}
+/** The names of the surface-wide settings, one per member of {@link SurfaceWideSettings} (a new member fails `tsc` here). */
+declare const SURFACE_WIDE_SETTING_KEYS: readonly ["date_range", "keyword"];
+type SurfaceWideSettingKey = (typeof SURFACE_WIDE_SETTING_KEYS)[number];
+
+/**
+ * DX-6233 / DX-6269 (PLAN-96 G-6) - the schema a Widget's config and settings are declared in, and the check of a value against it. Import-free of Node: the
+ * app imports this module at runtime (`@backend/widget-surfaces/value-schema.js`) to draw a placement's form and to check what is stored, and the server
+ * imports the same module to refuse a write the schema rejects, so the two can never disagree about what a Widget accepts.
+ *
+ * Every field carries its default, so the schema is also where a Widget's defaults live. A value is checked as a (possibly partial) set of the schema's
+ * fields: a key the schema does not name, or a value of the wrong type, is an issue, never read as a default.
+ */
+/**
+ * DX-6254 - the words that name a field, or one option of a field: a built-in Widget's message id, which the app looks up in the person's language, or the text a
+ * plugin's author wrote (a plugin brings no message catalog). The Configure form shows these, never a field's key or an option's stored id.
+ */
+type FieldText = {
+    readonly messageId: string;
+} | {
+    readonly text: string;
+};
+type ValueField = {
+    readonly type: "string";
+    readonly label: FieldText;
+    readonly default: string;
+    readonly maxLength?: number;
+    readonly enum?: readonly string[];
+    /** The words for each option of `enum`, by option id; present exactly when `enum` is, naming every option and no other. The stored value is the id. */
+    readonly optionLabels?: Readonly<Record<string, FieldText>>;
+} | {
+    readonly type: "number";
+    readonly label: FieldText;
+    readonly default: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly integer?: boolean;
+} | {
+    readonly type: "boolean";
+    readonly label: FieldText;
+    readonly default: boolean;
+};
+type ValueSchema = Readonly<Record<string, ValueField>>;
+type FieldValue<F extends ValueField> = F extends {
+    type: "string";
+} ? string : F extends {
+    type: "number";
+} ? number : boolean;
+type ValuesOf<S extends ValueSchema> = {
+    [K in keyof S]: FieldValue<S[K]>;
+};
+
+/**
+ * DX-6269 (PLAN-96 G-6) - the layout rules of a widget surface, as pure functions: snapping to whole cells, a Widget's size limits, collision, clamping and the
+ * first free space. Import-free of Node. The app runs them live while a placement is dragged or resized (so what the person sees while dragging is what is
+ * saved), and the server runs the same functions to check every layout write and to place a new or changed placement, so the two never disagree.
+ *
+ * Positions are 0-based cells; the grid is `GRID_COLUMNS` wide with unlimited rows. A layout never has two boxes overlapping: moving, resizing or changing a
+ * box pushes whatever it now overlaps down to just below it, and whatever that one now overlaps in turn. The box being edited never moves for another.
+ */
+
+interface Size {
+    w: number;
+    h: number;
+}
+
+/**
+ * DX-6269 (PLAN-96 G-6; DX-6233 finding (d)) - a Widget's DECLARATION: the part of a Widget that is data - its key, the sizes it may take, its config and
+ * settings schemas, the surface-wide settings it reads and the host context it needs. The component that draws it, its title and its description are the
+ * app's (`frontend/src/lib/widgets/catalog.ts`). Import-free of Node, so the app, the server and DX-6254's plugin SDK all read the one declaration: the app
+ * to draw the Widget and its forms, the server to refuse a placement write the declaration rejects.
+ */
+
+type CellSize = Size;
+interface WidgetDeclaration<C extends ValueSchema = ValueSchema, S extends ValueSchema = ValueSchema> {
+    /** Stable identity, stored on every placement: lowercase words joined by `-` for a built-in, `plugin:<plugin key>:<widget key>` for a plugin's (`pluginWidgetKey`). */
+    readonly key: string;
+    /** The size a new placement gets, and the smallest and largest one may take, in cells. */
+    readonly size: {
+        readonly default: CellSize;
+        readonly min: CellSize;
+        readonly max: CellSize;
+    };
+    readonly config: C;
+    readonly settings: S;
+    readonly readsSurfaceSettings: readonly SurfaceWideSettingKey[];
+    /** The host context keys the Widget cannot render without. */
+    readonly needsHostContext: readonly string[];
+}
+/** Identity function that lets TypeScript infer the schemas, so a component's `config` and `settings` props are typed from them. */
+declare function declareWidget<C extends ValueSchema, S extends ValueSchema>(declaration: WidgetDeclaration<C, S>): WidgetDeclaration<C, S>;
+
+/**
+ * DX-6254 (moved from the app's `catalog.ts`, DX-6233) - what a host hands a Widget's component: the contract between the app and every Widget, a built-in's or a
+ * plugin's. Types only and import-free of Node, so the app and `@danxbot/plugin-sdk/widgets` read this one module.
+ */
+
+/** The extra facts about where a host is that a host passes to a Widget (for a plan page, `{ plan: "96" }`); the Dashboard passes none. */
+type HostContext = Readonly<Record<string, string>>;
+interface WidgetProps<C extends ValueSchema, S extends ValueSchema> {
+    /** The Widget's config defaults, then the placement's config. */
+    config: ValuesOf<C>;
+    /** The Widget's defaults, then the placement's defaults (everyone's), then the viewer's own override. */
+    settings: ValuesOf<S>;
+    /** Only the surface-wide settings the Widget declares it reads (`readsSurfaceSettings`); never the others. */
+    surface: Partial<SurfaceWideSettings>;
+    host: HostContext;
+    placement: {
+        readonly id: number;
+        readonly name: string | null;
+    };
+    /** Saves the viewer's own override of some of the Widget's settings for this placement. Rejects with the server's refusal. */
+    saveSettings: (patch: Partial<ValuesOf<S>>) => Promise<void>;
+}
+
+/**
+ * DX-5170 / DX-4679 section 2 - the shape of `danx-plugin.json`, the manifest `@danxbot/plugin-sdk` writes beside a built plugin and the
+ * upload validator (DX-5171) checks before a revision is stored: the entry module and every listed file present with the stated size and
+ * sha256, nothing unlisted, and `runtime` naming the majors the plugin was built against (`runtime-contract.ts`).
+ *
+ * Pure types and constants; the writer is the SDK's, the checks are the server's.
+ */
+
+/** DX-6254: one Widget a plugin declares. Its words are the author's own text: a plugin brings no message catalog. */
+interface PluginManifestWidget {
+    /** The name of the entry's export that draws the Widget, recorded at build only when the entry chunk really exports it. */
+    readonly export: string;
+    readonly title: string;
+    /** One sentence for the Widget Library: what the Widget shows. */
+    readonly description: string;
+    /** The built-in Widgets' own declaration, with `key` the Widget's key inside the plugin; a placement stores `plugin:<plugin key>:<key>`. */
+    readonly declaration: WidgetDeclaration;
+}
+
+export { declareWidget };
+export type { CellSize, FieldText, HostContext, PluginManifestWidget as PluginWidget, SurfaceWideSettings, ValueField, ValueSchema, ValuesOf, WidgetDeclaration, WidgetProps };

package/dist/widgets.js

@@ -0,0 +1,11 @@
+// ../../src/plugins/plugin-manifest.ts
+var PLUGIN_KEY_PATTERN = "^[a-z0-9][a-z0-9_-]{0,63}$";
+
+// ../../src/widget-surfaces/declaration.ts
+function declareWidget(declaration) {
+  return declaration;
+}
+var PLUGIN_KEY_SHAPE = new RegExp(PLUGIN_KEY_PATTERN);
+export {
+  declareWidget
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danxbot/plugin-sdk",
-  "version": "0.2.41",
-  "description": "SDK for building 50 Arms card-type plugins (DX-5170): the card kit's type declarations, a Vite preset that builds a plugin against the app's shared runtime and writes its manifest, and the danx-plugin CLI.",
+  "version": "0.2.42",
+  "description": "SDK for building 50 Arms plugins (DX-5170): the card kit's type declarations, the Widget declaration kit, a Vite preset that builds a plugin against the app's shared runtime and writes its manifest, and the danx-plugin CLI.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -18,6 +18,10 @@
     "./publish": {
       "types": "./dist/publish.d.ts",
       "default": "./dist/publish.js"
+    },
+    "./widgets": {
+      "types": "./dist/widgets.d.ts",
+      "default": "./dist/widgets.js"
     }
   },
   "files": [
@@ -46,7 +50,7 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@danxbot/ui": "30.1.0",
+    "@danxbot/ui": "30.1.3",
     "@types/node": "^22.0.0",
     "@types/react": "^19.2.2",
     "esbuild": "^0.25.0",