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

package/dist/platform/ops/themes.ops.js

@@ -0,0 +1,47 @@
+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 { z } from "zod";
+import { ThemesService } from "../../themes/themes.service.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Theme operations of the `Platform` tool (themes spec §9): the org's theme listing. Setting a
+ * theme goes through the settings operations (`platform.set-preferences`, `org-settings.update`,
+ * `admin.update-settings`).
+ */
+let ThemesOperations = class ThemesOperations {
+    registry;
+    themes;
+    constructor(registry, themes) {
+        this.registry = registry;
+        this.themes = themes;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "themes.list",
+                description: "List the themes on in this org (id, version, name, schemes, logo and the bg / panel / ink / accent swatches per scheme), the theme in effect for you here (resolved; null is the built-in theme) and the org's setting (its default theme id, null following the platform, and whether personal picks are allowed or locked). Use a theme id with platform.set-preferences to change your own theme, or with org-settings.update to change the org's default.",
+                input: z.object({}).strict(),
+                example: {},
+                authz: { orgAction: "org.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/themes"],
+                confirm: "read",
+                run: async (_input, ctx) => this.themes.forOrg(ctx.orgId, ctx.actorAccountId),
+            }),
+        ]);
+    }
+};
+ThemesOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(ThemesService))
+], ThemesOperations);
+export { ThemesOperations };

package/dist/platform/platform-ops.module.d.ts

@@ -25,11 +25,12 @@ import { PluginsOperations } from "./ops/plugins.ops.js";
 import { PreviewersOperations } from "./ops/previewers.ops.js";
 import { RequestsOperations } from "./ops/requests.ops.js";
 import { SkillsOperations } from "./ops/skills.ops.js";
+import { ThemesOperations } from "./ops/themes.ops.js";
 /**
  * One provider per domain, each taking `PlatformOperations` as its first constructor argument:
  * the parity test in `tools/checks` builds the operations from it without a Nest app.
  */
-export declare const PLATFORM_OPERATION_PROVIDERS: readonly [typeof PlatformOperationsProvider, typeof SkillsOperations, typeof AgentsOperations, typeof AgentTemplatesOperations, typeof PluginsOperations, typeof MarketplacesOperations, typeof RequestsOperations, typeof ConnectorsOperations, typeof ExtensionsOperations, typeof ConversationsOperations, typeof ComponentsOperations, typeof AccountsOperations, typeof OrgsOperations, typeof AdminOperations, typeof CatalogAdminOperations, typeof OrgPluginsOperations, typeof ExtensionsAdminOperations, typeof ModelsOperations, typeof InboxOperations, typeof ApprovalsOperations, typeof ChannelsOperations, typeof OrgSettingsOperations, typeof EvalsOperations, typeof BackgroundOperations, typeof PreviewersOperations, typeof EnvironmentsOperations, typeof AgentSkillsOperations];
+export declare const PLATFORM_OPERATION_PROVIDERS: readonly [typeof PlatformOperationsProvider, typeof SkillsOperations, typeof AgentsOperations, typeof AgentTemplatesOperations, typeof PluginsOperations, typeof MarketplacesOperations, typeof RequestsOperations, typeof ConnectorsOperations, typeof ExtensionsOperations, typeof ConversationsOperations, typeof ComponentsOperations, typeof AccountsOperations, typeof OrgsOperations, typeof AdminOperations, typeof CatalogAdminOperations, typeof OrgPluginsOperations, typeof ExtensionsAdminOperations, typeof ModelsOperations, typeof InboxOperations, typeof ApprovalsOperations, typeof ChannelsOperations, typeof OrgSettingsOperations, typeof EvalsOperations, typeof BackgroundOperations, typeof PreviewersOperations, typeof EnvironmentsOperations, typeof AgentSkillsOperations, typeof ThemesOperations];
 /**
  * The `Platform` tool's operations (ruling P2): one provider per domain, each registering its
  * operations into `PlatformOperations` from `onModuleInit`. It imports the domain modules, which

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

@@ -20,6 +20,7 @@ import { ModelsModule } from "../models/models.module.js";
 import { OrgsModule } from "../orgs/orgs.module.js";
 import { ProvidersModule } from "../runtime/providers.js";
 import { SkillsModule } from "../skills/skills.module.js";
+import { ThemesModule } from "../themes/themes.module.js";
 import { ToolsModule } from "../tools/tools.module.js";
 import { AccountsOperations } from "./ops/accounts.ops.js";
 import { AdminOperations } from "./ops/admin.ops.js";
@@ -48,6 +49,7 @@ import { PluginsOperations } from "./ops/plugins.ops.js";
 import { PreviewersOperations } from "./ops/previewers.ops.js";
 import { RequestsOperations } from "./ops/requests.ops.js";
 import { SkillsOperations } from "./ops/skills.ops.js";
+import { ThemesOperations } from "./ops/themes.ops.js";
 import { PlatformModule } from "./platform.module.js";
 /**
  * One provider per domain, each taking `PlatformOperations` as its first constructor argument:
@@ -87,6 +89,8 @@ export const PLATFORM_OPERATION_PROVIDERS = [
     // Task 11b: environments, agent skills
     EnvironmentsOperations,
     AgentSkillsOperations,
+    // themes (themes spec §9)
+    ThemesOperations,
 ];
 /**
  * The `Platform` tool's operations (ruling P2): one provider per domain, each registering its
@@ -115,6 +119,7 @@ PlatformOpsModule = __decorate([
             EnvironmentsModule,
             BackgroundModule,
             FilesModule,
+            ThemesModule,
         ],
         providers: [...PLATFORM_OPERATION_PROVIDERS],
     })

package/dist/platform/route-schemas.js

@@ -20,6 +20,7 @@ import { INBOX_ROUTES } from "../inbox/inbox.schemas.js";
 import { ORG_MODEL_ROUTES } from "../models/org-models.schemas.js";
 import { ORG_ROUTES, ORG_SETTINGS_ROUTES } from "../orgs/orgs.schemas.js";
 import { SKILL_ROUTES } from "../skills/skills.schemas.js";
+import { THEME_ROUTES } from "../themes/themes.schemas.js";
 import { APPROVAL_ROUTES } from "../tools/approvals.schemas.js";
 import { CONNECTOR_ROUTES } from "../tools/connectors.schemas.js";
 /**
@@ -60,4 +61,6 @@ export const ROUTE_SCHEMAS = [
     ...ENVIRONMENT_ROUTES,
     // personal preferences (run context spec §3.4)
     ...ME_ROUTES,
+    // themes (themes spec §9)
+    ...THEME_ROUTES,
 ];

package/dist/runtime/subagents/definition.d.ts

@@ -34,9 +34,10 @@ export interface EffectiveDefinitionDeps {
 type Policy = "ask" | "deny";
 /**
  * `base` with `over` applied on top, the stricter value winning per key (`deny` > `ask`). Values
- * other than `ask` / `deny` (stored template data is not re-validated) are skipped on both sides.
+ * other than `ask` / `deny` (stored template data is not re-validated; an agent's connector-tool
+ * `allow`, which the policy check reads from the agent's current version) are skipped on both sides.
  */
-export declare function stricterPolicies(base: Record<string, Policy>, over: Record<string, Policy>): Record<string, Policy>;
+export declare function stricterPolicies(base: Record<string, string>, over: Record<string, string>): Record<string, Policy>;
 /** An org agent's version and definition as checked by its gates. */
 export interface CheckedOrgAgent {
     version: number;

package/dist/runtime/subagents/definition.js

@@ -23,7 +23,8 @@ const RANK = { ask: 1, deny: 2 };
 const isPolicy = (p) => p === "ask" || p === "deny";
 /**
  * `base` with `over` applied on top, the stricter value winning per key (`deny` > `ask`). Values
- * other than `ask` / `deny` (stored template data is not re-validated) are skipped on both sides.
+ * other than `ask` / `deny` (stored template data is not re-validated; an agent's connector-tool
+ * `allow`, which the policy check reads from the agent's current version) are skipped on both sides.
  */
 export function stricterPolicies(base, over) {
     const out = {};

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

@@ -0,0 +1,12 @@
+import { type ParsedTheme } from "@capybara-hq/plugin-sdk";
+/**
+ * The stylesheet of a stored theme (themes spec §8): each scheme's overrides under
+ * `:root[data-theme="<scheme>"]` (a single-scheme theme: its whole scheme, the same block under
+ * both selectors, with `color-scheme: <scheme>`), an `@font-face` per font (`src` from
+ * `assetUrl(<the font's path as stored>)`, the one URL builder), and each font role's stack with
+ * 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.
+ */
+export declare function renderThemeCss(theme: ParsedTheme, assetUrl: (pluginPath: string) => string, onSkipped?: (paths: string[]) => void): string;

package/dist/themes/render-css.js

@@ -0,0 +1,132 @@
+// A theme version's stylesheet (themes spec §8), rendered from the stored, parsed theme. The
+// definition was validated at import, but it is read back from a database row: every value is
+// checked again here with the SDK's grammars before it is written into CSS, so a changed row cannot
+// inject CSS. A value that fails is left out and reported.
+import { canonicalThemeValue, isThemeAssetPath, isThemeFontFamily, THEME_FONTS, THEME_OVERRIDABLE, THEME_TOKENS, } from "@capybara-hq/plugin-sdk";
+const SCHEMES = ["dark", "light"];
+const GROUPS = ["color", "shadow"];
+const OVERRIDABLE = {
+    color: new Set(THEME_OVERRIDABLE.color),
+    shadow: new Set(THEME_OVERRIDABLE.shadow),
+    radius: new Set(THEME_OVERRIDABLE.radius),
+};
+/** The CSS variable of a stored token name (the design's `tokens.css` names). */
+const VARIABLE = {
+    color: (n) => `--cb-${n}`,
+    shadow: (n) => `--cb-${n}`,
+    radius: (n) => `--cb-radius-${n}`,
+};
+/** The CSS variable of each font role's stack. */
+const STACK_VARIABLE = { mono: "--cb-font", prose: "--cb-font-prose" };
+const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/**
+ * One scheme's declarations: the stored overrides that pass their checks, keyed by variable.
+ * `full`: start from every built-in value of `scheme` (a single-scheme theme writes the whole
+ * scheme, so the other selector draws it too); a skipped override then keeps the built-in value.
+ */
+function schemeDeclarations(theme, scheme, full, skip) {
+    const out = new Map();
+    if (full) {
+        // Built-in values come from the generated tokens (code, not stored data)
+        for (const g of GROUPS) {
+            for (const [n, v] of Object.entries(THEME_TOKENS[g]))
+                out.set(VARIABLE[g](n), v[scheme]);
+        }
+    }
+    const over = theme.schemes?.[scheme];
+    if (!isRecord(over))
+        return out;
+    for (const g of GROUPS) {
+        const values = over[g];
+        if (!isRecord(values))
+            continue;
+        for (const [n, raw] of Object.entries(values)) {
+            const v = OVERRIDABLE[g].has(n) ? canonicalThemeValue(g, raw) : undefined;
+            if (v === undefined)
+                skip(`schemes.${scheme}.${g}.${n}`);
+            else
+                out.set(VARIABLE[g](n), v);
+        }
+    }
+    const radius = over.radius;
+    if (isRecord(radius)) {
+        for (const [n, raw] of Object.entries(radius)) {
+            const ok = OVERRIDABLE.radius.has(n) &&
+                typeof raw === "number" &&
+                Number.isInteger(raw) &&
+                raw >= 0 &&
+                raw <= 16;
+            if (ok)
+                out.set(VARIABLE.radius(n), `${raw}px`);
+            else
+                skip(`schemes.${scheme}.radius.${n}`);
+        }
+    }
+    return out;
+}
+const declarations = (d, extra = []) => [...extra, ...[...d].map(([k, v]) => `${k}: ${v};`)].join(" ");
+/**
+ * The stylesheet of a stored theme (themes spec §8): each scheme's overrides under
+ * `:root[data-theme="<scheme>"]` (a single-scheme theme: its whole scheme, the same block under
+ * both selectors, with `color-scheme: <scheme>`), an `@font-face` per font (`src` from
+ * `assetUrl(<the font's path as stored>)`, the one URL builder), and each font role's stack with
+ * 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.
+ */
+export function renderThemeCss(theme, assetUrl, onSkipped) {
+    const skipped = [];
+    const skip = (p) => skipped.push(p);
+    const rules = [];
+    const single = SCHEMES.includes(theme.singleScheme)
+        ? theme.singleScheme
+        : null;
+    if (single !== null) {
+        const body = declarations(schemeDeclarations(theme, single, true, skip), [
+            `color-scheme: ${single};`,
+        ]);
+        for (const s of SCHEMES)
+            rules.push(`:root[data-theme="${s}"] { ${body} }`);
+    }
+    else {
+        for (const s of SCHEMES) {
+            const d = schemeDeclarations(theme, s, false, skip);
+            if (d.size > 0)
+                rules.push(`:root[data-theme="${s}"] { ${declarations(d)} }`);
+        }
+    }
+    const families = { mono: [], prose: [] };
+    const fonts = theme.fonts;
+    (Array.isArray(fonts) ? fonts : []).forEach((f, i) => {
+        const font = isRecord(f) ? f : {};
+        const style = font.style ?? "normal";
+        const role = font.role;
+        const ok = isThemeFontFamily(font.family) &&
+            isThemeAssetPath(font.file) &&
+            /\.woff2$/i.test(font.file) &&
+            typeof font.weight === "number" &&
+            Number.isInteger(font.weight) &&
+            font.weight >= 100 &&
+            font.weight <= 900 &&
+            (style === "normal" || style === "italic") &&
+            (role === "mono" || role === "prose");
+        if (!ok) {
+            skip(`fonts.${i}`);
+            return;
+        }
+        const family = font.family;
+        rules.push(`@font-face { font-family: "${family}"; src: url("${assetUrl(font.file)}") format("woff2"); font-weight: ${font.weight}; font-style: ${style}; font-display: swap; }`);
+        const list = families[role];
+        if (!list.includes(family))
+            list.push(family);
+    });
+    const stacks = ["mono", "prose"]
+        .filter((r) => families[r].length > 0)
+        .map((r) => `${STACK_VARIABLE[r]}: ${families[r].map((f) => `"${f}"`).join(", ")}, ${THEME_FONTS[r]};`);
+    if (stacks.length > 0)
+        rules.push(`:root { ${stacks.join(" ")} }`);
+    if (skipped.length > 0)
+        onSkipped?.(skipped);
+    return `${rules.join("\n")}\n`;
+}

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

@@ -0,0 +1,34 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import { StorageService } from "../storage/storage.service.js";
+/** A theme asset's bytes and content type. */
+export interface ThemeAsset {
+    contentType: string;
+    data: Uint8Array;
+}
+/**
+ * Delivery of theme versions (themes spec §8): the stylesheet rendered from the stored definition
+ * and the stored assets. A version is identified by the theme id and version number only; a theme
+ * removed later (soft-deleted) still serves its versions, because their URLs are immutable and may
+ * be cached in open pages, and a theme's styles are not sensitive (§8, public access).
+ */
+export declare class ThemeDeliveryService {
+    private readonly db;
+    private readonly storage;
+    private readonly log;
+    constructor(db: KernelDb, storage: StorageService, log: KernelLogger);
+    /** The stored version row, or 404 `theme.not_found`. */
+    private version;
+    /**
+     * 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`.
+     */
+    stylesheet(id: string, version: 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
+     * file: 404 `theme.not_found`.
+     */
+    asset(id: string, version: string, file: string): Promise<ThemeAsset>;
+}

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

@@ -0,0 +1,111 @@
+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 { isThemeAssetPath } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+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";
+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}$/;
+const INT4_MAX = 2_147_483_647;
+/** The content type of each asset kind a theme names (fonts and logos). */
+const ASSET_TYPES = [
+    [/\.woff2$/i, "font/woff2"],
+    [/\.svg$/i, "image/svg+xml"],
+    [/\.png$/i, "image/png"],
+];
+/** 404 `theme.not_found`. */
+const notFound = (what) => new ApiError("theme.not_found", `${what} does not exist; reload the page to get the current theme`);
+/**
+ * Delivery of theme versions (themes spec §8): the stylesheet rendered from the stored definition
+ * and the stored assets. A version is identified by the theme id and version number only; a theme
+ * removed later (soft-deleted) still serves its versions, because their URLs are immutable and may
+ * be cached in open pages, and a theme's styles are not sensitive (§8, public access).
+ */
+let ThemeDeliveryService = class ThemeDeliveryService {
+    db;
+    storage;
+    log;
+    constructor(db, storage, log) {
+        this.db = db;
+        this.storage = storage;
+        this.log = log;
+    }
+    /** The stored version row, or 404 `theme.not_found`. */
+    async version(id, version) {
+        if (!UUID_RE.test(id) || !VERSION_RE.test(version) || Number(version) > INT4_MAX) {
+            throw notFound(`Theme ${id} version ${version}`);
+        }
+        const row = await this.db
+            .selectFrom("platform_theme_versions")
+            .select(["definition", "object_prefix"])
+            .where("theme_id", "=", id)
+            .where("version", "=", Number(version))
+            .executeTakeFirst();
+        if (!row)
+            throw notFound(`Theme ${id} version ${version}`);
+        return { definition: row.definition, objectPrefix: row.object_prefix };
+    }
+    /**
+     * 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`.
+     */
+    async stylesheet(id, version) {
+        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,
+            version,
+            skipped,
+        }));
+    }
+    /**
+     * 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
+     * file: 404 `theme.not_found`.
+     */
+    async asset(id, version, file) {
+        const v = await this.version(id, version);
+        const def = v.definition;
+        const named = [
+            ...(Array.isArray(def.fonts) ? def.fonts.map((f) => f?.file) : []),
+            def.logo?.mark,
+            def.logo?.favicon,
+        ]
+            .filter((p) => typeof p === "string")
+            .map(packagePath);
+        const type = ASSET_TYPES.find(([re]) => re.test(file))?.[1];
+        if (v.objectPrefix === null ||
+            type === undefined ||
+            !isThemeAssetPath(file) ||
+            !named.includes(file)) {
+            throw notFound(`Theme asset ${file}`);
+        }
+        this.storage.assertAvailable();
+        const got = await this.storage.deployment().get(`${v.objectPrefix}${file}`);
+        if (!got) {
+            this.log.warn("theme asset missing from object storage", { themeId: id, version, file });
+            throw notFound(`Theme asset ${file}`);
+        }
+        return { contentType: type, data: new Uint8Array(await new Response(got.body).arrayBuffer()) };
+    }
+};
+ThemeDeliveryService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(StorageService)),
+    __param(2, Inject(KERNEL_LOGGER))
+], ThemeDeliveryService);
+export { ThemeDeliveryService };

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

@@ -0,0 +1,95 @@
+import { type LocalizedName, type ParsedTheme, type ThemeScheme } from "@capybara-hq/plugin-sdk";
+import { type ComponentRow } from "../catalog/component-state.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { ApiError } from "../errors.js";
+/** A theme as the web uses it (spec §8): what to load and how to draw the logo. */
+export interface ThemeRef {
+    /** The `platform_themes` id (what settings and picks store). */
+    id: string;
+    /** Its current version. */
+    version: string;
+    name: LocalizedName;
+    /** The schemes the theme defines, `dark` first. */
+    schemes: ThemeScheme[];
+    /** The only scheme of a single-scheme theme, else null. */
+    singleScheme: ThemeScheme | null;
+    /** null: the theme has no logo (the built-in mark and wordmark). */
+    logo: {
+        markUrl: string | null;
+        wordmark: string | null;
+        faviconUrl: string | null;
+    } | null;
+    /** `/api/v1/themes/<id>/<version>/theme.css`. */
+    cssUrl: string;
+}
+/** The four colors a theme picker draws per scheme. */
+export interface ThemeSwatch {
+    bg: string;
+    panel: string;
+    ink: string;
+    accent: string;
+}
+/** A theme of an org's listing: its reference and swatches for each scheme it defines. */
+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
+ * 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 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, {
+    version: string;
+    definition: ParsedTheme;
+}>>;
+/** 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. */
+export declare function eligiblePlatformDefault(db: KernelSchemaDb, id: string): Promise<ComponentRow | null>;
+/**
+ * 400 `theme.not_available`: theme `id` cannot be chosen where it was set; `orgs`: the live orgs
+ * where it is off (a platform default must be on in every org).
+ */
+export declare const themeNotAvailable: (id: string, where: string, orgs?: {
+    orgId: string;
+    orgName: string;
+}[]) => ApiError;
+/**
+ * Locks theme `id`'s catalog item, then its `platform_themes` row, FOR SHARE (the one theme lock
+ * order: catalog item, then theme row, then the `uiTheme` setting row; the scope, disable, switch
+ * and removal writers hold the item or theme row FOR UPDATE before they read `uiTheme`), so the
+ * check that follows reads a state no such writer changes before the caller commits.
+ */
+export declare function lockThemeShared(db: KernelSchemaDb, id: string): Promise<void>;
+/**
+ * Refuses (400 `theme.not_available`) a platform default that is not a platform-owned theme with
+ * effective scope `all`, live and not disabled, or that is off in some live org (an org switched it
+ * off, or does not have the plugin a `follow` theme comes with; details list those orgs): the
+ * default is locked on in every org and every org falls back to it (spec §7). Call it in the
+ * setting's transaction after {@link lockThemeShared} and the `uiTheme` row lock.
+ */
+export declare function assertPlatformDefaultEligible(db: KernelSchemaDb, id: string): Promise<void>;
+/**
+ * Refuses (400 `theme.not_available`) an org default that is not on in the org. Call it in the
+ * setting's transaction after the org lock: it locks the theme's rows FOR SHARE before reading.
+ */
+export declare function assertThemeOnIn(db: KernelSchemaDb, orgId: string, id: string): Promise<void>;
+/** Whether theme `id` is on in the org (no locks: a read for display). */
+export declare function themeOnIn(db: KernelSchemaDb, orgId: string, id: string): Promise<boolean>;
+/** Whether theme `id` is on in at least one of the person's live orgs. */
+export declare function themeOnForAccount(db: KernelSchemaDb, accountId: string, id: string): Promise<boolean>;
+/**
+ * Refuses (400 `theme.not_available`) a person's pick that is on in none of their live orgs (the
+ * pick is one value across their orgs, spec §7; where it is off, the org's default applies).
+ */
+export declare function assertThemeOnForAccount(db: KernelSchemaDb, accountId: string, id: string): Promise<void>;