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

package/dist/skills/usable.d.ts

@@ -0,0 +1,82 @@
+import type { Logger, ObjectStore } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb, SkillManifest, SourceFormat } from "../db/kernel-schema.js";
+/** The `source` prefix of a platform skill version in a snapshot or an invocation record. */
+export declare const PLATFORM_SOURCE = "platform:";
+/** The snapshot `source` of a platform skill version stored at `prefix` (in `deployment/`). */
+export declare const platformSource: (prefix: string) => string;
+/**
+ * Where the files of a skill version with snapshot `source` live: `deployment/` for a platform
+ * version (`platform:<prefix>`), else the org's `kernel/<orgId>/`; `prefix` is the key prefix in
+ * that store.
+ */
+export declare function skillFileStore(storage: {
+    kernel(orgId: string): ObjectStore;
+    deployment(): ObjectStore;
+}, orgId: string, source: string): {
+    store: ObjectStore;
+    prefix: string;
+};
+/** A skill the org can use: one of its own, or a platform skill that is on in the org. */
+export interface UsableSkill {
+    id: string;
+    name: string;
+    description: string;
+    version: number;
+    /** The object prefix of the version (`platform:<prefix>` for a platform version). */
+    source: string;
+    /** The plugin it came from (a platform skill's plugin, an org skill's provenance). */
+    plugin: string | null;
+    origin: "org" | "platform";
+    /** The platform skill whose content this is (a platform skill, or a linked org copy). */
+    platformSkillId?: string;
+}
+/** A usable or selected skill with what the resolvers need beyond {@link UsableSkill}. */
+export interface SkillVersionRow extends UsableSkill {
+    /** `agent`: an agent's own skill (never in the org library). Platform skills are `org`. */
+    scope: "org" | "agent";
+    agentId: string | null;
+    manifest: SkillManifest;
+    format: SourceFormat;
+}
+/**
+ * The ids among `ids` of the platform skills on in the org (see {@link platformOn}), whatever the
+ * org's own skills are named: a skill of the org with the same name would clash with them.
+ */
+export declare function platformSkillsOn(db: KernelSchemaDb, orgId: string, ids: readonly string[]): Promise<Set<string>>;
+/**
+ * The ids among `ids` (platform skills that org copies are pinned to) whose pinned copies the org
+ * may use (ruling P2-18): the platform skill is on in the org ({@link platformSkillsOn}), or it was
+ * removed by a plugin update (soft-deleted, ruling P2-7: a pinned copy then keeps its own version
+ * as the org's).
+ */
+export declare function pinnedSkillLinksServed(db: KernelSchemaDb, orgId: string, ids: readonly string[]): Promise<Set<string>>;
+/**
+ * The org's live skills by id (`ids`; ids that are no usable skill are missing from the map): an
+ * agent's own skill or an org skill with its current version; an org copy linked to a platform
+ * skill without a pin (ruling B2) as that platform skill's current version under the copy's id,
+ * while the platform skill is on in the org; a pinned copy as its own version, while its platform
+ * skill is on in the org (ruling P2-18); a platform skill id while it is on in the org.
+ */
+export declare function skillVersionsById(db: KernelSchemaDb, orgId: string, ids: readonly string[], log?: Pick<Logger, "warn">): Promise<Map<string, SkillVersionRow>>;
+/**
+ * The skills an agent selects, sorted by id: its own skills (`scope = 'agent'`), the org skills
+ * it shared (`origin_agent_id`: the agent keeps a shared skill without a definition change) and
+ * the ids of `orgSkills` that resolve ({@link skillVersionsById}: org skills, linked copies,
+ * platform skills on in the org). Not deduplicated by name.
+ */
+export declare function selectedSkills(db: KernelSchemaDb, a: {
+    orgId: string;
+    agentId: string;
+    orgSkills: readonly string[];
+}, log?: Pick<Logger, "warn">): Promise<SkillVersionRow[]>;
+/**
+ * The org's usable skills, sorted by name: its own live org skills (`scope = 'org'`, unlinked, or
+ * pinned while their platform skill is on in the org, ruling P2-18) and the platform skills on in
+ * the org (see {@link platformOn}). An org copy linked
+ * without a pin is not listed: its platform skill is; except the org's own skill it promoted
+ * (ruling P3-3), listed once under its own id instead of the platform skill.
+ * `log` receives the name-clash warnings.
+ */
+export declare function usableSkills(db: KernelSchemaDb, orgId: string, log?: Pick<Logger, "warn">): Promise<UsableSkill[]>;
+/** {@link usableSkills} with each skill's manifest and format. */
+export declare function usableSkillVersions(db: KernelSchemaDb, orgId: string, log?: Pick<Logger, "warn">): Promise<SkillVersionRow[]>;

package/dist/skills/usable.js

@@ -0,0 +1,388 @@
+import { componentOn } from "../catalog/component-state.js";
+/** The `source` prefix of a platform skill version in a snapshot or an invocation record. */
+export const PLATFORM_SOURCE = "platform:";
+/** The snapshot `source` of a platform skill version stored at `prefix` (in `deployment/`). */
+export const platformSource = (prefix) => `${PLATFORM_SOURCE}${prefix}`;
+/**
+ * Where the files of a skill version with snapshot `source` live: `deployment/` for a platform
+ * version (`platform:<prefix>`), else the org's `kernel/<orgId>/`; `prefix` is the key prefix in
+ * that store.
+ */
+export function skillFileStore(storage, orgId, source) {
+    return source.startsWith(PLATFORM_SOURCE)
+        ? { store: storage.deployment(), prefix: source.slice(PLATFORM_SOURCE.length) }
+        : { store: storage.kernel(orgId), prefix: source };
+}
+/** Plugin install statuses that make a plugin on in the org (phase 1, org catalog state). */
+const LIVE_INSTALL = ["installing", "installed", "upgrading"];
+const byNameThenId = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+/** The live platform skill rows on in the org (`ids`: only those), before any name clash. */
+async function platformRowsOn(db, orgId, ids) {
+    if (ids !== undefined && ids.length === 0)
+        return [];
+    let q = db
+        .selectFrom("platform_skills as p")
+        .innerJoin("platform_skill_versions as v", (j) => j.onRef("v.skill_id", "=", "p.id").onRef("v.version", "=", "p.current_version"))
+        .leftJoin("catalog_items as c", (j) => j.onRef("c.id", "=", "p.catalog_item_id").on("c.deleted_at", "is", null))
+        .select((eb) => [
+        "p.id",
+        "p.name",
+        "p.plugin_name",
+        "p.catalog_item_id",
+        "p.current_version",
+        "p.scope_mode",
+        "p.scope",
+        "v.manifest",
+        "v.object_prefix",
+        "v.source_format",
+        "c.id as item_id",
+        "c.disabled as item_disabled",
+        "c.builtin as item_builtin",
+        eb
+            .exists(eb
+            .selectFrom("plugin_installs as a")
+            .select("a.id")
+            .whereRef("a.item_id", "=", "p.catalog_item_id")
+            .where("a.org_id", "=", orgId)
+            .where("a.status", "in", [...LIVE_INSTALL]))
+            .as("installed"),
+        eb
+            .exists(eb
+            .selectFrom("component_scope_orgs as l")
+            .select("l.org_id")
+            .where("l.kind", "=", "skill")
+            .whereRef("l.component_id", "=", "p.id")
+            .where("l.org_id", "=", orgId))
+            .as("listed"),
+        eb
+            .selectFrom("component_org_switches as w")
+            .select("w.enabled")
+            .where("w.kind", "=", "skill")
+            .whereRef("w.component_id", "=", "p.id")
+            .where("w.org_id", "=", orgId)
+            .as("switch"),
+    ])
+        .where("p.deleted_at", "is", null)
+        .where("p.disabled", "=", false);
+    if (ids !== undefined)
+        q = q.where("p.id", "in", [...ids]);
+    // the predicate of component scope (catalog/component-state.ts); `disabled` is filtered above
+    return (await q.execute()).filter((r) => componentOn({ scopeMode: r.scope_mode, scope: r.scope, disabled: false, itemId: r.catalog_item_id }, r.catalog_item_id === null
+        ? null
+        : {
+            live: r.item_id !== null,
+            disabled: r.item_disabled === true,
+            builtin: r.item_builtin === true,
+            // the plugin's own scope and list do not decide whether a component is on
+            scope: "optional",
+            listed: false,
+            installed: Boolean(r.installed),
+        }, Boolean(r.listed), r.switch ?? null));
+}
+/**
+ * The ids among `ids` of the platform skills on in the org (see {@link platformOn}), whatever the
+ * org's own skills are named: a skill of the org with the same name would clash with them.
+ */
+export async function platformSkillsOn(db, orgId, ids) {
+    return new Set((await platformRowsOn(db, orgId, ids)).map((r) => r.id));
+}
+/**
+ * The ids among `ids` (platform skills that org copies are pinned to) whose pinned copies the org
+ * may use (ruling P2-18): the platform skill is on in the org ({@link platformSkillsOn}), or it was
+ * removed by a plugin update (soft-deleted, ruling P2-7: a pinned copy then keeps its own version
+ * as the org's).
+ */
+export async function pinnedSkillLinksServed(db, orgId, ids) {
+    if (ids.length === 0)
+        return new Set();
+    const removed = await db
+        .selectFrom("platform_skills")
+        .select("id")
+        .where("id", "in", [...ids])
+        .where("deleted_at", "is not", null)
+        .execute();
+    return new Set([...(await platformSkillsOn(db, orgId, ids)), ...removed.map((r) => r.id)]);
+}
+/**
+ * The platform skills on in the org (`ids`: only those), minus the ones whose name an org skill of
+ * its own already uses (rule 10: the org's wins; logged unless that skill is a copy of the same
+ * component: linked to it, or carrying the same plugin's provenance before the migration linked
+ * it). On in the org:
+ * - never when the skill or its plugin is disabled (or its plugin is deleted);
+ * - `follow`: its plugin is on in the org (a live install, or builtin) and no component switch of
+ *   the org says off;
+ * - `own`: `wantedOn` over the skill's own scope, the org's list membership and its switch.
+ * One query for the skills with their plugin and org state, one for the org's names.
+ */
+async function platformOn(db, orgId, ids, log) {
+    const rows = await platformRowsOn(db, orgId, ids);
+    if (rows.length === 0)
+        return [];
+    const own = await db
+        .selectFrom("skills")
+        .select(["id", "name", "platform_skill_id", "catalog_item_id"])
+        .where("org_id", "=", orgId)
+        .where("scope", "=", "org")
+        .where("deleted_at", "is", null)
+        .where((eb) => eb.or([eb("platform_skill_id", "is", null), eb("pinned_version", "is not", null)]))
+        .where("name", "in", [...new Set(rows.map((r) => r.name))])
+        .execute();
+    const ownByName = new Map(own.map((r) => [r.name, r]));
+    const out = [];
+    const taken = new Map();
+    rows.sort((a, b) => (a.plugin_name ?? "") < (b.plugin_name ?? "")
+        ? -1
+        : (a.plugin_name ?? "") > (b.plugin_name ?? "")
+            ? 1
+            : a.id < b.id
+                ? -1
+                : 1);
+    for (const r of rows) {
+        const o = ownByName.get(r.name);
+        if (o) {
+            const sameComponent = o.platform_skill_id === r.id ||
+                (o.catalog_item_id !== null && o.catalog_item_id === r.catalog_item_id);
+            if (!sameComponent) {
+                log?.warn("platform skill shadowed by an org skill of the same name", {
+                    orgId,
+                    name: r.name,
+                    platformSkillId: r.id,
+                    skillId: o.id,
+                });
+            }
+            continue;
+        }
+        const first = taken.get(r.name);
+        if (first !== undefined) {
+            log?.warn("platform skills share a name in one org", {
+                orgId,
+                name: r.name,
+                kept: first,
+                dropped: r.id,
+            });
+            continue;
+        }
+        taken.set(r.name, r.id);
+        out.push({
+            id: r.id,
+            name: r.name,
+            description: r.manifest.description,
+            version: r.current_version,
+            source: platformSource(r.object_prefix),
+            plugin: r.plugin_name,
+            origin: "platform",
+            platformSkillId: r.id,
+            scope: "org",
+            agentId: null,
+            manifest: r.manifest,
+            format: r.source_format,
+        });
+    }
+    return out;
+}
+/**
+ * The org's live skills by id (`ids`; ids that are no usable skill are missing from the map): an
+ * agent's own skill or an org skill with its current version; an org copy linked to a platform
+ * skill without a pin (ruling B2) as that platform skill's current version under the copy's id,
+ * while the platform skill is on in the org; a pinned copy as its own version, while its platform
+ * skill is on in the org (ruling P2-18); a platform skill id while it is on in the org.
+ */
+export async function skillVersionsById(db, orgId, ids, log) {
+    const unique = [...new Set(ids)];
+    const out = new Map();
+    if (unique.length === 0)
+        return out;
+    const rows = await db
+        .selectFrom("skills as s")
+        .innerJoin("skill_versions as v", (j) => j.onRef("v.skill_id", "=", "s.id").onRef("v.version", "=", "s.current_version"))
+        .leftJoin("catalog_items as c", "c.id", "s.catalog_item_id")
+        .select([
+        "s.id",
+        "s.scope",
+        "s.agent_id",
+        "s.name",
+        "s.current_version",
+        "s.platform_skill_id",
+        "s.pinned_version",
+        "v.manifest",
+        "v.object_prefix",
+        "v.source_format",
+        "c.name as item_name",
+    ])
+        .where("s.org_id", "=", orgId)
+        .where("s.deleted_at", "is", null)
+        .where("s.id", "in", unique)
+        .execute();
+    const linked = rows.filter((r) => r.scope === "org" && r.platform_skill_id !== null && r.pinned_version === null);
+    const pinned = rows.filter((r) => r.scope === "org" && r.platform_skill_id !== null && r.pinned_version !== null);
+    const known = new Set(rows.map((r) => r.id));
+    const platformIds = [
+        ...new Set([
+            ...unique.filter((id) => !known.has(id)),
+            ...linked.map((r) => r.platform_skill_id),
+        ]),
+    ];
+    const platform = new Map((await platformOn(db, orgId, platformIds, log)).map((p) => [p.id, p]));
+    const owned = await ownedPlatformIds(db, orgId, linked.map((r) => r.platform_skill_id));
+    // ruling P2-18: a pinned copy serves its own version while its platform skill is on in the org
+    const pinnedOn = await pinnedSkillLinksServed(db, orgId, pinned.map((r) => r.platform_skill_id));
+    for (const r of rows) {
+        if (linked.includes(r)) {
+            const p = platform.get(r.platform_skill_id);
+            if (!p)
+                continue;
+            if (!owned.has(p.id)) {
+                out.set(r.id, { ...p, id: r.id });
+                continue;
+            }
+            // the org's own skill, promoted (ruling P3-3): promotion copied its current version to the
+            // platform under the same number, so while that is still the platform's current version it
+            // serves its own stored version (its snapshot source stays); a newer platform version (the
+            // owner's later upload, ruling P3-4) serves under its id. Either way it is the org's own.
+            if (r.current_version !== p.version) {
+                out.set(r.id, { ...p, id: r.id, origin: "org", plugin: r.item_name });
+                continue;
+            }
+        }
+        if (pinned.includes(r) && !pinnedOn.has(r.platform_skill_id))
+            continue;
+        out.set(r.id, {
+            id: r.id,
+            name: r.name,
+            description: r.manifest.description,
+            version: r.current_version,
+            source: r.object_prefix,
+            plugin: r.item_name,
+            origin: "org",
+            ...(r.platform_skill_id !== null && { platformSkillId: r.platform_skill_id }),
+            scope: r.scope,
+            agentId: r.agent_id,
+            manifest: r.manifest,
+            format: r.source_format,
+        });
+    }
+    for (const id of unique) {
+        const p = platform.get(id);
+        if (p && !known.has(id))
+            out.set(id, p);
+    }
+    return out;
+}
+/**
+ * The ids among `platformIds` of the live platform skills owned by `orgId` (promoted from its own
+ * skills, ruling P3-3).
+ */
+async function ownedPlatformIds(db, orgId, platformIds) {
+    if (platformIds.length === 0)
+        return new Set();
+    const rows = await db
+        .selectFrom("platform_skills")
+        .select("id")
+        .where("id", "in", [...new Set(platformIds)])
+        .where("owner_org_id", "=", orgId)
+        .where("deleted_at", "is", null)
+        .execute();
+    return new Set(rows.map((r) => r.id));
+}
+/**
+ * The skills an agent selects, sorted by id: its own skills (`scope = 'agent'`), the org skills
+ * it shared (`origin_agent_id`: the agent keeps a shared skill without a definition change) and
+ * the ids of `orgSkills` that resolve ({@link skillVersionsById}: org skills, linked copies,
+ * platform skills on in the org). Not deduplicated by name.
+ */
+export async function selectedSkills(db, a, log) {
+    const agentOwn = await db
+        .selectFrom("skills")
+        .select("id")
+        .where("org_id", "=", a.orgId)
+        .where("scope", "=", "agent")
+        .where("agent_id", "=", a.agentId)
+        .where("deleted_at", "is", null)
+        .execute();
+    const shared = await db
+        .selectFrom("skills")
+        .select("id")
+        .where("org_id", "=", a.orgId)
+        .where("scope", "=", "org")
+        .where("origin_agent_id", "=", a.agentId)
+        .where("deleted_at", "is", null)
+        .execute();
+    const orgSkills = new Set([...a.orgSkills, ...shared.map((r) => r.id)]);
+    const byId = await skillVersionsById(db, a.orgId, [...agentOwn.map((r) => r.id), ...orgSkills], log);
+    return [...byId.values()]
+        .filter((r) => (r.scope === "agent" ? r.agentId === a.agentId : orgSkills.has(r.id)))
+        .sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0));
+}
+/**
+ * The org's usable skills, sorted by name: its own live org skills (`scope = 'org'`, unlinked, or
+ * pinned while their platform skill is on in the org, ruling P2-18) and the platform skills on in
+ * the org (see {@link platformOn}). An org copy linked
+ * without a pin is not listed: its platform skill is; except the org's own skill it promoted
+ * (ruling P3-3), listed once under its own id instead of the platform skill.
+ * `log` receives the name-clash warnings.
+ */
+export async function usableSkills(db, orgId, log) {
+    return (await usableSkillVersions(db, orgId, log)).map(({ scope: _s, agentId: _a, manifest: _m, format: _f, ...u }) => u);
+}
+/** {@link usableSkills} with each skill's manifest and format. */
+export async function usableSkillVersions(db, orgId, log) {
+    const own = await db
+        .selectFrom("skills as s")
+        .innerJoin("skill_versions as v", (j) => j.onRef("v.skill_id", "=", "s.id").onRef("v.version", "=", "s.current_version"))
+        .leftJoin("catalog_items as c", "c.id", "s.catalog_item_id")
+        .select([
+        "s.id",
+        "s.name",
+        "s.current_version",
+        "s.platform_skill_id",
+        "v.manifest",
+        "v.object_prefix",
+        "v.source_format",
+        "c.name as item_name",
+    ])
+        .where("s.org_id", "=", orgId)
+        .where("s.scope", "=", "org")
+        .where("s.deleted_at", "is", null)
+        .where((eb) => eb.or([eb("s.platform_skill_id", "is", null), eb("s.pinned_version", "is not", null)]))
+        .execute();
+    // ruling P2-18: a pinned copy follows its platform skill's availability (the pin fixes the
+    // version only)
+    const pinnedOn = await pinnedSkillLinksServed(db, orgId, [
+        ...new Set(own.flatMap((r) => (r.platform_skill_id === null ? [] : [r.platform_skill_id]))),
+    ]);
+    const rows = own
+        .filter((r) => r.platform_skill_id === null || pinnedOn.has(r.platform_skill_id))
+        .map((r) => ({
+        id: r.id,
+        name: r.name,
+        description: r.manifest.description,
+        version: r.current_version,
+        source: r.object_prefix,
+        plugin: r.item_name,
+        origin: "org",
+        ...(r.platform_skill_id !== null && { platformSkillId: r.platform_skill_id }),
+        scope: "org",
+        agentId: null,
+        manifest: r.manifest,
+        format: r.source_format,
+    }));
+    // the org's own skills it promoted: under their own ids, instead of their platform skills
+    const promoted = await db
+        .selectFrom("skills as s")
+        .innerJoin("platform_skills as p", "p.id", "s.platform_skill_id")
+        .select(["s.id", "s.platform_skill_id"])
+        .where("s.org_id", "=", orgId)
+        .where("s.scope", "=", "org")
+        .where("s.deleted_at", "is", null)
+        .where("s.pinned_version", "is", null)
+        .where("p.owner_org_id", "=", orgId)
+        .where("p.deleted_at", "is", null)
+        .execute();
+    const promotedTo = new Set(promoted.map((r) => r.platform_skill_id));
+    if (promoted.length > 0) {
+        const served = await skillVersionsById(db, orgId, promoted.map((r) => r.id), log);
+        rows.push(...served.values());
+    }
+    rows.push(...(await platformOn(db, orgId, undefined, log)).filter((p) => !promotedTo.has(p.id)));
+    return rows.sort(byNameThenId);
+}

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

@@ -0,0 +1,13 @@
+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. The whole
+ * stylesheet is one `@layer theme { … }` block (client extensions spec §7.2).
+ */
+export declare function renderThemeCss(theme: ParsedTheme, assetUrl: (pluginPath: string) => string, onSkipped?: (paths: string[]) => void): string;

package/dist/themes/render-css.js

@@ -0,0 +1,135 @@
+// 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. The whole
+ * stylesheet is one `@layer theme { … }` block (client extensions spec §7.2).
+ */
+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);
+    // One block in the `theme` cascade layer (client extensions spec §7.2): the design stylesheet
+    // declares the order design, theme, extensions; an unlayered theme would beat plugin CSS.
+    return `@layer theme {\n${rules.join("\n")}\n}\n`;
+}

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

@@ -0,0 +1,36 @@
+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, or a `revision` other than the
+     * current `r<THEME_CSS_REVISION>` (an older one promised another format; a later one belongs to a
+     * newer replica): 404 `theme.not_found`, never cached.
+     */
+    stylesheet(id: string, version: string, revision: string): Promise<string>;
+    /**
+     * Asset `file` (a path inside the plugin, as stored: `fonts/MiSans.woff2`) of version `version`
+     * of theme `id`: only a font or logo the version's definition names. Unknown theme, version or
+     * file: 404 `theme.not_found`.
+     */
+    asset(id: string, version: string, file: string): Promise<ThemeAsset>;
+}