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

package/dist/storage/storage.service.js

@@ -1,5 +1,17 @@
-import { ExtensionPointUnavailableError, } from "@capybara-hq/plugin-sdk";
+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 { ExtensionPointUnavailableError, OBJECT_STORE_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { ApiError } from "../errors.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
 import { KeySpace, kernelPrefix, normalizeOrgId, pluginPrefix } from "./prefix.js";
 export { StorageKeyError } from "./prefix.js";
 /** 部署级对象的键前缀（见 {@link StorageService.deployment}）。 */
@@ -16,13 +28,15 @@ export function clampPresignTtl(ttlSeconds) {
     return Math.min(MAX_PRESIGN_TTL_SECONDS, Math.max(1, Math.floor(ttlSeconds)));
 }
 /**
- * 内核的对象存储服务（扩展模型 §5）：在 `object-store@1` 提供方之上加前缀隔离。
+ * 前缀隔离的对象存储（扩展模型 §5）：在 `object-store@1` 提供方之上加前缀隔离。A plain class over a
+ * {@link StorageSource}: the kernel's one instance is the {@link StorageService} provider; an
+ * extension's `ctx.storage` and the CLI build their own over their own source.
  * - 插件经 {@link forPlugin} 拿到 `ctx.storage`：键落在 `plugins/<插件>/<orgId>/` 下；
  * - 内核功能经 {@link kernel} 用 `kernel/<orgId>/`；
  * - 返回给调用方的键（`head` / `get` / `put` / `list`）都去掉前缀，列举结果只保留本前缀下的对象。
  * 没有提供方时各方法 reject `storage.unavailable`（{@link available} 为 false）。本身无状态，可多副本共用。
  */
-export class StorageService {
+export class PrefixedStorage {
     d;
     constructor(d) {
         this.d = d;
@@ -98,6 +112,33 @@ export class StorageService {
         return store;
     }
 }
+/**
+ * The kernel's object storage (one provider): the object store is the first loaded `object-store@1`
+ * provider in the {@link ExtensionRegistry} (read per call: it is ready only after the extensions
+ * load); the extensions that may hold data are those ever approved (permission snapshots, including
+ * uninstalled ones) plus the loaded ones.
+ */
+let StorageService = class StorageService extends PrefixedStorage {
+    constructor(registry, db) {
+        super({
+            provider: () => registry.list("object-store").find((e) => e.capability === OBJECT_STORE_EXTENSION_POINT)
+                ?.impl,
+            plugins: async () => {
+                const rows = await db
+                    .selectFrom("extension_permission_snapshots")
+                    .select("plugin")
+                    .execute();
+                return [...rows.map((r) => r.plugin), ...registry.manifests().map((m) => m.name)];
+            },
+        });
+    }
+};
+StorageService = __decorate([
+    Injectable(),
+    __param(0, Inject(ExtensionRegistry)),
+    __param(1, Inject(KernelDb))
+], StorageService);
+export { StorageService };
 /** 一个前缀下的 ObjectStore 视图：键先校验再拼接，返回的键去掉前缀。 */
 class ScopedStore {
     store;

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

package/dist/themes/theme-state.js

@@ -0,0 +1,203 @@
+// Which themes an org can use and which can be the platform default (themes spec §7), the theme
+// references the web reads, and the delivery URLs (§8). Plain functions in the caller's context (a
+// transaction's connection when there is one): the settings writers (deployment, org, person) and
+// `ThemesService` decide with the same predicates.
+import { mergeThemeSchemes, } from "@capybara-hq/plugin-sdk";
+import { componentOn, listedIn, loadComponents, loadScopeState, pluginFactsOf, switchOf, } from "../catalog/component-state.js";
+import { ApiError } from "../errors.js";
+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
+ * 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 function themeUrl(id, version, asset) {
+    const base = `/api/v1/themes/${encodeURIComponent(id)}/${encodeURIComponent(version)}`;
+    return asset === undefined
+        ? `${base}/theme.css`
+        : `${base}/assets/${encodeURIComponent(packagePath(asset))}`;
+}
+/** The {@link ThemeRef} of version `version` of theme `id`. */
+export function themeRefOf(id, version, def) {
+    const url = (ref) => (ref === undefined ? null : themeUrl(id, version, ref));
+    return {
+        id,
+        version,
+        name: def.name,
+        schemes: SCHEMES.filter((s) => def.schemes[s] !== undefined),
+        singleScheme: def.singleScheme,
+        logo: def.logo === undefined
+            ? null
+            : {
+                markUrl: url(def.logo.mark),
+                wordmark: def.logo.wordmark ?? null,
+                faviconUrl: url(def.logo.favicon),
+            },
+        cssUrl: themeUrl(id, version),
+    };
+}
+/**
+ * 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 function themeSwatches(def) {
+    const out = {};
+    const merged = mergeThemeSchemes(def);
+    for (const s of SCHEMES) {
+        const c = merged[s]?.color;
+        if (def.schemes[s] === undefined || c === undefined)
+            continue;
+        out[s] = { bg: c.bg ?? "", panel: c.panel ?? "", ink: c.ink ?? "", accent: c.accent ?? "" };
+    }
+    return out;
+}
+/** The current definitions of live themes `ids`, by id. */
+export async function themeDefinitions(db, ids) {
+    const out = new Map();
+    if (ids.length === 0)
+        return out;
+    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"])
+        .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 });
+    }
+    return out;
+}
+/** Whether theme `c` is on in the org (offered in its pickers, spec §6), from `st`. */
+const onIn = (st, c, orgId) => componentOn(c, pluginFactsOf(st, c.itemId, orgId), listedIn(st, c.id, orgId), switchOf(st, c.id, orgId));
+/** The live themes on in the org, sorted by id. */
+export async function themesOnIn(db, orgId) {
+    const comps = await loadComponents(db, "theme");
+    if (comps.length === 0)
+        return [];
+    const st = await loadScopeState(db, "theme", comps);
+    return comps.filter((c) => onIn(st, c, orgId));
+}
+/**
+ * Whether theme `c` can be the platform default (spec §7): platform-owned, not disabled, its
+ * plugin live and not disabled, and its effective scope `all` (its own, or its plugin's when it
+ * follows; a builtin plugin is `all`).
+ */
+function platformDefaultEligible(st, c) {
+    if (c.ownerOrgId !== null || c.disabled)
+        return false;
+    const p = c.itemId === null ? undefined : st.plugins.get(c.itemId);
+    if (c.itemId !== null && (p === undefined || p.disabled))
+        return false;
+    if (c.scopeMode === "own")
+        return c.scope === "all";
+    return p !== undefined && (p.builtin || p.scope === "all");
+}
+/** The live theme `id` if it can be the platform default, else null. */
+export async function eligiblePlatformDefault(db, id) {
+    const [c] = await loadComponents(db, "theme", { ids: [id] });
+    if (!c)
+        return null;
+    const st = await loadScopeState(db, "theme", [c]);
+    return platformDefaultEligible(st, c) ? c : 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 const themeNotAvailable = (id, where, orgs) => new ApiError("theme.not_available", orgs === undefined
+    ? `Theme ${id} is not available ${where}; choose one of the themes listed for it`
+    : `Theme ${id} is off in ${orgs.length} organization(s) (${orgs.map((o) => o.orgName).join(", ")}), so it cannot be the platform default; choose a theme that is on in every organization`, [{ theme: id, ...(orgs !== undefined && { orgs }) }]);
+/**
+ * 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 async function lockThemeShared(db, id) {
+    const row = await db
+        .selectFrom("platform_themes")
+        .select("catalog_item_id")
+        .where("id", "=", id)
+        .executeTakeFirst();
+    if (!row)
+        return;
+    if (row.catalog_item_id !== null) {
+        await db
+            .selectFrom("catalog_items")
+            .select("id")
+            .where("id", "=", row.catalog_item_id)
+            .forShare()
+            .execute();
+    }
+    await db.selectFrom("platform_themes").select("id").where("id", "=", id).forShare().execute();
+}
+/**
+ * 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 async function assertPlatformDefaultEligible(db, id) {
+    const [c] = await loadComponents(db, "theme", { ids: [id] });
+    const st = c && (await loadScopeState(db, "theme", [c]));
+    if (!c || !st || !platformDefaultEligible(st, c)) {
+        throw themeNotAvailable(id, "as the platform default (a platform theme whose scope is all)");
+    }
+    const orgs = await db
+        .selectFrom("orgs")
+        .select(["id", "name"])
+        .where("deleted_at", "is", null)
+        .orderBy("name")
+        .orderBy("id")
+        .execute();
+    const off = orgs.filter((o) => !onIn(st, c, o.id)).map((o) => ({ orgId: o.id, orgName: o.name }));
+    if (off.length > 0)
+        throw themeNotAvailable(id, "as the platform default", off);
+}
+/**
+ * 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 async function assertThemeOnIn(db, orgId, id) {
+    await lockThemeShared(db, id);
+    const [c] = await loadComponents(db, "theme", { ids: [id] });
+    const st = c && (await loadScopeState(db, "theme", [c]));
+    if (!c || !st || !onIn(st, c, orgId))
+        throw themeNotAvailable(id, "in this organization");
+}
+/** Whether theme `id` is on in the org (no locks: a read for display). */
+export async function themeOnIn(db, orgId, id) {
+    const [c] = await loadComponents(db, "theme", { ids: [id] });
+    if (!c)
+        return false;
+    return onIn(await loadScopeState(db, "theme", [c]), c, orgId);
+}
+/** Whether theme `id` is on in at least one of the person's live orgs. */
+export async function themeOnForAccount(db, accountId, id) {
+    const orgs = await db
+        .selectFrom("memberships as m")
+        .innerJoin("orgs as o", "o.id", "m.org_id")
+        .select("m.org_id")
+        .where("m.account_id", "=", accountId)
+        .where("o.deleted_at", "is", null)
+        .execute();
+    const [c] = await loadComponents(db, "theme", { ids: [id] });
+    if (!c || orgs.length === 0)
+        return false;
+    const st = await loadScopeState(db, "theme", [c]);
+    return orgs.some((o) => onIn(st, c, o.org_id));
+}
+/**
+ * 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 async function assertThemeOnForAccount(db, accountId, id) {
+    if (!(await themeOnForAccount(db, accountId, id))) {
+        throw themeNotAvailable(id, "in any of your organizations");
+    }
+}