@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

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

@@ -0,0 +1,116 @@
+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 { 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}$/;
+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, 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, 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,
+            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,116 @@
+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;
+    /**
+     * `"<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;
+    /** 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>/r<THEME_CSS_REVISION>/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 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` 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>>;
+/** 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. */
+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,221 @@
+// 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 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.
+ */
+export function themeUrl(id, version, asset) {
+    const base = `/api/v1/themes/${encodeURIComponent(id)}/${encodeURIComponent(version)}`;
+    return asset === undefined
+        ? `${base}/r${THEME_CSS_REVISION}/theme.css`
+        : `${base}/assets/${encodeURIComponent(packagePath(asset))}`;
+}
+/**
+ * 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),
+        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", "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,
+            plugin: r.plugin_name,
+        });
+    }
+    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");
+    }
+}

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

@@ -0,0 +1,61 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { ApiError } from "../errors.js";
+/** Where a theme is chosen (spec §7). */
+export interface ThemeUsage {
+    /** It is the platform default (`uiTheme.id`). */
+    platformDefault: boolean;
+    /** The live orgs whose default it is, by name. */
+    orgDefaults: {
+        orgId: string;
+        orgName: string;
+    }[];
+    /** The accounts that picked it (`accounts.theme`). */
+    pickedBy: number;
+}
+/**
+ * One theme a change takes away from some orgs, as a preview lists it (`themes?` of the scope,
+ * disable, uninstall and update previews): the orgs among those losing it whose default it is, and
+ * the number of people who picked it among those orgs' members (a preview never counts people of
+ * orgs it does not name).
+ */
+export interface ThemePreview {
+    id: string;
+    orgDefaults: {
+        orgId: string;
+        orgName: string;
+    }[];
+    pickedBy: number;
+}
+/** What a theme's availability is after a change: still `all`, narrower, or gone. */
+export type ThemeAfter = "all" | "narrower" | "gone";
+/**
+ * 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 declare function platformDefaultThemeId(db: KernelSchemaDb, opts?: {
+    lock?: boolean;
+}): Promise<string | null>;
+/** Where theme `themeId` (a `platform_themes` id) is chosen: see {@link ThemeUsage}. */
+export declare function themeUsage(db: KernelSchemaDb, themeId: string): Promise<ThemeUsage>;
+/**
+ * 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 declare function themesPreview(db: KernelSchemaDb, lost: ReadonlyMap<string, ReadonlySet<string>>): Promise<ThemePreview[] | undefined>;
+/** How many members of `orgs` (each counted once) picked theme `id`. */
+export declare function pickedByIn(db: KernelSchemaDb, id: string, orgs: ReadonlySet<string>): Promise<number>;
+/** 409 `theme.platform_default`: theme `theme` is the platform default (spec §7). */
+export declare const platformDefaultError: (theme: string) => ApiError;
+/**
+ * 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 declare function assertNotPlatformDefault(db: KernelSchemaDb, themeIds: readonly string[], after: (id: string) => ThemeAfter): Promise<void>;

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,33 @@
+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, 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
+     * (`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>;
+}