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

package/agent-docs/extension-points/sandbox.md

@@ -2,7 +2,7 @@
 
 <!-- generated:extension-point -->
 - Name: `sandbox` (a ref is `sandbox@<major>`)
-- Runs an environment's instance and keeps its files for agents' commands (Docker, E2B).
+- Runs a device's instance and keeps its files for agents' commands (Docker, E2B).
 - Providers: one at a time
 - Enabled per org: no
 - Brokered by the platform: yes (extensions use it only through `ctx`)
@@ -10,6 +10,6 @@
 
 Contract: SandboxProvider (`sandbox.ts`)
 
-The kernel accepts only `sandbox@2`. An environment is one instance plus a file system that outlives it. Implement the file system (`createFileSystem`, `destroyFileSystem`, `destroyFileSystemByName`), the instance on it (`create`, which throws `FileSystemGoneError` when the file system is gone instead of making an empty one; `resume`, `suspend`; `destroy` and `destroyByName`, which drop the instance and keep the files), and the instance's `exec`, `readFile`, `writeFile`, `stat`, `killAll` and `killTagged` (`concurrentExec` is required: several conversations share one instance). Aborting a command must kill it. Locking, suspension timing and destruction are the kernel's job, not yours. Never publish a docker socket proxy on a host address.
+The kernel accepts only `sandbox@2`. A device is one instance plus a file system that outlives it. Implement the file system (`createFileSystem`, `destroyFileSystem`, `destroyFileSystemByName`), the instance on it (`create`, which throws `FileSystemGoneError` when the file system is gone instead of making an empty one; `resume`, `suspend`; `destroy` and `destroyByName`, which drop the instance and keep the files), and the instance's `exec`, `readFile`, `writeFile`, `stat`, `killAll` and `killTagged` (`concurrentExec` is required: several conversations share one instance). Aborting a command must kill it. Locking, suspension timing and destruction are the kernel's job, not yours. Never publish a docker socket proxy on a host address.
 
 See `extensions` for the rules every extension follows.

package/agent-docs/extensions.md

@@ -44,7 +44,7 @@ look like `channel@1`: name and major version. The registered points:
 <!-- generated:extension-points -->
 | Extension point | Providers | Per org | What it is |
 |---|---|---|---|
-| `sandbox` | single | no | Runs an environment's instance and keeps its files for agents' commands (Docker, E2B). |
+| `sandbox` | single | no | Runs a device's instance and keeps its files for agents' commands (Docker, E2B). |
 | `config-source` | single | no | Supplies deployment configuration from an external store such as Nacos. |
 | `secret-store` | single | no | Stores and resolves secrets (connector credentials, secret config) outside the database. |
 | `object-store` | single | no | Stores files and artifacts in S3-compatible object storage, with presigned uploads. |

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/ctx.d.ts

@@ -198,15 +198,20 @@ export interface ExtensionContext {
      * 界面贡献的运行时（清单 `ui` + `permissions.ui`）：
      * - `view` / `action`：只能在 `setup` 期间注册，id 是清单里 kind view 的贡献 id；
      *   `action` 收到视图里按钮或表单提交（`args.actionId` 区分是哪一个）；
-     * - `invalidate`：告诉内核「这个贡献变了」，打开着它的网页会重新取视图（经 bus，跨副本）；
+     * - `invalidate`：告诉内核「这个贡献变了」，打开着它的网页会重新取视图（经 bus，跨副本）；a
+     *   `platform.page` contribution takes no `orgId` (it refreshes the admin console), every other
+     *   contribution requires one;
      * - `verifyEmbedToken`：校验 embed 页面拿到的嵌入令牌，只认签给本插件、未过期的，且此刻插件仍在该组织启用、
-     *   调用者仍是 active 成员（组织页面还要求 member 以上），否则返回 null；返回的 `role` 是此刻的角色。
+     *   调用者仍是 active 成员，角色仍满足位置的 minRole，否则返回 null；返回的 `role` 是此刻的角色。A
+     *   platform-scope token (`scope: "platform"`, no `orgId`) verifies only for a `platform.page`
+     *   contribution while the account is still an active super admin.
      */
     ui: {
         view(id: string, render: (args: UiRenderArgs) => Promise<UiView>): void;
         action(id: string, handler: (args: UiActionArgs) => Promise<UiActionResult>): void;
         invalidate(target: {
-            orgId: string;
+            /** Required, except for a `platform.page` contribution, where it must be omitted. */
+            orgId?: string;
             conversationId?: string;
             contribution: string;
         }): Promise<void>;

package/dist/define-extension.d.ts

@@ -14,7 +14,11 @@ export interface ExtensionManifest {
     optional?: ExtensionPointRef[];
     /** 权限清单（治理而非沙箱）。 */
     permissions?: ExtensionPermissions;
-    /** 界面贡献：对话页标签与组织页面；id 须同时列在 `permissions.ui` 里。 */
+    /**
+     * UI contributions, each in a slot of `UI_SLOTS`; every id is also listed in `permissions.ui`.
+     * Kept exactly as written: structural problems fail the extension, while a contribution to an
+     * unknown slot or version is only dropped when the host resolves the slots (`resolveUiSlots`).
+     */
     ui?: UiContribution[];
     config?: {
         deployment?: z.ZodTypeAny;

package/dist/define-extension.js

@@ -78,6 +78,7 @@ export function defineExtension(m) {
         if (errs.length > 0)
             fail(`invalid permissions: ${errs.join("; ")}`);
     }
+    // structural ui problems only; slot resolution never fails the extension (UI slots spec §3.2)
     const uiErrs = validateUiContributions(m.ui, m.permissions);
     if (uiErrs.length > 0)
         fail(`invalid ui: ${uiErrs.join("; ")}`);

package/dist/device-protocol.d.ts

@@ -1,6 +1,6 @@
 /**
  * Device protocol v1: the WebSocket frames between the kernel and a `capybara-device` program
- * (a connected machine that serves as an environment). Pure types and hand-written guards.
+ * (a connected machine that serves as a device). Pure types and hand-written guards.
  */
 import { type ExecResult, type SandboxActor, type SandboxLimits, type SandboxRoots } from "./sandbox.js";
 /** The protocol version carried in `X-Capybara-Device-Protocol` and the hello frame. */

package/dist/device-protocol.js

@@ -1,6 +1,6 @@
 /**
  * Device protocol v1: the WebSocket frames between the kernel and a `capybara-device` program
- * (a connected machine that serves as an environment). Pure types and hand-written guards.
+ * (a connected machine that serves as a device). Pure types and hand-written guards.
  */
 import { validateSandboxPathShape, } from "./sandbox.js";
 /** The protocol version carried in `X-Capybara-Device-Protocol` and the hello frame. */

package/dist/extension-point.js

@@ -8,7 +8,7 @@ const info = (majors, description, cardinality, brokered = false, orgScoped = fa
 });
 /** The registered extension points. */
 export const EXTENSION_POINTS = {
-    sandbox: info([2], "Runs an environment's instance and keeps its files for agents' commands (Docker, E2B).", "single", true),
+    sandbox: info([2], "Runs a device's instance and keeps its files for agents' commands (Docker, E2B).", "single", true),
     "config-source": info([1], "Supplies deployment configuration from an external store such as Nacos.", "single"),
     "secret-store": info([1], "Stores and resolves secrets (connector credentials, secret config) outside the database.", "single", true),
     "object-store": info([1], "Stores files and artifacts in S3-compatible object storage, with presigned uploads.", "single", true),

package/dist/file-preview.d.ts

@@ -7,7 +7,7 @@ export declare const FILE_PREVIEW_MAX_BYTES: number;
 /**
  * One previewer of a `file-preview@1` provider: which files it previews and how. It renders either a
  * view (`render`, drawn by the web app like any `UiView`) or an embed page (`embed`, the id of a ui
- * contribution `{ kind: "embed", place: "file-preview" }` of the same extension, which receives the
+ * contribution `{ kind: "embed", slot: "file.preview" }` of the same extension, which receives the
  * file over the message bridge). Exactly one of the two.
  */
 export interface FilePreviewer {

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.9";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -27,7 +27,13 @@ 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";
+export * from "./ui-resolve.js";
+export * from "./ui-slots.js";
 export * from "./web.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.9";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -27,7 +27,13 @@ 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";
+export * from "./ui-resolve.js";
+export * from "./ui-slots.js";
 export * from "./web.js";

package/dist/permissions.d.ts

@@ -62,9 +62,14 @@ export declare class ExtensionPointUnavailableError extends Error {
 /** 校验权限清单，返回错误列表（空表示合法）。 */
 export declare function validatePermissions(plugin: string, p: unknown): string[];
 /**
- * 校验清单 `ui` 并与权限清单交叉核对，返回错误列表（空表示合法）：
- * 每个贡献的 id 恰好出现在 `permissions.ui.views`（kind view）或 `permissions.ui.embeds`（kind embed）里，
- * `permissions.ui` 里也不能有清单 `ui` 没有的 id；embed 的 path 以 `/ui/` 开头并在 `permissions.http` 中声明为 GET。
- * 假定 `permissions` 已经过 {@link validatePermissions}。
+ * Checks the structure of the manifest's `ui` and cross-checks it with the permission manifest;
+ * returns the problems (empty = valid). Only structural problems (UI slots spec §3.2): each
+ * contribution's id is listed in exactly `permissions.ui.views` (kind view) or
+ * `permissions.ui.embeds` (kind embed), and `permissions.ui` lists no id the `ui` lacks; an embed's
+ * path starts with `/ui/` and is declared in `permissions.http` as GET; exactly one of `slot` (a
+ * well-formed slot reference) and `place` (a known place); for a slot the catalog knows at the
+ * version named, a kind it accepts and, unless an alias, the icon it requires. An unknown slot id or version is not a
+ * problem here: `resolveUiSlots` drops that contribution and the rest of the extension loads.
+ * Assumes `permissions` passed {@link validatePermissions}.
  */
 export declare function validateUiContributions(ui: unknown, permissions: unknown): string[];

package/dist/permissions.js

@@ -1,5 +1,6 @@
 import { POLICY_HOOKS } from "./hooks.js";
 import { UI_ICONS } from "./ui.js";
+import { PLACE_SLOTS, parseSlotRef, uiSlot } from "./ui-slots.js";
 /** hook 挂载点（封闭列表，见总设计 2.4）。 */
 export const HOOK_MOUNT_POINTS = [
     "session.start",
@@ -168,20 +169,18 @@ export function validatePermissions(plugin, p) {
 }
 const UI_ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
 const UI_TITLE_MAX = 100;
-const UI_PLACES = [
-    "conversation",
-    "panel",
-    "section",
-    "inline",
-    "page",
-    "file-preview",
-];
+const UI_PLACES = Object.keys(PLACE_SLOTS);
 const UI_EMBED_PREFIX = "/ui/";
 /**
- * 校验清单 `ui` 并与权限清单交叉核对，返回错误列表（空表示合法）：
- * 每个贡献的 id 恰好出现在 `permissions.ui.views`（kind view）或 `permissions.ui.embeds`（kind embed）里，
- * `permissions.ui` 里也不能有清单 `ui` 没有的 id；embed 的 path 以 `/ui/` 开头并在 `permissions.http` 中声明为 GET。
- * 假定 `permissions` 已经过 {@link validatePermissions}。
+ * Checks the structure of the manifest's `ui` and cross-checks it with the permission manifest;
+ * returns the problems (empty = valid). Only structural problems (UI slots spec §3.2): each
+ * contribution's id is listed in exactly `permissions.ui.views` (kind view) or
+ * `permissions.ui.embeds` (kind embed), and `permissions.ui` lists no id the `ui` lacks; an embed's
+ * path starts with `/ui/` and is declared in `permissions.http` as GET; exactly one of `slot` (a
+ * well-formed slot reference) and `place` (a known place); for a slot the catalog knows at the
+ * version named, a kind it accepts and, unless an alias, the icon it requires. An unknown slot id or version is not a
+ * problem here: `resolveUiSlots` drops that contribution and the rest of the extension loads.
+ * Assumes `permissions` passed {@link validatePermissions}.
  */
 export function validateUiContributions(ui, permissions) {
     const perms = isObj(permissions) ? permissions : {};
@@ -219,22 +218,46 @@ export function validateUiContributions(ui, permissions) {
         if (!title ||
             [title.zh, title.en].some((t) => typeof t !== "string" || t === "" || t.length > UI_TITLE_MAX))
             errs.push(`ui "${id}" title needs non-empty zh and en of at most ${UI_TITLE_MAX} characters`);
-        if (!UI_PLACES.includes(c.place))
+        // the slot it names, when the slot / place is well formed (known to the catalog or not)
+        let slotRef = null;
+        if ((c.slot === undefined) === (c.place === undefined)) {
+            errs.push(`ui "${id}" needs exactly one of slot and place`);
+        }
+        else if (c.slot !== undefined) {
+            slotRef = typeof c.slot === "string" ? parseSlotRef(c.slot) : null;
+            if (slotRef === null)
+                errs.push(`ui "${id}" slot must be a slot reference like "org.page" or "org.page@1"`);
+        }
+        else if (!UI_PLACES.includes(c.place)) {
             errs.push(`ui "${id}" place must be one of ${UI_PLACES.join(", ")}`);
+        }
+        else {
+            slotRef = { id: PLACE_SLOTS[c.place], version: 1 };
+        }
+        if (c.after !== undefined && typeof c.after !== "string")
+            errs.push(`ui "${id}" after must be a string`);
         if (c.kind !== "view" && c.kind !== "embed") {
             errs.push(`ui "${id}" kind must be view or embed`);
             return;
         }
         if (c.icon !== undefined && !UI_ICONS.includes(c.icon))
             errs.push(`ui "${id}" icon must be one of ${UI_ICONS.join(", ")}`);
+        // the slot checks describe only the catalog's version: another version is left to
+        // resolveUiSlots, which drops it (unsupported-version) without failing the extension
+        const known = slotRef === null ? undefined : uiSlot(slotRef.id);
+        const spec = known !== undefined && known.version === slotRef?.version ? known : undefined;
+        if (spec !== undefined) {
+            if (!spec.accepts.includes(c.kind))
+                errs.push(`ui "${id}" slot ${spec.id} does not accept kind ${c.kind}`);
+            if (spec.icon === "required" && c.icon === undefined && c.aliasOf === undefined)
+                errs.push(`ui "${id}" slot ${spec.id} needs an icon`);
+        }
         if (c.aliasOf !== undefined)
             aliases.push({ id, kind: c.kind, target: c.aliasOf });
         if (seen.has(id))
             errs.push(`ui has duplicate id "${id}"`);
         seen.set(id, c.kind);
         if (c.kind === "view") {
-            if (c.place === "file-preview")
-                errs.push(`ui "${id}" place file-preview is only allowed for kind embed`);
             if (c.path !== undefined)
                 errs.push(`ui "${id}" path is only allowed for kind embed`);
             if (!views.includes(id))

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/sandbox.d.ts

@@ -4,8 +4,8 @@
  * primitives below; the kernel builds `glob` / `grep` / `edit` from `exec` plus `readFile` /
  * `writeFile`.
  *
- * `@2` separates an environment's **file system** from its **instance**: the file system
- * (`createFileSystem`) lives until the environment is deleted (`destroyFileSystem`); instances
+ * `@2` separates a device's **file system** from its **instance**: the file system
+ * (`createFileSystem`) lives until the device is deleted (`destroyFileSystem`); instances
  * (`create`) attach to it and come and go (`destroy` drops the instance and keeps the files).
  */
 /** Sandbox extension point ref. */
@@ -38,7 +38,7 @@ export interface SandboxHandle {
 }
 /** The roots of an instance, falling back to {@link DEFAULT_SANDBOX_ROOTS}. */
 export declare function rootsOf(h: SandboxHandle): SandboxRoots;
-/** The provider's file system handle (an environment's files, independent of any instance). */
+/** The provider's file system handle (a device's files, independent of any instance). */
 export interface FileSystemHandle {
     /** The provider's file system id. */
     id: string;
@@ -74,7 +74,7 @@ export declare function isSandboxGoneError(e: unknown): e is SandboxGoneError;
 /**
  * The file system is definitely gone on the provider's side (volume removed, E2B sandbox killed).
  * `create` throws it instead of attaching the instance to a new, empty file system; the kernel then
- * reports the environment's files as lost rather than handing out a silently empty workspace.
+ * reports the device's files as lost rather than handing out a silently empty workspace.
  */
 export declare class FileSystemGoneError extends Error {
     readonly fileSystemGone: true;
@@ -93,8 +93,8 @@ export declare const SANDBOX_TAG_RE: RegExp;
 /**
  * The `sandbox@2` implementation (provided by a sandbox plugin such as Docker or E2B).
  *
- * **File systems and instances.** `createFileSystem` makes an environment's files; they live until
- * `destroyFileSystem` (the environment is deleted). `create` makes an instance attached to an
+ * **File systems and instances.** `createFileSystem` makes a device's files; they live until
+ * `destroyFileSystem` (the device is deleted). `create` makes an instance attached to an
  * existing file system; `destroy` / `destroyByName` drop the instance only and keep the files, and
  * `suspend` keeps them too. When the file system is gone, `create` must throw
  * {@link FileSystemGoneError} and never create an empty one in its place (a Docker provider checks
@@ -126,7 +126,7 @@ export declare const SANDBOX_TAG_RE: RegExp;
  * `exitCode: null`, `timedOut: false` (and the output collected so far), it does not reject. An
  * `exec` called with an already aborted signal rejects at once.
  *
- * **Concurrent use** (required in `@2`): the sessions of one environment share its instance, so the
+ * **Concurrent use** (required in `@2`): the sessions of one device share its instance, so the
  * kernel calls `exec`, `readFile`, `writeFile` and `stat` concurrently on one instance. Those four
  * methods must be safe to call concurrently. Each `exec` labels its command with its `tag`, and an
  * aborted `exec` kills only its own command.
@@ -135,12 +135,12 @@ export interface SandboxProvider {
     /** `exec` / `readFile` / `writeFile` / `stat` may run concurrently on one instance (required). */
     readonly concurrentExec: true;
     /**
-     * Whether the provider isolates the sessions of one environment from each other inside the
+     * Whether the provider isolates the sessions of one device from each other inside the
      * instance (a declared capability; absent means false).
      */
     readonly sessionIsolation?: boolean;
     /**
-     * Creates an environment's file system. `name` looks like `cap-env-<environmentId>`. If a file
+     * Creates a device's file system. `name` looks like `cap-device-<deviceId>`. If a file
      * system with this name already exists, return it.
      */
     createFileSystem(args: {

package/dist/sandbox.js

@@ -4,8 +4,8 @@
  * primitives below; the kernel builds `glob` / `grep` / `edit` from `exec` plus `readFile` /
  * `writeFile`.
  *
- * `@2` separates an environment's **file system** from its **instance**: the file system
- * (`createFileSystem`) lives until the environment is deleted (`destroyFileSystem`); instances
+ * `@2` separates a device's **file system** from its **instance**: the file system
+ * (`createFileSystem`) lives until the device is deleted (`destroyFileSystem`); instances
  * (`create`) attach to it and come and go (`destroy` drops the instance and keeps the files).
  */
 /** Sandbox extension point ref. */
@@ -45,7 +45,7 @@ export function isSandboxGoneError(e) {
 /**
  * The file system is definitely gone on the provider's side (volume removed, E2B sandbox killed).
  * `create` throws it instead of attaching the instance to a new, empty file system; the kernel then
- * reports the environment's files as lost rather than handing out a silently empty workspace.
+ * reports the device's files as lost rather than handing out a silently empty workspace.
  */
 export class FileSystemGoneError extends Error {
     fileSystemGone = true;

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[];
+};