@capybara-hq/plugin-sdk 0.1.0-rc.7 → 0.1.0-rc.8

package/agent-docs/plugin-format.md

@@ -10,11 +10,12 @@ A plugin is a directory, packed into a `.tgz` with `capybara-plugin pack` (the p
   skills/<name>/SKILL.md         skills (scanned unless plugin.json lists them)
   connectors/<id>.json           connector templates (scanned unless listed)
   agents/<name>.md               agent templates (scanned unless listed)
+  themes/<id>.json               themes (scanned unless listed)
   src/index.ts                   the extension (optional; bundled by the packer)
   migrations/*.sql, ui/**        extension migrations and UI files (optional)
 ```
 
-A plugin without `src/index.ts` is declarative: skills and templates only, no code runs.
+A plugin without `src/index.ts` is declarative: skills, templates and themes only, no code runs.
 
 ## plugin.json
 
@@ -37,6 +38,7 @@ file is strict: an unknown key is an error. Fields (agent templates are listed u
 | `skills` | array of object | no |
 | `connectorTemplates` | array of object | no |
 | `agents` | array of object | no |
+| `themes` | array of object | no |
 | `setupGuides` | array of object | no |
 | `extension` | object | no |
 <!-- /generated -->
@@ -48,10 +50,12 @@ Rules that the schema cannot show:
   release candidates, ranges on official packages are written `^0.1.0-rc.0`.
 - `description` is a string or `{ en, zh? }`; `displayName` is `{ zh, en }`.
 - `icon` is a `./` path to an `.svg` or `.png` inside the plugin.
-- `skills`, `connectorTemplates`, `agents` list paths starting with `./` that stay inside the plugin.
+- `skills`, `connectorTemplates`, `agents`, `themes` list paths starting with `./` that stay inside the plugin.
   Omit them to scan the default folders. Names and ids are unique within the plugin.
 - `dependencies`: plugin name plus semver range; no self-dependency.
 - `agents`: at most 64 templates (see `agent-templates`).
+- `themes`: at most 10 `<id>.json` files; the id is the file's base name. A theme file is checked
+  by `parseThemeFile` (schema `https://capybarahq.com/schemas/theme.v1.schema.json`).
 - `setupGuides` (at most 8): setup material shown where a person configures what the plugin
   brings. Each guide has an `id`, a `place` (`channel-connection`: 新建渠道 and the channel detail;
   the plugin's extension must provide `channel@1`), a `title` and `steps` (`{ en, zh? }`, plain

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "0.1.0-rc.7";
+export declare const SDK_VERSION = "0.1.0-rc.8";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -27,6 +27,10 @@ export * from "./setup-guide.js";
 export * from "./skill.js";
 export * from "./skill-invocation.js";
 export * from "./storage.js";
+export * from "./theme.js";
+export * from "./theme-assets.js";
+export * from "./theme-readability.js";
+export * from "./theme-tokens.generated.js";
 export * from "./tool.js";
 export * from "./tool-key.js";
 export * from "./ui.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export const SDK_VERSION = "0.1.0-rc.7";
+export const SDK_VERSION = "0.1.0-rc.8";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -27,6 +27,10 @@ export * from "./setup-guide.js";
 export * from "./skill.js";
 export * from "./skill-invocation.js";
 export * from "./storage.js";
+export * from "./theme.js";
+export * from "./theme-assets.js";
+export * from "./theme-readability.js";
+export * from "./theme-tokens.generated.js";
 export * from "./tool.js";
 export * from "./tool-key.js";
 export * from "./ui.js";

package/dist/plugin-manifest.d.ts

@@ -2,9 +2,11 @@ import { z } from "zod";
 import { type JsonSchema } from "./config-ui.js";
 import { type ConnectorTemplateSpec, type LocalizedName, type StaticExtensionManifest } from "./plugin-package.js";
 import { type PluginSetupGuide } from "./setup-guide.js";
+import { type PluginThemeRef } from "./theme.js";
 /**
  * The plugin manifest `.capybara-plugin/plugin.json` (package ecosystem spec §4.1). A plugin is a
- * bundle of at most one extension, skills and connector templates, packed as an npm-pack tgz:
+ * bundle of at most one extension, skills, connector templates, agent templates and themes, packed as
+ * an npm-pack tgz:
  *
  * ```
  * package/package.json                  npm metadata; version equals plugin.json version
@@ -12,13 +14,14 @@ import { type PluginSetupGuide } from "./setup-guide.js";
  * package/skills/<name>/SKILL.md        skills
  * package/connectors/<id>.json          connector templates ({@link ConnectorTemplateFile})
  * package/agents/<name>.md              agent templates (parsed by `parseAgentTemplate`)
+ * package/themes/<id>.json              themes (parsed by `parseThemeFile`)
  * package/dist/index.mjs                extension entry (only with an extension)
  * package/migrations/*.sql, package/ui/**
  * ```
  *
  * Paths start with `./` and stay inside the plugin root. Omitting `skills` / `connectorTemplates`
- * / `agents` means "scan `skills/*\/SKILL.md` / `connectors/*.json` / `agents/*.md`" (done by the
- * kernel when it reads the package). `extension` is written by the packer, never by hand.
+ * / `agents` / `themes` means "scan `skills/*\/SKILL.md` / `connectors/*.json` / `agents/*.md` /
+ * `themes/*.json`" (done by the kernel when it reads the package). `extension` is written by the packer, never by hand.
  *
  * The committed JSON Schema (`schemas/plugin.v1.schema.json`) is generated from
  * {@link PluginManifestSchema} by `pnpm gen:package-schemas` and drift-checked by
@@ -40,6 +43,8 @@ export declare const PLUGIN_MANIFEST_LIMITS: {
     readonly connectorTemplates: 20;
     /** Agent templates ({@link AGENT_TEMPLATE_LIMITS}`.perPlugin`). */
     readonly agents: 64;
+    /** Themes ({@link THEME_LIMITS}`.perPlugin`). */
+    readonly themes: 10;
     readonly descriptionChars: 1024;
     readonly publisherChars: 100;
     readonly displayNameChars: 100;
@@ -124,6 +129,8 @@ export interface PluginManifest {
     connectorTemplates?: PluginConnectorTemplateRef[];
     /** Agent templates; omitted = scan `agents/*.md`. */
     agents?: PluginAgentRef[];
+    /** Themes; omitted = scan `themes/*.json`. */
+    themes?: PluginThemeRef[];
     /**
      * Setup guides (spec `2026-11-08-plugin-setup-guides-design.md`): steps and template files the
      * kernel renders for a place (`channel-connection`); see {@link PluginSetupGuide}.

package/dist/plugin-manifest.js

@@ -6,9 +6,11 @@ import { defineExtension, EXTENSION_NAME_RE } from "./define-extension.js";
 import { CATALOG_ITEM_NAME_RE, CONNECTOR_TEMPLATE_LIMITS, isSafePackagePath, SEMVER_VERSION_RE, validateConnectorTemplate, } from "./plugin-package.js";
 import { hasUpperBound } from "./semver-range.js";
 import { SETUP_GUIDE_FILE_RE, SETUP_GUIDE_LANGUAGES, SETUP_GUIDE_LIMITS, SETUP_GUIDE_MODES, SETUP_GUIDE_PLACES, } from "./setup-guide.js";
+import { THEME_LIMITS, themeIdOf } from "./theme.js";
 /**
  * The plugin manifest `.capybara-plugin/plugin.json` (package ecosystem spec §4.1). A plugin is a
- * bundle of at most one extension, skills and connector templates, packed as an npm-pack tgz:
+ * bundle of at most one extension, skills, connector templates, agent templates and themes, packed as
+ * an npm-pack tgz:
  *
  * ```
  * package/package.json                  npm metadata; version equals plugin.json version
@@ -16,13 +18,14 @@ import { SETUP_GUIDE_FILE_RE, SETUP_GUIDE_LANGUAGES, SETUP_GUIDE_LIMITS, SETUP_G
  * package/skills/<name>/SKILL.md        skills
  * package/connectors/<id>.json          connector templates ({@link ConnectorTemplateFile})
  * package/agents/<name>.md              agent templates (parsed by `parseAgentTemplate`)
+ * package/themes/<id>.json              themes (parsed by `parseThemeFile`)
  * package/dist/index.mjs                extension entry (only with an extension)
  * package/migrations/*.sql, package/ui/**
  * ```
  *
  * Paths start with `./` and stay inside the plugin root. Omitting `skills` / `connectorTemplates`
- * / `agents` means "scan `skills/*\/SKILL.md` / `connectors/*.json` / `agents/*.md`" (done by the
- * kernel when it reads the package). `extension` is written by the packer, never by hand.
+ * / `agents` / `themes` means "scan `skills/*\/SKILL.md` / `connectors/*.json` / `agents/*.md` /
+ * `themes/*.json`" (done by the kernel when it reads the package). `extension` is written by the packer, never by hand.
  *
  * The committed JSON Schema (`schemas/plugin.v1.schema.json`) is generated from
  * {@link PluginManifestSchema} by `pnpm gen:package-schemas` and drift-checked by
@@ -44,6 +47,8 @@ export const PLUGIN_MANIFEST_LIMITS = {
     connectorTemplates: 20,
     /** Agent templates ({@link AGENT_TEMPLATE_LIMITS}`.perPlugin`). */
     agents: AGENT_TEMPLATE_LIMITS.perPlugin,
+    /** Themes ({@link THEME_LIMITS}`.perPlugin`). */
+    themes: THEME_LIMITS.perPlugin,
     descriptionChars: 1024,
     publisherChars: 100,
     displayNameChars: 100,
@@ -196,6 +201,12 @@ const schema = z
     }))
         .max(L.agents)
         .optional(),
+    themes: z
+        .array(z.strictObject({
+        path: dotPath("path").refine((p) => p.endsWith(".json") && CATALOG_ITEM_NAME_RE.test(themeIdOf(p)), { message: "path must be a <id>.json file with id matching ^[a-z0-9][a-z0-9-]{0,63}$" }),
+    }))
+        .max(L.themes)
+        .optional(),
     setupGuides: z.array(setupGuide).max(SETUP_GUIDE_LIMITS.guides).optional(),
     extension: extensionSection.optional(),
 })
@@ -235,6 +246,13 @@ const schema = z
             issue(["agents", i, "path"], `duplicate agent template path ${a.path}`);
         agentPaths.add(a.path);
     });
+    const themeIds = new Set();
+    m.themes?.forEach((t, i) => {
+        const id = themeIdOf(t.path);
+        if (themeIds.has(id))
+            issue(["themes", i, "path"], `duplicate theme id ${id}`);
+        themeIds.add(id);
+    });
     const guideIds = new Set();
     m.setupGuides?.forEach((g, i) => {
         if (guideIds.has(g.id))
@@ -269,8 +287,9 @@ const schema = z
     if (m.extension === undefined &&
         m.skills?.length === 0 &&
         m.connectorTemplates?.length === 0 &&
-        (m.agents === undefined || m.agents.length === 0)) {
-        issue([], "a plugin must contain an extension, a skill, a connector template or an agent template");
+        (m.agents === undefined || m.agents.length === 0) &&
+        (m.themes === undefined || m.themes.length === 0)) {
+        issue([], "a plugin must contain an extension, a skill, a connector template, an agent template or a theme");
     }
     const ext = m.extension;
     if (ext === undefined)

package/dist/theme-assets.d.ts

@@ -0,0 +1,39 @@
+import { type ParsedTheme } from "./theme.js";
+/**
+ * Parses a logo SVG (UTF-8, ≤ {@link THEME_LIMITS}`.svgBytes`) with a strict, namespace-aware
+ * XML parser and re-serializes it. The root must be an `svg` element in the SVG namespace with a
+ * numeric `viewBox`; its `width`, `height` and `class` are dropped. Rejected: a DOCTYPE (and so
+ * any entity declaration), processing instructions, a non-UTF-8 encoding, elements outside the
+ * SVG allowlist (`script`, `foreignObject`, `style`, …) or in the XHTML namespace, `style` and
+ * `on*` attributes, `href` / `xlink:href` not starting with `#`, `javascript:` / `vbscript:` in
+ * any value, quotes or a backslash in attribute values, any function other than `url(#id)`, colors
+ * (`rgb`, `rgba`, `hsl`, `hsla`) and transforms (`translate`, `rotate`, `scale`, `matrix`,
+ * `skewX`, `skewY`), a viewBox longer than 128 characters, and animation of `href`, `style` or event
+ * handlers. Comments, the XML declaration and elements / attributes in other namespaces (editor
+ * metadata) are dropped; CDATA becomes escaped text. Never throws.
+ */
+export declare function sanitizeThemeSvg(bytes: Uint8Array): {
+    svg: string;
+} | {
+    error: string;
+};
+/** A woff2 font: the `wOF2` signature and at most {@link THEME_LIMITS}`.fontBytes`. */
+export declare function checkWoff2(bytes: Uint8Array): string | undefined;
+/**
+ * A PNG logo: the PNG signature, an `IHDR` first chunk with a height of at least
+ * {@link THEME_LIMITS}`.pngMinHeight` pixels, and at most {@link THEME_LIMITS}`.pngBytes`.
+ */
+export declare function checkPng(bytes: Uint8Array): string | undefined;
+/**
+ * Resolves and checks the asset files of a parsed theme: each `fonts[].file` ({@link checkWoff2})
+ * and `logo.mark` / `logo.favicon` (`.svg` through {@link sanitizeThemeSvg}, `.png` through
+ * {@link checkPng}); the favicon must be square (SVG viewBox or PNG width = height). `files` holds the plugin's files keyed by their path without a leading
+ * `./`; the returned `assets` (the sanitized SVG bytes, the other files unchanged) use the same
+ * keys. Errors are `<field>: <reason>`, English; the total input size of the theme's distinct
+ * assets must stay within {@link THEME_LIMITS}`.assetsBytes`. That limit is per plugin, so a
+ * caller reading several themes also checks the sum over all of them (distinct paths).
+ */
+export declare function validateThemeAssets(theme: ParsedTheme, files: Map<string, Uint8Array>): {
+    assets: Map<string, Uint8Array>;
+    errors: string[];
+};