@capybara-hq/kernel 0.1.0-rc.14 → 0.1.0-rc.15

package/dist/ui/arrangement.js

@@ -1,22 +1,66 @@
-import { UI_ARRANGEABLE_SLOTS, UI_CONTRIBUTION_KEY_RE, uiSlot, } from "@capybara-hq/plugin-sdk";
+import { UI_ARRANGEABLE_SLOTS, UI_CONTRIBUTION_KEY_RE, UI_SINGLE_SLOTS, uiSlot, } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 /**
- * Arrangement of UI slots (UI slots spec §5): per slot, which contributions are hidden and in
- * which order. "Hidden" means not listed: the access gate never reads an arrangement, so a hidden
- * contribution's view, action and embed routes keep working for an allowed role.
+ * Arrangement of UI slots (UI slots spec §5, client extensions spec §6.3): per list slot, which
+ * contributions are hidden and in which order; per single slot, which contribution replaces the
+ * built-in (`use`, null = the built-in). "Hidden" means not listed and `use` only picks what is
+ * listed: the access gate never reads an arrangement, so a contribution's view, action and embed
+ * routes keep working for an allowed role whatever the arrangement says.
  */
-const Key = z.string().regex(UI_CONTRIBUTION_KEY_RE);
+const Key = z.string().regex(UI_CONTRIBUTION_KEY_RE, "must be a contribution key <plugin>/<id>");
 const LIST_MAX = 200;
-export const UiArrangementEntrySchema = z
-    .object({ hidden: z.array(Key).max(LIST_MAX), order: z.array(Key).max(LIST_MAX) })
-    .strict();
-export const UiArrangementSchema = z.partialRecord(z.enum(UI_ARRANGEABLE_SLOTS), UiArrangementEntrySchema);
+/**
+ * A list slot's entry: the keys hidden and the keys ordered first. The refusals name the slot and
+ * what it takes (actionable for an admin and the Platform tool's model).
+ */
+const listEntrySchema = (slot) => {
+    const keys = z
+        .array(Key, {
+        error: (iss) => iss.input === undefined
+            ? `${slot} is a list slot: give an array of contribution keys <plugin>/<id>`
+            : undefined,
+    })
+        .max(LIST_MAX);
+    return z.strictObject({ hidden: keys, order: keys }, {
+        error: (iss) => iss.code === "unrecognized_keys"
+            ? `${slot} is a list slot: give { hidden, order }; use is only for the single slots (${UI_SINGLE_SLOTS.join(", ")})`
+            : undefined,
+    });
+};
+/** A single slot's entry: the contribution that replaces the built-in, or null for the built-in. */
+const useEntrySchema = (slot) => z.strictObject({
+    use: z.union([Key, z.null()], {
+        error: (iss) => iss.input === undefined
+            ? `${slot} needs use: a contribution key <plugin>/<id>, or null for the built-in`
+            : undefined,
+    }),
+}, {
+    error: (iss) => iss.code === "unrecognized_keys"
+        ? `${slot} is a single slot: give { use } (a contribution key <plugin>/<id>, or null for the built-in); hidden and order are only for list slots`
+        : undefined,
+});
+/** Whether a slot is a single (replaceable) slot. */
+export const isSingle = (slot) => UI_SINGLE_SLOTS.includes(slot);
+/**
+ * An object over `slots`, each optional and of its kind's entry (nullable in a patch); unknown
+ * slots are refused, and so are `use` on a list slot and `hidden` / `order` on a single slot (400
+ * `validation_failed` on the settings routes).
+ */
+function arrangementShape(slots, nullable) {
+    const shape = {};
+    for (const slot of slots) {
+        const entry = isSingle(slot) ? useEntrySchema(slot) : listEntrySchema(slot);
+        shape[slot] = (nullable ? entry.nullable() : entry).optional();
+    }
+    return z.object(shape).strict();
+}
+export const UiArrangementSchema = arrangementShape(UI_ARRANGEABLE_SLOTS, false);
 /** The slots an org arranges: every arrangeable slot but the platform's own. */
 export const ORG_ARRANGEABLE = UI_ARRANGEABLE_SLOTS.filter((s) => s !== "platform.page");
 /** An org's patch: a slot's entry replaces the stored one, null removes it. */
-export const OrgUiArrangementPatchSchema = z.partialRecord(z.enum(ORG_ARRANGEABLE), UiArrangementEntrySchema.nullable());
+export const OrgUiArrangementPatchSchema = arrangementShape(ORG_ARRANGEABLE, true);
 /** A deployment patch: like {@link OrgUiArrangementPatchSchema} over every arrangeable slot. */
-export const UiArrangementPatchSchema = z.partialRecord(z.enum(UI_ARRANGEABLE_SLOTS), UiArrangementEntrySchema.nullable());
+export const UiArrangementPatchSchema = arrangementShape(UI_ARRANGEABLE_SLOTS, true);
 /** Merges a per-slot patch into the stored arrangement (null removes the slot's entry). */
 export function mergeArrangement(current, patch) {
     const merged = { ...current };
@@ -29,17 +73,46 @@ export function mergeArrangement(current, patch) {
     return merged;
 }
 const NONE = { hidden: [], order: [] };
-/** The entry that applies to a slot: the org's if it arranged the slot, else the platform's. */
+const asList = (e) => ("hidden" in e ? e : NONE);
+/**
+ * The list entry that applies to a slot: the org's if it arranged the slot, else the platform's
+ * (a `use` entry, which only a single slot stores, reads as none).
+ */
 export function effectiveEntry(org, platform, slot) {
     const o = org?.[slot];
     if (o !== undefined)
-        return { entry: o, source: "org" };
+        return { entry: asList(o), source: "org" };
     const p = platform[slot];
     if (p !== undefined)
-        return { entry: p, source: "platform" };
+        return { entry: asList(p), source: "platform" };
     return { entry: NONE, source: "none" };
 }
-const keyOf = (i) => `${i.plugin}/${i.id}`;
+/**
+ * The winner of a single slot (client extensions spec §6.3): the org's entry if it has one, else
+ * the platform's, else none. No entry or `use: null` is the built-in (null); a `use` naming a key
+ * not in `available` (extension off in the org, contribution dropped, the viewer's role below the
+ * slot's) is the built-in too, never the other level's pick. A list slot, or an entry that is not
+ * a `use` entry, has no winner.
+ */
+export function resolveSingleSlot(slot, orgEntry, platformEntry, available) {
+    if (!isSingle(slot))
+        return null;
+    const entry = orgEntry ?? platformEntry;
+    if (entry === undefined || !("use" in entry) || entry.use === null)
+        return null;
+    return available.has(entry.use) ? entry.use : null;
+}
+/** The `use` stored for a single slot: the org's entry if it has one, else the platform's. */
+export function storedUse(org, platform, slot) {
+    const o = org?.[slot];
+    const e = o ?? platform[slot];
+    return {
+        use: e !== undefined && "use" in e ? e.use : null,
+        followsPlatform: o === undefined,
+    };
+}
+/** The arrangement key of a contribution: `<plugin>/<id>`. */
+export const keyOf = (i) => `${i.plugin}/${i.id}`;
 /**
  * Orders the items of one slot (hidden ones stay in place): grouped by anchor in the slot's anchor
  * order, also without an entry (the lists match what the page renders per anchor); within a group

package/dist/ui/registry.d.ts

@@ -45,19 +45,29 @@ export declare const uiFrame: (m: UiBusMessage) => string;
 /**
  * 单个插件在 setup 期间注册的视图与动作：进程内的静态登记（同 `ctx.tools.register`），
  * 不是跨请求的共享状态——各副本加载同一插件得到同样的登记。
- * id 必须是 `permissions.ui.views` 里的（与清单 `ui` 里 kind view 的贡献一一对应，`defineExtension` 已交叉核对）。
+ * The id must be in `permissions.ui.views` or `permissions.ui.components` (a component's server
+ * view, client extensions spec §5.2); `defineExtension` already cross-checked them with the
+ * manifest `ui`.
  */
 export declare class PluginUiRegistration {
     private readonly manifest;
-    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    /**
+     * Out of scope (the id is in neither `permissions.ui.views` nor `permissions.ui.components`):
+     * throws ExtensionPermissionError and writes an audit entry.
+     */
     private readonly deny;
     readonly views: Map<string, UiRender>;
     readonly actions: Map<string, UiActionHandler>;
     private readonly declaredViews;
     private readonly contributions;
+    /** The ids of the manifest's `component` contributions: their permission is `ui.components`. */
+    private readonly components;
     private sealed;
     constructor(manifest: ExtensionManifest, 
-    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    /**
+     * Out of scope (the id is in neither `permissions.ui.views` nor `permissions.ui.components`):
+     * throws ExtensionPermissionError and writes an audit entry.
+     */
     deny: (item: string) => never);
     /** setup 结束后调用：此后 view / action 抛错。 */
     seal(): void;

package/dist/ui/registry.js

@@ -31,7 +31,9 @@ export const uiFrame = (m) => `event: ui\ndata: ${JSON.stringify({ plugin: m.plu
 /**
  * 单个插件在 setup 期间注册的视图与动作：进程内的静态登记（同 `ctx.tools.register`），
  * 不是跨请求的共享状态——各副本加载同一插件得到同样的登记。
- * id 必须是 `permissions.ui.views` 里的（与清单 `ui` 里 kind view 的贡献一一对应，`defineExtension` 已交叉核对）。
+ * The id must be in `permissions.ui.views` or `permissions.ui.components` (a component's server
+ * view, client extensions spec §5.2); `defineExtension` already cross-checked them with the
+ * manifest `ui`.
  */
 export class PluginUiRegistration {
     manifest;
@@ -40,14 +42,21 @@ export class PluginUiRegistration {
     actions = new Map();
     declaredViews;
     contributions;
+    /** The ids of the manifest's `component` contributions: their permission is `ui.components`. */
+    components;
     sealed = false;
     constructor(manifest, 
-    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    /**
+     * Out of scope (the id is in neither `permissions.ui.views` nor `permissions.ui.components`):
+     * throws ExtensionPermissionError and writes an audit entry.
+     */
     deny) {
         this.manifest = manifest;
         this.deny = deny;
-        this.declaredViews = new Set(manifest.permissions?.ui?.views ?? []);
+        const ui = manifest.permissions?.ui;
+        this.declaredViews = new Set([...(ui?.views ?? []), ...(ui?.components ?? [])]);
         this.contributions = new Set((manifest.ui ?? []).map((c) => c.id));
+        this.components = new Set((manifest.ui ?? []).filter((c) => c.kind === "component").map((c) => c.id));
     }
     /** setup 结束后调用：此后 view / action 抛错。 */
     seal() {
@@ -99,7 +108,9 @@ export class PluginUiRegistration {
             throw new Error(`plugin ${name}: ui.${what} is only allowed during setup; setup has completed`);
         }
         if (typeof id !== "string" || !this.declaredViews.has(id)) {
-            this.deny(`permissions.ui.views ${String(id)}`);
+            // name the list the id belongs in: a component's server view is declared under components
+            const list = typeof id === "string" && this.components.has(id) ? "components" : "views";
+            this.deny(`permissions.ui.${list} ${String(id)}`);
         }
         if (typeof fn !== "function") {
             throw new Error(`plugin ${name}: ui.${what} "${id}" handler must be a function`);

package/dist/ui/ui.schemas.d.ts

@@ -9,6 +9,8 @@ export declare const ContributionParams: z.ZodObject<{
 export declare const ContributionsQuery: z.ZodObject<{
     slot: z.ZodOptional<z.ZodEnum<{
         "agent.detail.section": "agent.detail.section";
+        "conversation.composer.frame": "conversation.composer.frame";
+        "conversation.empty": "conversation.empty";
         "conversation.panel": "conversation.panel";
         "conversation.properties.section": "conversation.properties.section";
         "conversation.tool-result.card": "conversation.tool-result.card";
@@ -16,6 +18,8 @@ export declare const ContributionsQuery: z.ZodObject<{
         "org.page": "org.page";
         "org.settings.section": "org.settings.section";
         "platform.page": "platform.page";
+        "shell.brand": "shell.brand";
+        "shell.overlay": "shell.overlay";
     }>>;
 }, z.core.$strip>;
 export declare const ViewQuery: z.ZodObject<{

package/dist/ui/views.d.ts

@@ -24,14 +24,31 @@ export interface UiContributionItem {
     /** From `UI_ICONS`; `puzzle` when the manifest names none. */
     icon: UiIcon;
 }
-/** One slot of an arrangement listing: where its entry comes from and its items in order. */
-export interface UiArrangementSlot {
+/** A list slot of an arrangement listing: where its entry comes from and its items in order. */
+export interface UiArrangementListSlot {
     slot: UiSlotId;
     source: "org" | "platform" | "none";
     items: (UiContributionItem & {
         hidden: boolean;
     })[];
 }
+/**
+ * A single slot of an arrangement listing (client extensions spec §6.3): the contributions that may
+ * replace the built-in, the stored `use` (null = the built-in; it may name a key that is not a
+ * candidate any more, which renders the built-in) and whether it is the platform's (the org has no
+ * entry; always false on the platform's own listing).
+ */
+export interface UiArrangementSingleSlot {
+    slot: UiSlotId;
+    candidates: {
+        key: string;
+        title: UiContribution["title"];
+    }[];
+    use: string | null;
+    followsPlatform: boolean;
+}
+/** One slot of an arrangement listing. */
+export type UiArrangementSlot = UiArrangementListSlot | UiArrangementSingleSlot;
 /** 嵌入应用的签发目标：已核对组织启用与对话访问。 */
 export interface UiEmbedTarget {
     plugin: string;
@@ -101,6 +118,8 @@ export declare function dropForeignOpens(view: UiView, panels: ReadonlySet<strin
  *   org; org: the role alone); refused is 404 `ui.not_found`, the same as not existing;
  * - a view takes only the context id of its scope (`conversationId` / `agentId`): a missing one or
  *   one of another scope is 400 `validation_failed`;
+ * - a component's server view (`ctx.ui.view(<component id>)`) is served like a view of its slot;
+ *   only its views carry `data` (a plain view's `data` is 502 `ui.invalid_view`);
  * - 调用带 5 秒时限与中止信号：render 抛错 502 `ui.render_failed`、action 抛错 502 `ui.action_failed`、
  *   超时 504 `ui.timeout`、返回非法视图 502
  *   `ui.invalid_view`，都记告警日志、不写对话日志（这些不是模型可见的内容）。
@@ -111,27 +130,35 @@ export declare class UiViews {
     constructor(host: ExtensionHost, conversations: ConversationsService, previewers: PreviewerRegistry, db: KernelDb, log: Pick<Logger, "warn">, effective: Pick<EffectiveConfigs, "get" | "platform">);
     /**
      * The contributions the role may use in the org, of one slot or of every org-reachable slot:
-     * the extension enabled and loaded, a view's render registered, the slot's `minRole`
-     * ({@link canUseSlot}, so never `platform.page`); no alias, no `file.preview` contribution (the
-     * file previewers list those). Base order (spec §5): extension name, then manifest order.
+     * the extension enabled and loaded, a view's render registered (a component is listed with or
+     * without a server view), the slot's `minRole` ({@link canUseSlot}, so never `platform.page`);
+     * no alias, no `file.preview` contribution (the file previewers list those). Base order (spec
+     * §5): extension name, then manifest order. A single slot lists at most its winner
+     * ({@link resolveSingleSlot} over what this role may use: none until one is chosen, and the web
+     * renders the built-in); display only, the routes that serve a contribution never read it. The
+     * winner is listed whether or not its client code may load (kill switch, per-plugin disable,
+     * client API support): the web renders the built-in when the org's client set has no such
+     * component, and any other consumer must do the same.
      */
     contributions(orgId: string, role: OrgRole, slot?: UiSlotId): Promise<UiContributionItem[]>;
     /** {@link contributions} before the arrangement: what the role may use, in base order. */
     private orgBase;
     /**
      * The arrangement page of an org: every org-arrangeable slot with the contributions the role may
-     * use, in effective order with the hidden ones in place, and where the entry comes from.
+     * use: a list slot in effective order with the hidden ones in place, and where the entry comes
+     * from; a single slot with its candidates, the stored `use` and whether it follows the platform.
      */
     arrangementView(orgId: string, role: OrgRole): Promise<UiArrangementSlot[]>;
     /**
      * The platform's arrangement page: every arrangeable slot with the contributions of every running
-     * extension (whatever its org enablement), ordered by the platform entry, hidden ones in place.
+     * extension (whatever its org enablement): a list slot ordered by the platform entry, hidden ones
+     * in place; a single slot with its candidates and the platform's `use`.
      */
     platformArrangementView(): Promise<UiArrangementSlot[]>;
     /**
      * The `platform.page` contributions of the running extensions, for the admin console (super
-     * admins; no org enablement applies): no alias, a view's render registered. Base order like
-     * {@link contributions}.
+     * admins; no org enablement applies): no alias, a view's render registered (a component is
+     * listed with or without a server view). Base order like {@link contributions}.
      */
     platformContributions(): Promise<UiContributionItem[]>;
     /**

package/dist/ui/views.js

@@ -20,7 +20,7 @@ import { readUiArrangement } from "../identity/settings.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { readOrgSettings } from "../orgs/settings.service.js";
-import { arrange, arrangeBySlot, effectiveEntry, ORG_ARRANGEABLE, orderItems, } from "./arrangement.js";
+import { arrange, arrangeBySlot, effectiveEntry, isSingle, keyOf, ORG_ARRANGEABLE, orderItems, resolveSingleSlot, storedUse, } from "./arrangement.js";
 import { callExtension } from "./call-extension.js";
 import { canUseSlot, UUID_RE } from "./registry.js";
 export { callExtension } from "./call-extension.js";
@@ -73,12 +73,14 @@ export function dropForeignOpens(view, panels) {
     return { ...rest, ...(open !== undefined && ok(open) && { open }), blocks };
 }
 /**
- * Lists contributions for a listing route: no alias, a view's render registered; base order
- * (spec §5): extension name, then manifest order (stable).
+ * Lists contributions for a listing route: no alias, a view's render registered (an embed or a
+ * component is listed without one: a component's server view is optional); base order (spec §5):
+ * extension name, then manifest order (stable).
  */
 function listed(entries) {
     return entries
-        .filter((c) => c.contribution.aliasOf === undefined && (c.contribution.kind === "embed" || c.render))
+        .filter((c) => c.contribution.aliasOf === undefined &&
+        (c.contribution.kind === "embed" || c.contribution.kind === "component" || c.render))
         .map((c, i) => ({ c, i }))
         .sort((x, y) => (x.c.plugin === y.c.plugin ? x.i - y.i : x.c.plugin < y.c.plugin ? -1 : 1))
         .map(({ c: { plugin, contribution: c, slot: s, after } }) => ({
@@ -92,6 +94,8 @@ function listed(entries) {
         icon: c.icon ?? "puzzle",
     }));
 }
+/** The candidates of a single slot in an arrangement listing. */
+const candidatesOf = (items) => items.map((i) => ({ key: keyOf(i), title: i.title }));
 /** The items in effective order, each marked hidden or not (hidden ones stay in place). */
 function withHidden(items, entry) {
     const hidden = new Set(entry.hidden);
@@ -107,12 +111,15 @@ const TOAST_MAX = 500;
 const MAX_LOGGED_PROBLEMS = 10;
 const notFound = () => new ApiError("ui.not_found", "UI contribution not found");
 const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
-/** 校验动作结果，返回问题列表（空 = 合法）。 */
-function actionResultProblems(r) {
+/**
+ * 校验动作结果，返回问题列表（空 = 合法）。A new `view` may carry `data` only for a component
+ * (`component`).
+ */
+function actionResultProblems(r, component) {
     if (!isObj(r))
         return ["action result must be an object"];
     if (r.view !== undefined)
-        return validateUiView(r.view).map((p) => `view: ${p}`);
+        return validateUiView(r.view, { component }).map((p) => `view: ${p}`);
     if (r.toast === undefined)
         return [];
     if (!isObj(r.toast))
@@ -133,6 +140,8 @@ function actionResultProblems(r) {
  *   org; org: the role alone); refused is 404 `ui.not_found`, the same as not existing;
  * - a view takes only the context id of its scope (`conversationId` / `agentId`): a missing one or
  *   one of another scope is 400 `validation_failed`;
+ * - a component's server view (`ctx.ui.view(<component id>)`) is served like a view of its slot;
+ *   only its views carry `data` (a plain view's `data` is 502 `ui.invalid_view`);
  * - 调用带 5 秒时限与中止信号：render 抛错 502 `ui.render_failed`、action 抛错 502 `ui.action_failed`、
  *   超时 504 `ui.timeout`、返回非法视图 502
  *   `ui.invalid_view`，都记告警日志、不写对话日志（这些不是模型可见的内容）。
@@ -160,9 +169,15 @@ let UiViews = class UiViews {
     }
     /**
      * The contributions the role may use in the org, of one slot or of every org-reachable slot:
-     * the extension enabled and loaded, a view's render registered, the slot's `minRole`
-     * ({@link canUseSlot}, so never `platform.page`); no alias, no `file.preview` contribution (the
-     * file previewers list those). Base order (spec §5): extension name, then manifest order.
+     * the extension enabled and loaded, a view's render registered (a component is listed with or
+     * without a server view), the slot's `minRole` ({@link canUseSlot}, so never `platform.page`);
+     * no alias, no `file.preview` contribution (the file previewers list those). Base order (spec
+     * §5): extension name, then manifest order. A single slot lists at most its winner
+     * ({@link resolveSingleSlot} over what this role may use: none until one is chosen, and the web
+     * renders the built-in); display only, the routes that serve a contribution never read it. The
+     * winner is listed whether or not its client code may load (kill switch, per-plugin disable,
+     * client API support): the web renders the built-in when the org's client set has no such
+     * component, and any other consumer must do the same.
      */
     async contributions(orgId, role, slot) {
         const items = await this.orgBase(orgId, role, slot);
@@ -172,7 +187,16 @@ let UiViews = class UiViews {
             this.d.orgArrangement(orgId),
             this.d.platformArrangement(),
         ]);
-        return arrangeBySlot(items, (s) => effectiveEntry(org, platform, s).entry);
+        const winners = new Map();
+        const winnerOf = (s) => {
+            if (!winners.has(s)) {
+                const available = new Set(items.filter((i) => i.slot === s).map(keyOf));
+                winners.set(s, resolveSingleSlot(s, org?.[s], platform[s], available));
+            }
+            return winners.get(s) ?? null;
+        };
+        const shown = items.filter((i) => !isSingle(i.slot) || keyOf(i) === winnerOf(i.slot));
+        return arrangeBySlot(shown, (s) => effectiveEntry(org, platform, s).entry);
     }
     /** {@link contributions} before the arrangement: what the role may use, in base order. */
     async orgBase(orgId, role, slot) {
@@ -187,7 +211,8 @@ let UiViews = class UiViews {
     }
     /**
      * The arrangement page of an org: every org-arrangeable slot with the contributions the role may
-     * use, in effective order with the hidden ones in place, and where the entry comes from.
+     * use: a list slot in effective order with the hidden ones in place, and where the entry comes
+     * from; a single slot with its candidates, the stored `use` and whether it follows the platform.
      */
     async arrangementView(orgId, role) {
         // the page is for people who arrange or at least see the org's UI, not for a guest
@@ -199,17 +224,18 @@ let UiViews = class UiViews {
             this.d.platformArrangement(),
         ]);
         return ORG_ARRANGEABLE.map((slot) => {
+            const items = base.filter((i) => i.slot === slot);
+            if (isSingle(slot)) {
+                return { slot, candidates: candidatesOf(items), ...storedUse(org, platform, slot) };
+            }
             const { entry, source } = effectiveEntry(org, platform, slot);
-            return {
-                slot,
-                source,
-                items: withHidden(base.filter((i) => i.slot === slot), entry),
-            };
+            return { slot, source, items: withHidden(items, entry) };
         });
     }
     /**
      * The platform's arrangement page: every arrangeable slot with the contributions of every running
-     * extension (whatever its org enablement), ordered by the platform entry, hidden ones in place.
+     * extension (whatever its org enablement): a list slot ordered by the platform entry, hidden ones
+     * in place; a single slot with its candidates and the platform's `use`.
      */
     async platformArrangementView() {
         const [base, platform] = await Promise.all([
@@ -217,18 +243,19 @@ let UiViews = class UiViews {
             this.d.platformArrangement(),
         ]);
         return UI_ARRANGEABLE_SLOTS.map((slot) => {
+            const items = base.filter((i) => i.slot === slot);
+            if (isSingle(slot)) {
+                const { use } = storedUse(undefined, platform, slot);
+                return { slot, candidates: candidatesOf(items), use, followsPlatform: false };
+            }
             const { entry, source } = effectiveEntry(undefined, platform, slot);
-            return {
-                slot,
-                source,
-                items: withHidden(base.filter((i) => i.slot === slot), entry),
-            };
+            return { slot, source, items: withHidden(items, entry) };
         });
     }
     /**
      * The `platform.page` contributions of the running extensions, for the admin console (super
-     * admins; no org enablement applies): no alias, a view's render registered. Base order like
-     * {@link contributions}.
+     * admins; no org enablement applies): no alias, a view's render registered (a component is
+     * listed with or without a server view). Base order like {@link contributions}.
      */
     async platformContributions() {
         const items = listed(this.d.host.uiContributions().filter((c) => c.slot.id === "platform.page"));
@@ -289,7 +316,8 @@ let UiViews = class UiViews {
         const { entry, args } = await this.resolve(t, "render");
         const render = entry.render;
         const view = await this.call(t, "render", (signal) => render({ ...args, signal }));
-        this.check(t, "render", validateUiView(view));
+        // `data` only from a component's view (client extensions spec §5.2)
+        this.check(t, "render", validateUiView(view, { component: entry.contribution.kind === "component" }));
         return dropForeignOpens(view, this.panels(t.plugin));
     }
     /** 执行动作：调用插件 `action`（视图里的按钮 / 表单提交），校验返回的提示或新视图。 */
@@ -303,7 +331,7 @@ let UiViews = class UiViews {
             ...(input.payload !== undefined && { payload: input.payload }),
             ...(input.answer !== undefined && { answer: input.answer }),
         }));
-        this.check(t, "action", actionResultProblems(r));
+        this.check(t, "action", actionResultProblems(r, entry.contribution.kind === "component"));
         const res = r;
         if (res.view !== undefined)
             return { view: dropForeignOpens(res.view, this.panels(t.plugin)) };
@@ -338,7 +366,9 @@ let UiViews = class UiViews {
             c.contribution.aliasOf === undefined &&
             (need === "embed"
                 ? c.contribution.kind === "embed"
-                : c.contribution.kind === "view" && c[need] !== undefined));
+                : // a view, or a component's server view (served like a view of its slot)
+                    (c.contribution.kind === "view" || c.contribution.kind === "component") &&
+                        c[need] !== undefined));
         if (t.scope === "platform") {
             const found = platformEntry(entry);
             return { entry: found, args: this.platformArgs(t, found) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/kernel",
-  "version": "0.1.0-rc.14",
+  "version": "0.1.0-rc.15",
   "description": "Capybara kernel: config, database, plugin host and HTTP API of the Capybara agent platform",
   "license": "Apache-2.0",
   "repository": {
@@ -65,7 +65,7 @@
     "yaml": "^2.9.1",
     "yauzl": "3.4.0",
     "zod": "^4.6.7",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.10"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.11"
   },
   "devDependencies": {
     "@langchain/langgraph-checkpoint-validation": "^1.2.0",
@@ -74,7 +74,7 @@
     "@types/ws": "^8.18.2",
     "@types/yauzl": "3.4.0",
     "ws": "^8.22.0",
-    "@capybara-hq/testing": "0.1.0-rc.13"
+    "@capybara-hq/testing": "0.1.0-rc.14"
   },
   "scripts": {
     "build": "tsc -b"

package/src/migrations/0107_extension_client_builds.sql

@@ -0,0 +1,50 @@
+-- Client extensions (spec 2026-11-09-client-extensions-design.md §9.1, §10.4).
+-- extension_client_builds: the client files of an extension package, keyed by the package sha256
+-- (the build id). The files live in object storage under `deployment/<object_prefix>`; the
+-- integrity values delivered to browsers come from this row, never from the object store.
+CREATE TABLE IF NOT EXISTS extension_client_builds (
+  package_sha256 text PRIMARY KEY REFERENCES extension_packages(sha256) ON DELETE CASCADE,
+  plugin text NOT NULL,
+  entry text,
+  styles text[] NOT NULL,
+  assets text[] NOT NULL,
+  integrity jsonb NOT NULL,
+  sizes jsonb NOT NULL,
+  api_version int NOT NULL,
+  object_prefix text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- extension_client_reports: crash and load reports of client code, one row per
+-- (plugin, build, org, contribution, kind); org_id is null for admin pages. Upserted, pruned after
+-- 30 days.
+CREATE TABLE IF NOT EXISTS extension_client_reports (
+  plugin text NOT NULL,
+  build text NOT NULL,
+  org_id text NULL,
+  contribution text NULL,
+  kind text NOT NULL CHECK (kind IN ('load', 'render', 'event', 'api', 'budget')),
+  count int NOT NULL DEFAULT 1,
+  first_at timestamptz NOT NULL DEFAULT now(),
+  last_at timestamptz NOT NULL DEFAULT now(),
+  last_message text NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS extension_client_reports_key_uq
+  ON extension_client_reports (
+    plugin, build, (coalesce(org_id, '')), (coalesce(contribution, '')), kind
+  );
+
+CREATE INDEX IF NOT EXISTS extension_client_reports_last_at
+  ON extension_client_reports (last_at);
+
+-- extension_replica_status.serving_sha256: the package a replica actually serves for the plugin
+-- (the row's own sha256 when loaded; the older package still running when the row's version is
+-- pending approval or failed; null when none runs). Client code follows the server code that runs
+-- (spec §9.3): a build is delivered while a live replica serves its package.
+ALTER TABLE extension_replica_status ADD COLUMN IF NOT EXISTS serving_sha256 text NULL;
+
+-- catalog_item_versions.appearance_order: the keys of plugin.json's
+-- suggestedAppearance.replacements in the author's order (a jsonb object does not keep key order),
+-- so the suggestion is listed and applied in that order (spec §6.5); null without replacements.
+ALTER TABLE catalog_item_versions ADD COLUMN IF NOT EXISTS appearance_order text[] NULL;