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

package/dist/platform/ops/org-settings.ops.js

@@ -39,7 +39,7 @@ let OrgSettingsOperations = class OrgSettingsOperations {
         this.registry.register([
             defineOperation({
                 id: "org-settings.get",
-                description: "Read this org's settings: toolSearch, locale, sandboxToolPolicy, platformTool (on, read-only or off), sandboxEgress and wakeOnBackgroundTask (absent means it follows the deployment), theme (the org's default theme id, null or absent following the platform, and personal: allowed or locked), uiArrangement (per UI slot, the extension contributions the org hides and their order; a slot not listed follows the platform), the deployment's sandbox egress default and the sandbox cpu / memory limits in effect.",
+                description: "Read this org's settings: toolSearch, locale, sandboxToolPolicy, platformTool (on, read-only or off), sandboxEgress and wakeOnBackgroundTask (absent means it follows the deployment), theme (the org's default theme id, null or absent following the platform, and personal: allowed or locked), uiArrangement (per list slot, the extension contributions the org hides and their order; per single slot, the contribution that replaces the built-in as use, null for the built-in; a slot not listed follows the platform), the deployment's sandbox egress default and the sandbox cpu / memory limits in effect.",
                 input: z.object({}).strict(),
                 example: {},
                 authz: { orgAction: "org.read" },
@@ -53,7 +53,7 @@ let OrgSettingsOperations = class OrgSettingsOperations {
             }),
             defineOperation({
                 id: "org-settings.update",
-                description: "Change this org's settings (org admins). Give only the settings to change; null clears sandboxEgress or wakeOnBackgroundTask so they follow the deployment again. theme: { id, personal } sets the org's default theme (a theme id from themes.list, or null to follow the platform) and whether members may pick their own (allowed) or not (locked); null clears it. uiArrangement: { <slot>: { hidden, order } } replaces that slot's entry, where hidden and order list contribution keys <extension>/<contribution> (hidden ones are not listed in the web UI but their pages still open by URL); null for a slot makes it follow the platform again; platform.page is refused. Setting platformTool to off or read-only takes effect from the next call and cuts this Platform tool off in the org, so say so before asking; an org admin switches it back on in the web settings.",
+                description: "Change this org's settings (org admins). Give only the settings to change; null clears sandboxEgress or wakeOnBackgroundTask so they follow the deployment again. theme: { id, personal } sets the org's default theme (a theme id from themes.list, or null to follow the platform) and whether members may pick their own (allowed) or not (locked); null clears it. uiArrangement: { <slot>: { hidden, order } } (a list slot) or { <slot>: { use } } (a single slot: shell.brand, conversation.empty, conversation.composer.frame) replaces that slot's entry, where hidden, order and use name contribution keys <extension>/<contribution> (hidden ones are not listed in the web UI but their pages still open by URL; use null is the built-in); null for a slot makes it follow the platform again; platform.page is refused. Setting platformTool to off or read-only takes effect from the next call and cuts this Platform tool off in the org, so say so before asking; an org admin switches it back on in the web settings.",
                 input: OrgSettingsPatchSchema.refine((i) => Object.values(i).some((v) => v !== undefined), {
                     message: "give at least one setting",
                 }),

package/dist/platform/ops/orgs.ops.js

@@ -160,6 +160,7 @@ let OrgsOperations = class OrgsOperations {
                     "orgMarketplaceBrowse",
                     "uiTheme",
                     "uiArrangement",
+                    "clientExtensions",
                 ],
                 extras: ["orgId", "runConcurrency", "sandbox", "subagents"],
                 confirm: "platform",

package/dist/platform/ops/ui.ops.js

@@ -22,7 +22,7 @@ let UiOperations = class UiOperations {
         this.registry.register([
             defineOperation({
                 id: "ui.slots",
-                description: "List the UI slots an extension can contribute to (id, version, where it is, scope and args, accepted kinds view / embed, minimum role, anchors). Use a slot id as a ui contribution's `slot` in a plugin manifest.",
+                description: "List the UI slots an extension can contribute to (id, version, where it is, scope and args, accepted kinds view / embed / component, cardinality list or single, minimum role, anchors). Use a slot id as a ui contribution's `slot` in a plugin manifest.",
                 input: z.object({}).strict(),
                 example: {},
                 // any signed-in person may call the route; every run's actor is a member of this org

package/dist/platform/platform-ops.module.js

@@ -7,6 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { Module } from "@nestjs/common";
 import { AgentsModule } from "../agents/agents.module.js";
 import { BackgroundModule } from "../background/background.module.js";
+import { AppearanceModule } from "../catalog/appearance.service.js";
 import { CatalogModule } from "../catalog/catalog.module.js";
 import { ChannelsModule } from "../channels/channels.module.js";
 import { ConversationsModule } from "../conversations/conversations.module.js";
@@ -114,6 +115,7 @@ PlatformOpsModule = __decorate([
             AgentsModule,
             OrgsModule,
             CatalogModule,
+            AppearanceModule,
             ExtensionsModule,
             ToolsModule,
             ConversationsModule,

package/dist/platform/route-schemas.js

@@ -4,6 +4,7 @@ import { AGENT_ROUTES } from "../agents/agents.schemas.js";
 import { AGENT_TEMPLATE_ROUTES } from "../agents/templates.schemas.js";
 import { BACKGROUND_ROUTES } from "../background/background.schemas.js";
 import { ADMIN_CATALOG_ROUTES } from "../catalog/admin-catalog.schemas.js";
+import { APPEARANCE_ROUTES } from "../catalog/appearance.schemas.js";
 import { COMPONENT_SCOPE_ROUTES } from "../catalog/component-scope.schemas.js";
 import { MARKETPLACE_ROUTES } from "../catalog/marketplaces.schemas.js";
 import { ORG_CATALOG_ROUTES } from "../catalog/org-catalog.schemas.js";
@@ -66,6 +67,8 @@ export const ROUTE_SCHEMAS = [
     ...ME_ROUTES,
     // themes (themes spec §9)
     ...THEME_ROUTES,
+    // a plugin's suggested appearance (client extensions spec §6.5)
+    ...APPEARANCE_ROUTES,
     // setup guide checks (setup guides v2 §10.3, §12)
     ...SETUP_CHECK_ROUTES,
     ...SETUP_GUIDE_ROUTES,

package/dist/roles/worker.module.js

@@ -14,6 +14,8 @@ import { PlatformMigration } from "../catalog/platform-migration.js";
 import { PluginScopeWorkersModule } from "../catalog/scope-sync-workers.js";
 import { ChannelsModule, ChannelWorkersModule } from "../channels/channels.module.js";
 import { GatewayCheckJob } from "../channels/supervisor.js";
+import { ClientModule } from "../client/client.module.js";
+import { ClientReportsCron } from "../client/client-reports.cron.js";
 import { AttachmentsModule } from "../conversations/attachments.module.js";
 import { AttachmentCleanupJob } from "../conversations/attachments.service.js";
 import { EventLogModule } from "../conversations/event-log.js";
@@ -55,6 +57,7 @@ let WorkerModule = WorkerModule_1 = class WorkerModule {
             module: WorkerModule_1,
             imports: [
                 KernelScheduleModule,
+                ClientModule,
                 // the queue consumers (their worker options come from the startup config)
                 RuntimeWorkersModule.forRoot(config),
                 EvalWorkersModule.forRoot(config),
@@ -87,6 +90,7 @@ let WorkerModule = WorkerModule_1 = class WorkerModule {
                 BackgroundTaskPollJob,
                 ToolJobs,
                 InitialPasswordCleanupJob,
+                ClientReportsCron,
                 CatalogJobs,
                 PlatformMigration,
                 DirectoryScanJob,

package/dist/themes/render-css.d.ts

@@ -7,6 +7,7 @@ import { type ParsedTheme } from "@capybara-hq/plugin-sdk";
  * the theme's families first, then the built-in stack. Every stored value is re-validated (token
  * names against the overridable list, values against the SDK grammar, radius 0-16, families,
  * paths, weights, styles, roles); one that fails is left out, and `onSkipped` (when given and
- * something was skipped) is called once with the paths of every skipped value.
+ * something was skipped) is called once with the paths of every skipped value. The whole
+ * stylesheet is one `@layer theme { … }` block (client extensions spec §7.2).
  */
 export declare function renderThemeCss(theme: ParsedTheme, assetUrl: (pluginPath: string) => string, onSkipped?: (paths: string[]) => void): string;

package/dist/themes/render-css.js

@@ -73,7 +73,8 @@ const declarations = (d, extra = []) => [...extra, ...[...d].map(([k, v]) => `${
  * the theme's families first, then the built-in stack. Every stored value is re-validated (token
  * names against the overridable list, values against the SDK grammar, radius 0-16, families,
  * paths, weights, styles, roles); one that fails is left out, and `onSkipped` (when given and
- * something was skipped) is called once with the paths of every skipped value.
+ * something was skipped) is called once with the paths of every skipped value. The whole
+ * stylesheet is one `@layer theme { … }` block (client extensions spec §7.2).
  */
 export function renderThemeCss(theme, assetUrl, onSkipped) {
     const skipped = [];
@@ -128,5 +129,7 @@ export function renderThemeCss(theme, assetUrl, onSkipped) {
         rules.push(`:root { ${stacks.join(" ")} }`);
     if (skipped.length > 0)
         onSkipped?.(skipped);
-    return `${rules.join("\n")}\n`;
+    // One block in the `theme` cascade layer (client extensions spec §7.2): the design stylesheet
+    // declares the order design, theme, extensions; an unlayered theme would beat plugin CSS.
+    return `@layer theme {\n${rules.join("\n")}\n}\n`;
 }

package/dist/themes/theme-delivery.service.d.ts

@@ -22,9 +22,11 @@ export declare class ThemeDeliveryService {
     /**
      * The stylesheet of version `version` of theme `id` ({@link renderThemeCss}, asset URLs from
      * {@link themeUrl}); a stored value that fails re-validation is left out with one warning per
-     * render naming every skipped value. Unknown theme or version: 404 `theme.not_found`.
+     * render naming every skipped value. Unknown theme or version, or a `revision` other than the
+     * current `r<THEME_CSS_REVISION>` (an older one promised another format; a later one belongs to a
+     * newer replica): 404 `theme.not_found`, never cached.
      */
-    stylesheet(id: string, version: string): Promise<string>;
+    stylesheet(id: string, version: string, revision: string): Promise<string>;
     /**
      * Asset `file` (a path inside the plugin, as stored: `fonts/MiSans.woff2`) of version `version`
      * of theme `id`: only a font or logo the version's definition names. Unknown theme, version or

package/dist/themes/theme-delivery.service.js

@@ -15,7 +15,7 @@ import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { packagePath } from "../packages/tgz.js";
 import { StorageService } from "../storage/storage.service.js";
 import { renderThemeCss } from "./render-css.js";
-import { themeUrl } from "./theme-state.js";
+import { THEME_CSS_REVISION, themeUrl } from "./theme-state.js";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** A version number as it appears in a delivery URL: a positive int4. */
 const VERSION_RE = /^[1-9]\d{0,9}$/;
@@ -61,9 +61,14 @@ let ThemeDeliveryService = class ThemeDeliveryService {
     /**
      * The stylesheet of version `version` of theme `id` ({@link renderThemeCss}, asset URLs from
      * {@link themeUrl}); a stored value that fails re-validation is left out with one warning per
-     * render naming every skipped value. Unknown theme or version: 404 `theme.not_found`.
+     * render naming every skipped value. Unknown theme or version, or a `revision` other than the
+     * current `r<THEME_CSS_REVISION>` (an older one promised another format; a later one belongs to a
+     * newer replica): 404 `theme.not_found`, never cached.
      */
-    async stylesheet(id, version) {
+    async stylesheet(id, version, revision) {
+        if (revision !== `r${THEME_CSS_REVISION}`) {
+            throw notFound(`Theme ${id} version ${version} stylesheet revision ${revision}`);
+        }
         const { definition } = await this.version(id, version);
         return renderThemeCss(definition, (path) => themeUrl(id, version, path), (skipped) => this.log.warn("theme stylesheet: stored values failed re-validation and were left out", {
             themeId: id,

package/dist/themes/theme-state.d.ts

@@ -6,6 +6,11 @@ import { ApiError } from "../errors.js";
 export interface ThemeRef {
     /** The `platform_themes` id (what settings and picks store). */
     id: string;
+    /**
+     * `"<plugin>/<theme file id>"`: the name the web's `theme=` state token and `useTheme()` carry
+     * (client extensions spec §7.3). Stable across versions, unlike `id`.
+     */
+    key: string;
     /** Its current version. */
     version: string;
     name: LocalizedName;
@@ -19,7 +24,7 @@ export interface ThemeRef {
         wordmark: string | null;
         faviconUrl: string | null;
     } | null;
-    /** `/api/v1/themes/<id>/<version>/theme.css`. */
+    /** `/api/v1/themes/<id>/<version>/r<THEME_CSS_REVISION>/theme.css`. */
     cssUrl: string;
 }
 /** The four colors a theme picker draws per scheme. */
@@ -34,24 +39,40 @@ export type ListedTheme = ThemeRef & {
     swatches: Partial<Record<ThemeScheme, ThemeSwatch>>;
 };
 /**
- * The delivery URL of a theme version (spec §8): its stylesheet, or with `asset` (a path inside the
+ * The render revision of theme stylesheets, a segment of the stylesheet URL (`r<N>/theme.css`).
+ * The stylesheet is cached as immutable for a year, keyed by its URL: bump this whenever
+ * `renderThemeCss`'s output format changes, so no browser keeps an older format under a URL
+ * that now means the new one. The delivery route serves only the current revision (404
+ * `theme.not_found` otherwise). History: (none, `<version>/theme.css`) plain rules; 2: one
+ * `@layer theme { … }` block (client extensions spec §7.2).
+ */
+export declare const THEME_CSS_REVISION = 2;
+/**
+ * The delivery URL of a theme version (spec §8): its stylesheet (with the render revision,
+ * {@link THEME_CSS_REVISION}), or with `asset` (a path inside the
  * plugin as the theme file names it, e.g. `./fonts/MiSans.woff2`) that asset, as one path segment
  * (`assets/fonts%2FMiSans.woff2`; the route decodes it back to the stored path `fonts/MiSans.woff2`).
  * The one builder of these URLs: the listing, the stylesheet and the asset routes all use it.
  */
 export declare function themeUrl(id: string, version: string, asset?: string): string;
-/** The {@link ThemeRef} of version `version` of theme `id`. */
-export declare function themeRefOf(id: string, version: string, def: ParsedTheme): ThemeRef;
+/**
+ * The {@link ThemeRef} of version `version` of theme `id` of plugin `plugin` (null only for a row
+ * without provenance: the key is then the file id alone).
+ */
+export declare function themeRefOf(id: string, version: string, def: ParsedTheme, plugin: string | null): ThemeRef;
 /**
  * The swatches of each scheme the theme defines: its overrides merged onto the current built-in
  * values (a stored definition holds only the theme file's own values, themes spec §6).
  */
 export declare function themeSwatches(def: ParsedTheme): Partial<Record<ThemeScheme, ThemeSwatch>>;
-/** The current definitions of live themes `ids`, by id. */
-export declare function themeDefinitions(db: KernelSchemaDb, ids: readonly string[]): Promise<Map<string, {
+/** A live theme's current definition and its plugin (null: no provenance). */
+export interface ThemeDefinition {
     version: string;
     definition: ParsedTheme;
-}>>;
+    plugin: string | null;
+}
+/** The current definitions of live themes `ids`, by id. */
+export declare function themeDefinitions(db: KernelSchemaDb, ids: readonly string[]): Promise<Map<string, ThemeDefinition>>;
 /** The live themes on in the org, sorted by id. */
 export declare function themesOnIn(db: KernelSchemaDb, orgId: string): Promise<ComponentRow[]>;
 /** The live theme `id` if it can be the platform default, else null. */

package/dist/themes/theme-state.js

@@ -9,7 +9,17 @@ import { packagePath } from "../packages/tgz.js";
 /** The schemes in the order they are listed. */
 const SCHEMES = ["dark", "light"];
 /**
- * The delivery URL of a theme version (spec §8): its stylesheet, or with `asset` (a path inside the
+ * The render revision of theme stylesheets, a segment of the stylesheet URL (`r<N>/theme.css`).
+ * The stylesheet is cached as immutable for a year, keyed by its URL: bump this whenever
+ * `renderThemeCss`'s output format changes, so no browser keeps an older format under a URL
+ * that now means the new one. The delivery route serves only the current revision (404
+ * `theme.not_found` otherwise). History: (none, `<version>/theme.css`) plain rules; 2: one
+ * `@layer theme { … }` block (client extensions spec §7.2).
+ */
+export const THEME_CSS_REVISION = 2;
+/**
+ * The delivery URL of a theme version (spec §8): its stylesheet (with the render revision,
+ * {@link THEME_CSS_REVISION}), or with `asset` (a path inside the
  * plugin as the theme file names it, e.g. `./fonts/MiSans.woff2`) that asset, as one path segment
  * (`assets/fonts%2FMiSans.woff2`; the route decodes it back to the stored path `fonts/MiSans.woff2`).
  * The one builder of these URLs: the listing, the stylesheet and the asset routes all use it.
@@ -17,14 +27,18 @@ const SCHEMES = ["dark", "light"];
 export function themeUrl(id, version, asset) {
     const base = `/api/v1/themes/${encodeURIComponent(id)}/${encodeURIComponent(version)}`;
     return asset === undefined
-        ? `${base}/theme.css`
+        ? `${base}/r${THEME_CSS_REVISION}/theme.css`
         : `${base}/assets/${encodeURIComponent(packagePath(asset))}`;
 }
-/** The {@link ThemeRef} of version `version` of theme `id`. */
-export function themeRefOf(id, version, def) {
+/**
+ * The {@link ThemeRef} of version `version` of theme `id` of plugin `plugin` (null only for a row
+ * without provenance: the key is then the file id alone).
+ */
+export function themeRefOf(id, version, def, plugin) {
     const url = (ref) => (ref === undefined ? null : themeUrl(id, version, ref));
     return {
         id,
+        key: plugin === null ? def.id : `${plugin}/${def.id}`,
         version,
         name: def.name,
         schemes: SCHEMES.filter((s) => def.schemes[s] !== undefined),
@@ -62,12 +76,16 @@ export async function themeDefinitions(db, ids) {
     const rows = await db
         .selectFrom("platform_themes as p")
         .innerJoin("platform_theme_versions as v", (j) => j.onRef("v.theme_id", "=", "p.id").onRef("v.version", "=", "p.current_version"))
-        .select(["p.id", "p.current_version", "v.definition"])
+        .select(["p.id", "p.current_version", "p.plugin_name", "v.definition"])
         .where("p.id", "in", [...ids])
         .where("p.deleted_at", "is", null)
         .execute();
     for (const r of rows) {
-        out.set(r.id, { version: String(r.current_version), definition: r.definition });
+        out.set(r.id, {
+            version: String(r.current_version),
+            definition: r.definition,
+            plugin: r.plugin_name,
+        });
     }
     return out;
 }

package/dist/themes/themes-public.controller.d.ts

@@ -10,8 +10,13 @@ import { ThemesService } from "./themes.service.js";
 export declare class ThemeDeliveryController {
     private readonly delivery;
     constructor(delivery: ThemeDeliveryService);
-    /** The version's stylesheet: scheme overrides, `@font-face` rules and font stacks. */
-    css(id: string, version: string, reply: FastifyReply): Promise<void>;
+    /**
+     * 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.
+     */
+    css(id: string, version: string, revision: string, reply: FastifyReply): Promise<void>;
     /**
      * A font (`font/woff2`) or logo (`image/svg+xml`, sanitized at import, served under a CSP
      * sandbox; `image/png`) the version names; `file` is its plugin path as one segment

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