@capybara-hq/kernel 0.1.0-rc.10 → 0.1.0-rc.11

package/dist/themes/theme-usage.js

@@ -0,0 +1,98 @@
+// Who uses a theme (themes spec §6 "Losing access", §7): the platform default (`deployment_settings`
+// key `uiTheme`), the orgs whose default it is (`orgs.settings.theme.id`) and the people who picked
+// it (`accounts.theme`); the previews of changes that take a theme away list them, and the guard
+// refuses any change that takes the platform default away from an org. Plain reads in the caller's
+// context (a transaction's connection when there is one). The settings are read through the same
+// readers and schemas as their services (`readUiTheme`, `parseOrgSettings`), so the two never drift.
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { readUiTheme, UI_THEME_SETTING } from "../identity/settings.js";
+import { parseOrgSettings } from "../orgs/settings.service.js";
+/**
+ * The platform default theme's id (null: the built-in theme, or not set), through the setting's
+ * typed reader; `lock`: the row is read FOR SHARE, so a concurrent write of the setting (which
+ * locks it FOR UPDATE first, see `SettingsService`) waits for the caller's transaction, and the
+ * reverse.
+ */
+export async function platformDefaultThemeId(db, opts = {}) {
+    return (await readUiTheme(db, opts)).id;
+}
+/** Where theme `themeId` (a `platform_themes` id) is chosen: see {@link ThemeUsage}. */
+export async function themeUsage(db, themeId) {
+    const platformDefault = (await platformDefaultThemeId(db)) === themeId;
+    // the jsonb filter narrows the rows; the typed parse decides (an invalid stored value is no default)
+    const orgs = (await db
+        .selectFrom("orgs")
+        .select(["id", "name", "settings"])
+        .where("deleted_at", "is", null)
+        .where(sql `settings -> 'theme' ->> 'id'`, "=", themeId)
+        .orderBy("name")
+        .orderBy("id")
+        .execute()).filter((o) => parseOrgSettings(o.settings).theme?.id === themeId);
+    const picked = await db
+        .selectFrom("accounts")
+        .select((eb) => eb.fn.countAll().as("n"))
+        .where("theme", "=", themeId)
+        .executeTakeFirstOrThrow();
+    return {
+        platformDefault,
+        orgDefaults: orgs.map((o) => ({ orgId: o.id, orgName: o.name })),
+        pickedBy: Number(picked.n),
+    };
+}
+/**
+ * The `themes` block of a preview: for each theme of `lost` (theme id -> the orgs losing it) that
+ * some org loses, the orgs among those whose default it is and how many of their members picked
+ * it, by id.
+ * Undefined when no theme is lost, so a preview without themes keeps its shape and its hash.
+ */
+export async function themesPreview(db, lost) {
+    const out = [];
+    for (const id of [...lost.keys()].sort()) {
+        const orgs = lost.get(id);
+        if (!orgs || orgs.size === 0)
+            continue;
+        const u = await themeUsage(db, id);
+        out.push({
+            id,
+            orgDefaults: u.orgDefaults.filter((o) => orgs.has(o.orgId)),
+            pickedBy: await pickedByIn(db, id, orgs),
+        });
+    }
+    return out.length > 0 ? out : undefined;
+}
+/** How many members of `orgs` (each counted once) picked theme `id`. */
+export async function pickedByIn(db, id, orgs) {
+    if (orgs.size === 0)
+        return 0;
+    const picked = await db
+        .selectFrom("accounts as a")
+        .select((eb) => eb.fn.count("a.id").distinct().as("n"))
+        .where("a.theme", "=", id)
+        .where((eb) => eb.exists(eb
+        .selectFrom("memberships as m")
+        .select("m.account_id")
+        .whereRef("m.account_id", "=", "a.id")
+        .where("m.org_id", "in", [...orgs])))
+        .executeTakeFirstOrThrow();
+    return Number(picked.n);
+}
+/** 409 `theme.platform_default`: theme `theme` is the platform default (spec §7). */
+export const platformDefaultError = (theme) => new ApiError("theme.platform_default", `Theme ${theme} is the platform default theme (setting ${UI_THEME_SETTING}): it must stay on in every organization. Choose another platform default theme first, then narrow, disable or remove this one`, [{ theme, setting: UI_THEME_SETTING }]);
+/**
+ * Refuses a change that takes the platform default theme away from any org (spec §7): when one of
+ * `themeIds` is the platform default and `after` says it would no longer be `all` (narrower, or
+ * gone), 409 `theme.platform_default`. Call it in the change's transaction before anything is
+ * written, after locking the catalog item or theme rows the change touches (the one theme lock
+ * order: catalog item, theme row, then the `uiTheme` row, which this reads FOR SHARE; the setting's
+ * write takes them in the same order).
+ */
+export async function assertNotPlatformDefault(db, themeIds, after) {
+    if (themeIds.length === 0)
+        return;
+    const id = await platformDefaultThemeId(db, { lock: true });
+    if (id === null || !themeIds.includes(id))
+        return;
+    if (after(id) !== "all")
+        throw platformDefaultError(id);
+}

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

@@ -0,0 +1,28 @@
+import type { FastifyReply } from "fastify";
+import { ThemeDeliveryService } from "./theme-delivery.service.js";
+import type { ThemeRef } from "./theme-state.js";
+import { ThemesService } from "./themes.service.js";
+/**
+ * Theme delivery (themes spec §8): every theme version's stylesheet and assets, public (styles are
+ * not sensitive; the URLs reveal only that the theme exists) and immutable. The URLs are the ones
+ * `themeUrl` builds; an unknown theme, version or file is 404 `theme.not_found`.
+ */
+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>;
+    /**
+     * 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
+     * (`fonts%2FMiSans.woff2`).
+     */
+    asset(id: string, version: string, file: string, reply: FastifyReply): Promise<void>;
+}
+/** The platform default theme for pages before sign-in (themes spec §8-§9), public. */
+export declare class PlatformThemeController {
+    private readonly themes;
+    constructor(themes: ThemesService);
+    /** The platform default's reference while it is eligible; null: the built-in theme. */
+    platformTheme(): Promise<ThemeRef | null>;
+}

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

@@ -0,0 +1,92 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, Header, Inject, Param, Res } from "@nestjs/common";
+import { Public } from "../identity/principal.js";
+import { ThemeDeliveryService } from "./theme-delivery.service.js";
+import { ThemesService } from "./themes.service.js";
+/** A theme version's stylesheet and assets never change (the version is in the URL). */
+const IMMUTABLE = "public, max-age=31536000, immutable";
+/**
+ * Theme delivery (themes spec §8): every theme version's stylesheet and assets, public (styles are
+ * not sensitive; the URLs reveal only that the theme exists) and immutable. The URLs are the ones
+ * `themeUrl` builds; an unknown theme, version or file is 404 `theme.not_found`.
+ */
+let ThemeDeliveryController = class ThemeDeliveryController {
+    delivery;
+    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);
+        await reply
+            .header("content-type", "text/css; charset=utf-8")
+            .header("x-content-type-options", "nosniff")
+            .header("cache-control", IMMUTABLE)
+            .send(css);
+    }
+    /**
+     * 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
+     * (`fonts%2FMiSans.woff2`).
+     */
+    async asset(id, version, file, reply) {
+        const a = await this.delivery.asset(id, version, file);
+        reply
+            .header("content-type", a.contentType)
+            .header("x-content-type-options", "nosniff")
+            .header("cache-control", IMMUTABLE);
+        if (a.contentType === "image/svg+xml") {
+            reply.header("content-security-policy", "default-src 'none'; sandbox");
+        }
+        await reply.send(Buffer.from(a.data.buffer, a.data.byteOffset, a.data.byteLength));
+    }
+};
+__decorate([
+    Public(),
+    Get("theme.css"),
+    __param(0, Param("id")),
+    __param(1, Param("version")),
+    __param(2, Res())
+], ThemeDeliveryController.prototype, "css", null);
+__decorate([
+    Public(),
+    Get("assets/:file"),
+    __param(0, Param("id")),
+    __param(1, Param("version")),
+    __param(2, Param("file")),
+    __param(3, Res())
+], ThemeDeliveryController.prototype, "asset", null);
+ThemeDeliveryController = __decorate([
+    Controller("api/v1/themes/:id/:version"),
+    __param(0, Inject(ThemeDeliveryService))
+], ThemeDeliveryController);
+export { ThemeDeliveryController };
+/** The platform default theme for pages before sign-in (themes spec §8-§9), public. */
+let PlatformThemeController = class PlatformThemeController {
+    themes;
+    constructor(themes) {
+        this.themes = themes;
+    }
+    /** The platform default's reference while it is eligible; null: the built-in theme. */
+    platformTheme() {
+        return this.themes.platformDefault();
+    }
+};
+__decorate([
+    Public(),
+    Get(),
+    Header("cache-control", "no-store")
+], PlatformThemeController.prototype, "platformTheme", null);
+PlatformThemeController = __decorate([
+    Controller("api/v1/platform/theme"),
+    __param(0, Inject(ThemesService))
+], PlatformThemeController);
+export { PlatformThemeController };

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

@@ -0,0 +1,13 @@
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type OrgThemes, ThemesService } from "./themes.service.js";
+/** The org's themes (`/api/v1/orgs/:orgId/themes`, themes spec §9): members only. */
+export declare class OrgThemesController {
+    private readonly themes;
+    constructor(themes: ThemesService);
+    /**
+     * `{ themes, resolved, org }`: the themes on in the org (with swatches), the viewer's resolved
+     * theme (null: the built-in one) and the org's default and personal lock.
+     */
+    list(principal: Principal, org: OrgContext): Promise<OrgThemes>;
+}

package/dist/themes/themes.controller.js

@@ -0,0 +1,38 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, Inject } from "@nestjs/common";
+import { CurrentPrincipal } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ThemesService } from "./themes.service.js";
+/** The org's themes (`/api/v1/orgs/:orgId/themes`, themes spec §9): members only. */
+let OrgThemesController = class OrgThemesController {
+    themes;
+    constructor(themes) {
+        this.themes = themes;
+    }
+    /**
+     * `{ themes, resolved, org }`: the themes on in the org (with swatches), the viewer's resolved
+     * theme (null: the built-in one) and the org's default and personal lock.
+     */
+    async list(principal, org) {
+        return this.themes.forOrg(org.orgId, principal.kind === "user" ? principal.account.id : null);
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], OrgThemesController.prototype, "list", null);
+OrgThemesController = __decorate([
+    Controller("api/v1/orgs/:orgId/themes"),
+    __param(0, Inject(ThemesService))
+], OrgThemesController);
+export { OrgThemesController };

package/dist/themes/themes.module.d.ts

@@ -0,0 +1,3 @@
+/** Themes (themes spec §7-§9): resolution, the org's theme listing and delivery. */
+export declare class ThemesModule {
+}

package/dist/themes/themes.module.js

@@ -0,0 +1,21 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@nestjs/common";
+import { StorageModule } from "../storage/storage.module.js";
+import { ThemeDeliveryService } from "./theme-delivery.service.js";
+import { ThemesService } from "./themes.service.js";
+/** Themes (themes spec §7-§9): resolution, the org's theme listing and delivery. */
+let ThemesModule = class ThemesModule {
+};
+ThemesModule = __decorate([
+    Module({
+        imports: [StorageModule],
+        providers: [ThemesService, ThemeDeliveryService],
+        exports: [ThemesService, ThemeDeliveryService],
+    })
+], ThemesModule);
+export { ThemesModule };

package/dist/themes/themes.schemas.d.ts

@@ -0,0 +1,3 @@
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** The theme routes the Platform operations mirror (`check:platform-ops` keys). */
+export declare const THEME_ROUTES: readonly RouteSchemas[];

package/dist/themes/themes.schemas.js

@@ -0,0 +1,2 @@
+/** The theme routes the Platform operations mirror (`check:platform-ops` keys). */
+export const THEME_ROUTES = [{ route: "GET /api/v1/orgs/:orgId/themes" }];

package/dist/themes/themes.service.d.ts

@@ -0,0 +1,50 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { type ListedTheme, type ThemeRef } from "./theme-state.js";
+/** `GET /api/v1/orgs/:orgId/themes` (themes spec §9). */
+export interface OrgThemes {
+    /** The themes on in the org, by English name. */
+    themes: ListedTheme[];
+    /** The viewer's theme ({@link ThemesService.resolve}); null: the built-in theme. */
+    resolved: ThemeRef | null;
+    /**
+     * The org's setting as stored: its default (null: follow the platform) and the personal lock.
+     * The stored id may name a theme absent from `themes` (it went off in the org after it was
+     * chosen; resolution skips it): the UI shows it as unavailable, not as selected.
+     */
+    org: {
+        id: string | null;
+        personal: "allowed" | "locked";
+    };
+}
+/**
+ * Which theme applies (themes spec §7) and the org's theme listing. Read-only; the levels are
+ * written by their settings services (deployment, org, person), which check availability with the
+ * same predicates (`theme-state.ts`).
+ */
+export declare class ThemesService {
+    private readonly db;
+    constructor(db: KernelDb);
+    /** The themes on in the org with their references and swatches, by English name then id. */
+    listForOrg(orgId: string): Promise<ListedTheme[]>;
+    /**
+     * The theme of a signed-in page in the org (spec §7): the person's pick if it is on in the org
+     * and the org does not lock; else the org's default if on; else the platform default if on in
+     * the org; else null (the built-in theme). An unavailable choice is skipped, never an error.
+     * `accountId` null (a service token): no personal pick.
+     */
+    resolve(orgId: string, accountId: string | null): Promise<ThemeRef | null>;
+    /** The platform default for pages before sign-in, when it is still eligible (spec §7); else null. */
+    platformDefault(): Promise<ThemeRef | null>;
+    /**
+     * The listing, the viewer's resolved theme and the org's setting. Separate reads, not one
+     * snapshot: a change committed between them shows at the next read.
+     */
+    forOrg(orgId: string, accountId: string | null): Promise<OrgThemes>;
+    /** A live theme's name (the super admin's summaries); null when there is no such theme. */
+    nameOf(id: string): Promise<LocalizedName | null>;
+    /** Theme `id`'s name if it is on in the org, else null (a summary never names another org's theme). */
+    nameIn(orgId: string, id: string): Promise<LocalizedName | null>;
+    /** Theme `id`'s name if it is on in one of the person's orgs, else null (same reason). */
+    nameForAccount(accountId: string, id: string): Promise<LocalizedName | null>;
+}

package/dist/themes/themes.service.js

@@ -0,0 +1,99 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { readUiTheme } from "../identity/settings.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { DEFAULT_ORG_THEME, readOrgSettings } from "../orgs/settings.service.js";
+import { eligiblePlatformDefault, themeDefinitions, themeOnForAccount, themeOnIn, themeRefOf, themeSwatches, themesOnIn, } from "./theme-state.js";
+/**
+ * Which theme applies (themes spec §7) and the org's theme listing. Read-only; the levels are
+ * written by their settings services (deployment, org, person), which check availability with the
+ * same predicates (`theme-state.ts`).
+ */
+let ThemesService = class ThemesService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** The themes on in the org with their references and swatches, by English name then id. */
+    async listForOrg(orgId) {
+        const on = await themesOnIn(this.db.db, orgId);
+        const defs = await themeDefinitions(this.db.db, on.map((c) => c.id));
+        const out = [];
+        for (const c of on) {
+            const d = defs.get(c.id);
+            if (!d)
+                continue;
+            out.push({
+                ...themeRefOf(c.id, d.version, d.definition),
+                swatches: themeSwatches(d.definition),
+            });
+        }
+        return out.sort((a, b) => a.name.en < b.name.en ? -1 : a.name.en > b.name.en ? 1 : a.id < b.id ? -1 : 1);
+    }
+    /**
+     * The theme of a signed-in page in the org (spec §7): the person's pick if it is on in the org
+     * and the org does not lock; else the org's default if on; else the platform default if on in
+     * the org; else null (the built-in theme). An unavailable choice is skipped, never an error.
+     * `accountId` null (a service token): no personal pick.
+     */
+    async resolve(orgId, accountId) {
+        return (await this.forOrg(orgId, accountId)).resolved;
+    }
+    /** The platform default for pages before sign-in, when it is still eligible (spec §7); else null. */
+    async platformDefault() {
+        const { id } = await readUiTheme(this.db.db);
+        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;
+    }
+    /**
+     * The listing, the viewer's resolved theme and the org's setting. Separate reads, not one
+     * snapshot: a change committed between them shows at the next read.
+     */
+    async forOrg(orgId, accountId) {
+        const themes = await this.listForOrg(orgId);
+        const org = (await readOrgSettings(this.db.db, orgId)).theme ?? DEFAULT_ORG_THEME;
+        const pick = accountId === null || org.personal === "locked"
+            ? null
+            : ((await this.db
+                .selectFrom("accounts")
+                .select("theme")
+                .where("id", "=", accountId)
+                .executeTakeFirst())?.theme ?? null);
+        const platform = (await readUiTheme(this.db.db)).id;
+        const on = (id) => (id === null ? undefined : themes.find((t) => t.id === id));
+        const hit = on(pick) ?? on(org.id) ?? on(platform);
+        let resolved = null;
+        if (hit) {
+            const { swatches: _swatches, ...ref } = hit;
+            resolved = ref;
+        }
+        return { themes, resolved, org: { id: org.id, personal: org.personal } };
+    }
+    /** A live theme's name (the super admin's summaries); null when there is no such theme. */
+    async nameOf(id) {
+        return (await themeDefinitions(this.db.db, [id])).get(id)?.definition.name ?? null;
+    }
+    /** Theme `id`'s name if it is on in the org, else null (a summary never names another org's theme). */
+    async nameIn(orgId, id) {
+        return (await themeOnIn(this.db.db, orgId, id)) ? this.nameOf(id) : null;
+    }
+    /** Theme `id`'s name if it is on in one of the person's orgs, else null (same reason). */
+    async nameForAccount(accountId, id) {
+        return (await themeOnForAccount(this.db.db, accountId, id)) ? this.nameOf(id) : null;
+    }
+};
+ThemesService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], ThemesService);
+export { ThemesService };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/kernel",
-  "version": "0.1.0-rc.10",
+  "version": "0.1.0-rc.11",
   "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.7"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.8"
   },
   "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.10"
+    "@capybara-hq/testing": "0.1.0-rc.11"
   },
   "scripts": {
     "build": "tsc -b"

package/src/migrations/0102_themes.sql

@@ -0,0 +1,64 @@
+-- Themes as a platform component kind (themes spec 2026-11-08-themes-design.md §6, §7): rows and
+-- versions shaped like platform agent templates, with the owner columns of org-owned items; the
+-- `theme` kind in the component scope, switch and install component tables; the person's pick on
+-- the account. Expand-only: the only dropped objects are the three kind checks, re-added wider in
+-- the next statement each.
+
+CREATE TABLE IF NOT EXISTS platform_themes (
+  id text PRIMARY KEY,
+  catalog_item_id uuid REFERENCES catalog_items(id) ON DELETE SET NULL,
+  plugin_name text,
+  name text NOT NULL,
+  description text,
+  description_zh text,
+  current_version integer NOT NULL CHECK (current_version >= 1),
+  scope_mode text NOT NULL DEFAULT 'follow' CHECK (scope_mode IN ('follow', 'own')),
+  scope text NOT NULL DEFAULT 'optional' CHECK (scope IN ('all', 'optional', 'named')),
+  disabled boolean NOT NULL DEFAULT false,
+  shown_to_others boolean NOT NULL DEFAULT true,
+  scope_version integer NOT NULL DEFAULT 0,
+  -- The owning org (NULL = the platform), the org it was created in (no FK, immutable) and the
+  -- share switch, as on the other platform components (0084).
+  owner_org_id text REFERENCES orgs(id) ON DELETE SET NULL,
+  origin_org_id text,
+  shareable boolean NOT NULL DEFAULT false,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz
+);
+CREATE UNIQUE INDEX IF NOT EXISTS platform_themes_live_name_origin_uq
+  ON platform_themes ((coalesce(plugin_name, '')), name, (coalesce(origin_org_id, '')))
+  WHERE deleted_at IS NULL;
+
+-- One version of a theme: `definition` is the parsed theme file (`ParsedTheme`); fonts and logo
+-- live under `object_prefix` in `deployment/` (NULL for a theme without assets).
+CREATE TABLE IF NOT EXISTS platform_theme_versions (
+  theme_id text NOT NULL REFERENCES platform_themes(id) ON DELETE CASCADE,
+  version integer NOT NULL CHECK (version >= 1),
+  definition jsonb NOT NULL,
+  object_prefix text,
+  catalog_version text,
+  updated_on_own boolean NOT NULL DEFAULT false,
+  created_by text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (theme_id, version)
+);
+
+-- 0081 declared these checks inline, so they carry the default names.
+-- capybara:allow-destructive the check is added back with 'theme' in the next statement; existing rows satisfy it
+ALTER TABLE component_scope_orgs DROP CONSTRAINT IF EXISTS component_scope_orgs_kind_check;
+ALTER TABLE component_scope_orgs ADD CONSTRAINT component_scope_orgs_kind_check
+  CHECK (kind IN ('skill', 'agent_template', 'connector_template', 'theme'));
+-- capybara:allow-destructive the check is added back with 'theme' in the next statement; existing rows satisfy it
+ALTER TABLE component_org_switches DROP CONSTRAINT IF EXISTS component_org_switches_kind_check;
+ALTER TABLE component_org_switches ADD CONSTRAINT component_org_switches_kind_check
+  CHECK (kind IN ('skill', 'agent_template', 'connector_template', 'theme'));
+-- NOT VALID as in 0053: existing rows were checked by the narrower constraint already.
+-- capybara:allow-destructive the check is added back with 'theme' in the next statement; existing rows satisfy it
+ALTER TABLE plugin_install_components DROP CONSTRAINT IF EXISTS plugin_install_components_kind_check;
+ALTER TABLE plugin_install_components ADD CONSTRAINT plugin_install_components_kind_check
+  CHECK (kind IN ('extension', 'connector', 'skill', 'plugin', 'agent_template', 'theme')) NOT VALID;
+
+-- The person's theme (§7): one value across all their orgs; NULL follows the org. No FK: a pick
+-- that is not on in the current org (or no longer exists) is skipped, never an error.
+ALTER TABLE accounts ADD COLUMN IF NOT EXISTS theme text;

package/src/migrations/0103_ui_theme_setting.sql

@@ -0,0 +1,7 @@
+-- The platform default theme setting `uiTheme` (themes spec §7) always has a row: the guards that
+-- refuse taking the default theme away from an org read it FOR SHARE, and the setting's write
+-- locks it FOR UPDATE before checking the chosen theme, so the two serialize on this row.
+-- `{"id": null}` is the built-in theme (the default when the key is missing).
+INSERT INTO deployment_settings (key, value)
+VALUES ('uiTheme', '{"id": null}'::jsonb)
+ON CONFLICT (key) DO NOTHING;