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

package/dist/themes/themes-public.controller.js

@@ -23,9 +23,14 @@ let ThemeDeliveryController = class ThemeDeliveryController {
     constructor(delivery) {
         this.delivery = delivery;
     }
-    /** The version's stylesheet: scheme overrides, `@font-face` rules and font stacks. */
-    async css(id, version, reply) {
-        const css = await this.delivery.stylesheet(id, version);
+    /**
+     * The version's stylesheet: scheme overrides, `@font-face` rules and font stacks, in the render
+     * revision `revision` (`r<THEME_CSS_REVISION>`; only the current one is served). The URL without
+     * a revision (before revision 2) has no route: 404, so a browser's cached unlayered copy is never
+     * answered with the new format under an immutable cache.
+     */
+    async css(id, version, revision, reply) {
+        const css = await this.delivery.stylesheet(id, version, revision);
         await reply
             .header("content-type", "text/css; charset=utf-8")
             .header("x-content-type-options", "nosniff")
@@ -51,10 +56,11 @@ let ThemeDeliveryController = class ThemeDeliveryController {
 };
 __decorate([
     Public(),
-    Get("theme.css"),
+    Get(":revision/theme.css"),
     __param(0, Param("id")),
     __param(1, Param("version")),
-    __param(2, Res())
+    __param(2, Param("revision")),
+    __param(3, Res())
 ], ThemeDeliveryController.prototype, "css", null);
 __decorate([
     Public(),

package/dist/themes/themes.service.js

@@ -32,7 +32,7 @@ let ThemesService = class ThemesService {
             if (!d)
                 continue;
             out.push({
-                ...themeRefOf(c.id, d.version, d.definition),
+                ...themeRefOf(c.id, d.version, d.definition, d.plugin),
                 swatches: themeSwatches(d.definition),
             });
         }
@@ -53,7 +53,7 @@ let ThemesService = class ThemesService {
         if (id === null || (await eligiblePlatformDefault(this.db.db, id)) === null)
             return null;
         const d = (await themeDefinitions(this.db.db, [id])).get(id);
-        return d ? themeRefOf(id, d.version, d.definition) : null;
+        return d ? themeRefOf(id, d.version, d.definition, d.plugin) : null;
     }
     /**
      * The listing, the viewer's resolved theme and the org's setting. Separate reads, not one

package/dist/tools/pipeline.d.ts

@@ -151,8 +151,9 @@ interface PipelineDeps {
     /** The org's switches of single extension tools: a turned-off one is not called (spec A §7). */
     readonly switches: Pick<OrgToolSwitches, "isToolOff">;
     /**
-     * Ids of an extension's `inline` ui contributions (read live, no alias): a plugin tool's
-     * `ToolResult.card` must name one of them, otherwise it is dropped with a warning.
+     * Ids of an extension's `conversation.tool-result.card` contributions of any kind (view, embed
+     * or component; read live, no alias): a plugin tool's `ToolResult.card` must name one of them,
+     * otherwise it is dropped with a warning.
      */
     inlineViews(plugin: string): ReadonlySet<string>;
     /**

package/dist/ui/arrangement.d.ts

@@ -1,74 +1,65 @@
 import { type UiSlotId } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 import type { UiContributionItem } from "./views.js";
-export declare const UiArrangementEntrySchema: z.ZodObject<{
-    hidden: z.ZodArray<z.ZodString>;
-    order: z.ZodArray<z.ZodString>;
-}, z.core.$strict>;
-export type UiArrangementEntry = z.infer<typeof UiArrangementEntrySchema>;
-export declare const UiArrangementSchema: z.ZodRecord<z.ZodEnum<{
-    "agent.detail.section": "agent.detail.section";
-    "conversation.panel": "conversation.panel";
-    "conversation.properties.section": "conversation.properties.section";
-    "conversation.tool-result.card": "conversation.tool-result.card";
-    "file.preview": "file.preview";
-    "org.page": "org.page";
-    "org.settings.section": "org.settings.section";
-    "platform.page": "platform.page";
-}> & z.core.$partial, z.ZodObject<{
-    hidden: z.ZodArray<z.ZodString>;
-    order: z.ZodArray<z.ZodString>;
-}, z.core.$strict>>;
-export type UiArrangement = z.infer<typeof UiArrangementSchema>;
+export type UiListEntry = {
+    hidden: string[];
+    order: string[];
+};
+export type UiUseEntry = {
+    use: string | null;
+};
+/** One slot's entry: `{ hidden, order }` on a list slot, `{ use }` on a single slot. */
+export type UiArrangementEntry = UiListEntry | UiUseEntry;
+export type UiArrangement = Partial<Record<UiSlotId, UiArrangementEntry>>;
+/** Whether a slot is a single (replaceable) slot. */
+export declare const isSingle: (slot: UiSlotId) => boolean;
+export declare const UiArrangementSchema: z.ZodType<UiArrangement>;
 /** The slots an org arranges: every arrangeable slot but the platform's own. */
 export declare const ORG_ARRANGEABLE: readonly UiSlotId[];
 /** An org's patch: a slot's entry replaces the stored one, null removes it. */
-export declare const OrgUiArrangementPatchSchema: z.ZodRecord<z.ZodEnum<{
-    "agent.detail.section": "agent.detail.section";
-    "conversation.panel": "conversation.panel";
-    "conversation.properties.section": "conversation.properties.section";
-    "conversation.tool-result.card": "conversation.tool-result.card";
-    "file.preview": "file.preview";
-    "org.page": "org.page";
-    "org.settings.section": "org.settings.section";
-    "platform.page": "platform.page";
-}> & z.core.$partial, z.ZodNullable<z.ZodObject<{
-    hidden: z.ZodArray<z.ZodString>;
-    order: z.ZodArray<z.ZodString>;
-}, z.core.$strict>>>;
+export declare const OrgUiArrangementPatchSchema: z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", UiArrangementEntry | null>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", UiArrangementEntry | null>>, unknown>>;
 /** A deployment patch: like {@link OrgUiArrangementPatchSchema} over every arrangeable slot. */
-export declare const UiArrangementPatchSchema: z.ZodRecord<z.ZodEnum<{
-    "agent.detail.section": "agent.detail.section";
-    "conversation.panel": "conversation.panel";
-    "conversation.properties.section": "conversation.properties.section";
-    "conversation.tool-result.card": "conversation.tool-result.card";
-    "file.preview": "file.preview";
-    "org.page": "org.page";
-    "org.settings.section": "org.settings.section";
-    "platform.page": "platform.page";
-}> & z.core.$partial, z.ZodNullable<z.ZodObject<{
-    hidden: z.ZodArray<z.ZodString>;
-    order: z.ZodArray<z.ZodString>;
-}, z.core.$strict>>>;
+export declare const UiArrangementPatchSchema: z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", UiArrangementEntry | null>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", UiArrangementEntry | null>>, unknown>>;
 /** Merges a per-slot patch into the stored arrangement (null removes the slot's entry). */
 export declare function mergeArrangement(current: UiArrangement | undefined, patch: Partial<Record<UiSlotId, UiArrangementEntry | null>>): UiArrangement;
-/** The entry that applies to a slot: the org's if it arranged the slot, else the platform's. */
+/**
+ * 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 declare function effectiveEntry(org: UiArrangement | undefined, platform: UiArrangement, slot: UiSlotId): {
-    entry: UiArrangementEntry;
+    entry: UiListEntry;
     source: "org" | "platform" | "none";
 };
+/**
+ * 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 declare function resolveSingleSlot(slot: UiSlotId, orgEntry: UiArrangementEntry | undefined, platformEntry: UiArrangementEntry | undefined, available: ReadonlySet<string>): string | null;
+/** The `use` stored for a single slot: the org's entry if it has one, else the platform's. */
+export declare function storedUse(org: UiArrangement | undefined, platform: UiArrangement, slot: UiSlotId): {
+    use: string | null;
+    followsPlatform: boolean;
+};
+/** The arrangement key of a contribution: `<plugin>/<id>`. */
+export declare const keyOf: (i: {
+    plugin: string;
+    id: string;
+}) => string;
 /**
  * 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
  * the keys of `entry.order` come first in that order, the rest in base order. Unknown keys are
  * ignored, so an order never moves an item across anchors.
  */
-export declare function orderItems(items: UiContributionItem[], entry: UiArrangementEntry): UiContributionItem[];
+export declare function orderItems(items: UiContributionItem[], entry: UiListEntry): UiContributionItem[];
 /** {@link orderItems} without the hidden keys. */
-export declare function arrange(items: UiContributionItem[], entry: UiArrangementEntry): UiContributionItem[];
+export declare function arrange(items: UiContributionItem[], entry: UiListEntry): UiContributionItem[];
 /**
  * Applies the per-slot entries to a mixed list: each slot's items are arranged and written back
  * into the positions that slot occupied (a slot without an entry: its base order, grouped by
  * anchor).
  */
-export declare function arrangeBySlot(items: UiContributionItem[], entryOf: (slot: UiSlotId) => UiArrangementEntry): UiContributionItem[];
+export declare function arrangeBySlot(items: UiContributionItem[], entryOf: (slot: UiSlotId) => UiListEntry): UiContributionItem[];

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[]>;
     /**