@50arms/plugin-sdk 0.0.0-stage → 0.2.51

package/dist/vite.d.ts

@@ -0,0 +1,133 @@
+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 `@50arms/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 {
+    /** The module exporting `CardView` and/or `CardListView`, relative to the project root. */
+    readonly entry?: string;
+    /**
+     * DX-6178: the card types the plugin's `CardView` is made for (card type keys, e.g. `["Bug"]`). Each becomes that type's DEFAULT view once the plugin's revision is approved
+     * 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 `@50arms/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()`.
+ *
+ * - The specifiers in `src/plugins/runtime-contract.ts` (`react`, `react/jsx-runtime`, `react-dom`, `@50arms/ui`, the card kit) stay
+ *   EXTERNAL: the page's import map answers them with the app's own modules, so the plugin shares its single React and design system.
+ * - 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, its Widgets, the stylesheets and the runtime majors.
+ */
+declare function danxPlugin(options?: DanxPluginOptions): Plugin;
+
+export { PLUGIN_ENTRY_FILE, danxPlugin };
+export type { DanxPluginOptions };

package/dist/vite.js

@@ -0,0 +1,303 @@
+// ../../src/plugins/runtime-contract.ts
+var CARD_KIT_MAJOR = 1;
+var CARD_KIT_LIBRARY = "@danxbot/card-kit";
+var PLUGIN_RUNTIME_LIBRARIES = [
+  { name: "react", major: 19 },
+  { name: "react-dom", major: 19 },
+  { name: "@50arms/ui", major: 35 },
+  { name: CARD_KIT_LIBRARY, major: CARD_KIT_MAJOR }
+];
+var PLUGIN_RUNTIME_SPECIFIERS = [
+  { specifier: "react", library: "react" },
+  { specifier: "react/jsx-runtime", library: "react" },
+  { specifier: "react-dom", library: "react-dom" },
+  { specifier: "@50arms/ui", library: "@50arms/ui" },
+  { specifier: `${CARD_KIT_LIBRARY}@${CARD_KIT_MAJOR}`, library: CARD_KIT_LIBRARY }
+];
+var PLUGIN_RUNTIME_LEGACY_ALIASES = [{ specifier: "@danxbot/ui", library: "@50arms/ui", major: 33 }];
+var PLUGIN_NEVER_BUNDLED_PACKAGES = [
+  ...PLUGIN_RUNTIME_LIBRARIES.map((library) => library.name).filter((name) => name !== CARD_KIT_LIBRARY),
+  // A source still importing the old name, built with the current SDK, would bundle a second copy of the design system; the build refuses it.
+  ...PLUGIN_RUNTIME_LEGACY_ALIASES.map((alias) => alias.specifier),
+  "scheduler",
+  "react-router"
+];
+function pluginRuntimeContract() {
+  return {
+    specifiers: PLUGIN_RUNTIME_SPECIFIERS.map((entry) => entry.specifier),
+    majors: Object.fromEntries(PLUGIN_RUNTIME_LIBRARIES.map((library) => [library.name, library.major]))
+  };
+}
+
+// src/manifest.ts
+import { createHash } from "node:crypto";
+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";
+var PLUGIN_VIEW_EXPORTS = [CARD_VIEW_EXPORT, CARD_LIST_VIEW_EXPORT];
+
+// src/manifest.ts
+function filesUnder(root, dir = root) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => entry.isDirectory() ? filesUnder(root, join(dir, entry.name)) : [join(dir, entry.name)]).sort();
+}
+function describeFile(root, file) {
+  const bytes = readFileSync(file);
+  return {
+    path: relative(root, file).split(sep).join("/"),
+    size: bytes.length,
+    sha256: createHash("sha256").update(bytes).digest("hex")
+  };
+}
+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 {
+    entry,
+    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, 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 DATE_RANGE_MS = { "24h": 864e5, "7d": 7 * 864e5, "30d": 30 * 864e5 };
+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";
+function bundledNeverPackage(moduleId) {
+  const normalised = moduleId.replaceAll("\\", "/");
+  return PLUGIN_NEVER_BUNDLED_PACKAGES.find((name) => normalised.includes(`/node_modules/${name}/`));
+}
+function danxPlugin(options = {}) {
+  const entry = options.entry ?? "src/index.tsx";
+  const widgets = options.widgets ?? [];
+  let viewExports = [];
+  return {
+    name: "danx-plugin",
+    config() {
+      return {
+        // The runtime-contract specifiers include `react/jsx-runtime`, never `react/jsx-dev-runtime`.
+        esbuild: { jsx: "automatic", jsxDev: false },
+        // Library mode leaves `process.env.NODE_ENV` for the consumer; a browser has no `process`.
+        define: { "process.env.NODE_ENV": JSON.stringify("production") },
+        build: {
+          target: "es2022",
+          sourcemap: true,
+          cssCodeSplit: false,
+          lib: { entry, formats: ["es"], fileName: () => PLUGIN_ENTRY_FILE },
+          rollupOptions: {
+            external: PLUGIN_RUNTIME_SPECIFIERS.map((shared) => shared.specifier),
+            output: {
+              chunkFileNames: "chunks/[name]-[hash].js",
+              assetFileNames: (asset) => asset.names.some((name) => name.endsWith(".css")) ? STYLESHEET_FILE : "assets/[name]-[hash][extname]"
+            }
+          }
+        }
+      };
+    },
+    generateBundle(_options, bundle) {
+      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 && widgets.length === 0) {
+        throw new Error(
+          `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) {
+          const duplicate = bundledNeverPackage(id);
+          if (duplicate === void 0) continue;
+          throw new Error(
+            `danx-plugin: ${output.fileName} would bundle a copy of ${duplicate}, which the app already serves (${id}). Import only the specifiers the runtime contract lists (${PLUGIN_RUNTIME_SPECIFIERS.map((shared) => shared.specifier).join(", ")}); the card kit also re-exports Link and useNavigate in place of react-router.`
+          );
+        }
+      }
+    },
+    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 ?? [], widgets);
+    }
+  };
+}
+export {
+  PLUGIN_ENTRY_FILE,
+  danxPlugin
+};

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 `@50arms/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 `@50arms/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,14 @@
+// ../../src/widget-surfaces/model.ts
+var DATE_RANGE_MS = { "24h": 864e5, "7d": 7 * 864e5, "30d": 30 * 864e5 };
+
+// ../../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
+};