@aphexcms/cms-core 9.4.0 → 9.5.0

package/dist/services/plugin-settings-service.js

@@ -0,0 +1,235 @@
+// services/plugin-settings-service.ts
+//
+// Resolves and persists a plugin's per-organization settings — the "config plane"
+// (see references/plugin-settings-and-secrets-scope.md). A plugin declares its
+// settings shape via an `aphex/settings` part; this service merges the declared
+// defaults with the stored per-(org, plugin) values and writes edits back, scoped
+// to the org.
+//
+// Secrets (`type: 'secret'` fields) are handled specially:
+//   - stored AES-256-GCM-encrypted (never plaintext),
+//   - decrypted only for server injection (`get`), never for the client (`getMasked`),
+//   - write-only: a blank/masked submission means "leave unchanged".
+// When no encryption key is configured, secret writes are refused and secret reads
+// return nothing — fail safe, never store or reveal a plaintext secret.
+import { encryptSecret, decryptSecret, isEncryptedSecret } from '../security/secret-crypto.js';
+import { settingsListItems } from '../schema-utils/settings.js';
+import { cmsLogger } from '../utils/logger.js';
+/** Placeholder shown to the client for a secret that has a stored value. */
+export const SECRET_MASK = '••••••';
+const isSecret = (f) => f.type === 'secret';
+/**
+ * Static default for a field — its `initialValue` when that's a plain value (not a
+ * function/thunk). Secrets never carry a default.
+ */
+function fieldDefault(field) {
+    if (isSecret(field))
+        return undefined;
+    const initial = field.initialValue;
+    return typeof initial === 'function' ? undefined : initial;
+}
+/** Build the defaults object from a declaration's fields (skips undefined). */
+function defaultsFor(fields) {
+    const out = {};
+    for (const field of fields) {
+        const value = fieldDefault(field);
+        if (value !== undefined)
+            out[field.name] = value;
+    }
+    return out;
+}
+/** Raised when a submitted value doesn't match its declared field type. */
+export class PluginSettingsValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid plugin settings: ${issues.join('; ')}`);
+        this.issues = issues;
+        this.name = 'PluginSettingsValidationError';
+    }
+}
+/**
+ * Check one submitted value against its declared field type, returning an error
+ * message or `null`.
+ *
+ * The declaration is the contract, so the host enforces it here rather than leaving
+ * every plugin to re-guard values it already described. Without this a `string` field
+ * would happily store an object, and the plugin would find out at request time, deep
+ * in its own code, with no useful trace back to the save that caused it.
+ *
+ * `null` is always allowed — it's how the panel represents "cleared".
+ */
+function checkValue(field, value) {
+    if (value === null)
+        return null;
+    switch (field.type) {
+        case 'string': {
+            if (typeof value !== 'string')
+                return `"${field.name}" must be a string`;
+            // A select-style string field may only hold one of its declared options.
+            const items = settingsListItems(field);
+            if (items.length > 0 && !items.some((item) => item.value === value)) {
+                return `"${field.name}" must be one of: ${items.map((i) => i.value).join(', ')}`;
+            }
+            return null;
+        }
+        case 'text':
+            if (typeof value !== 'string')
+                return `"${field.name}" must be a string`;
+            return null;
+        case 'number':
+            // Reject NaN/Infinity too — they survive JSON as null and corrupt round-trips.
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                return `"${field.name}" must be a finite number`;
+            }
+            if (field.min !== undefined && value < field.min) {
+                return `"${field.name}" must be >= ${field.min}`;
+            }
+            if (field.max !== undefined && value > field.max) {
+                return `"${field.name}" must be <= ${field.max}`;
+            }
+            return null;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                return `"${field.name}" must be a boolean`;
+            return null;
+        case 'secret':
+            // Secrets are write-only strings; blank/mask is handled before this point.
+            if (typeof value !== 'string')
+                return `"${field.name}" must be a string`;
+            return null;
+    }
+}
+export class PluginSettingsService {
+    db;
+    resolver;
+    encryptionKey;
+    constructor(
+    /** Narrowed to the two methods this service uses — the full adapter satisfies it. */
+    db, 
+    /** Likewise: settings resolution is the only part of the resolver needed here. */
+    resolver, 
+    /** Key for encrypting `secret` fields; when absent, secrets are disabled (fail safe). */
+    encryptionKey = null) {
+        this.db = db;
+        this.resolver = resolver;
+        this.encryptionKey = encryptionKey;
+    }
+    /** Whether secret fields can be stored/read (an encryption key is configured). */
+    get secretsEnabled() {
+        return typeof this.encryptionKey === 'string' && this.encryptionKey.length > 0;
+    }
+    secretFieldNames(declaration) {
+        return new Set(declaration.fields.filter(isSecret).map((f) => f.name));
+    }
+    /**
+     * Effective values for injection into plugin **server** code: declared defaults
+     * overlaid with stored values, with secrets **decrypted** to plaintext. Secrets
+     * that can't be decrypted (no key, or a bad envelope) are omitted, never returned
+     * as ciphertext. This is the sensitive read — never send its result to a client.
+     */
+    async get(organizationId, pluginId) {
+        const declaration = this.resolver.settingsDeclaration(pluginId);
+        const stored = (await this.db.getPluginSettings(organizationId, pluginId)) ?? {};
+        const defaults = declaration ? defaultsFor(declaration.fields) : {};
+        const merged = { ...defaults, ...stored };
+        if (!declaration)
+            return merged;
+        const secrets = this.secretFieldNames(declaration);
+        for (const name of secrets) {
+            const value = merged[name];
+            if (!isEncryptedSecret(value)) {
+                // Unset or non-envelope — nothing usable to inject.
+                delete merged[name];
+                continue;
+            }
+            if (!this.secretsEnabled) {
+                delete merged[name];
+                continue;
+            }
+            try {
+                merged[name] = decryptSecret(value, this.encryptionKey);
+            }
+            catch (error) {
+                cmsLogger.error(`Failed to decrypt secret "${pluginId}.${name}":`, error);
+                delete merged[name];
+            }
+        }
+        return merged;
+    }
+    /**
+     * Effective values for the **client/API**: same merge, but secrets are **masked** —
+     * a stored secret becomes {@link SECRET_MASK}, an unset one an empty string. Plaintext
+     * secrets never cross this boundary.
+     */
+    async getMasked(organizationId, pluginId) {
+        const declaration = this.resolver.settingsDeclaration(pluginId);
+        const stored = (await this.db.getPluginSettings(organizationId, pluginId)) ?? {};
+        const defaults = declaration ? defaultsFor(declaration.fields) : {};
+        const merged = { ...defaults, ...stored };
+        if (declaration) {
+            for (const name of this.secretFieldNames(declaration)) {
+                merged[name] = isEncryptedSecret(merged[name]) ? SECRET_MASK : '';
+            }
+        }
+        return merged;
+    }
+    /**
+     * Resolve for the admin surface: the declaration plus masked values plus whether
+     * secrets are enabled. `declaration: null` when the plugin declares no settings.
+     */
+    async resolve(organizationId, pluginId) {
+        const declaration = this.resolver.settingsDeclaration(pluginId) ?? null;
+        const values = await this.getMasked(organizationId, pluginId);
+        return { declaration, values, secretsEnabled: this.secretsEnabled };
+    }
+    /**
+     * Persist a partial edit. Only declared field names are accepted, and each value is
+     * type-checked against its declaration — an invalid patch is rejected whole, never
+     * applied in part, so a failed save can't leave settings half-written. Secret fields
+     * are encrypted; a blank or still-masked secret submission means "leave unchanged"
+     * (so the client never has to echo the real value back). Returns the new **masked**
+     * values — a save response never leaks a plaintext secret.
+     *
+     * @throws {PluginSettingsValidationError} when a value doesn't match its field type.
+     */
+    async save(organizationId, pluginId, patch) {
+        const declaration = this.resolver.settingsDeclaration(pluginId);
+        if (!declaration) {
+            throw new Error(`Plugin "${pluginId}" has not declared any settings.`);
+        }
+        const fieldsByName = new Map(declaration.fields.map((f) => [f.name, f]));
+        const secrets = this.secretFieldNames(declaration);
+        const stored = (await this.db.getPluginSettings(organizationId, pluginId)) ?? {};
+        const next = { ...stored };
+        // Validate the whole patch before writing any of it.
+        const issues = [];
+        const pending = [];
+        for (const [key, value] of Object.entries(patch)) {
+            const field = fieldsByName.get(key);
+            if (!field)
+                continue; // undeclared → dropped
+            if (secrets.has(key)) {
+                // Write-only: blank or the untouched mask means "keep the current value".
+                if (value === '' || value === SECRET_MASK || value == null)
+                    continue;
+                if (!this.secretsEnabled) {
+                    throw new Error(`Cannot store secret "${pluginId}.${key}": no secretEncryptionKey configured.`);
+                }
+            }
+            const issue = checkValue(field, value);
+            if (issue)
+                issues.push(issue);
+            else
+                pending.push([key, value]);
+        }
+        if (issues.length > 0)
+            throw new PluginSettingsValidationError(issues);
+        for (const [key, value] of pending) {
+            next[key] = secrets.has(key)
+                ? encryptSecret(String(value), this.encryptionKey)
+                : value;
+        }
+        await this.db.setPluginSettings(organizationId, pluginId, next);
+        return this.getMasked(organizationId, pluginId);
+    }
+}

package/dist/services/roles-service.d.ts

@@ -1,6 +1,6 @@
 import type { CacheAdapter } from '../cache/index.js';
 import type { DatabaseAdapter } from '../db/index.js';
-import { type Capability, type Role } from '../types/capabilities.js';
+import { type Role } from '../types/capabilities.js';
 /**
  * RolesService — caches per-org role capability lookups.
  *
@@ -23,7 +23,7 @@ export declare class RolesService {
      *   3. Built-in seed if the name matches a built-in.
      *   4. Empty list — unknown role → no capabilities.
      */
-    getCapabilities(organizationId: string, roleName: string): Promise<Capability[]>;
+    getCapabilities(organizationId: string, roleName: string): Promise<string[]>;
     /** List every role defined for an organization. */
     listRoles(organizationId: string): Promise<Role[]>;
     /** Idempotent — safe to call on every request if you want. */

package/dist/services/roles-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roles-service.d.ts","sourceRoot":"","sources":["../../src/lib/services/roles-service.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAGN,KAAK,UAAU,EACf,KAAK,IAAI,EACT,MAAM,uBAAuB,CAAC;AAI/B;;;;;GAKG;AACH,qBAAa,YAAY;IAKvB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,GAAG;IANZ,OAAO,CAAC,MAAM,CAAC,WAAW,CAAM;IAChC,OAAO,CAAC,QAAQ,CAA4C;gBAGnD,EAAE,EAAE,eAAe,EACnB,KAAK,GAAE,YAAY,GAAG,IAAW,EACjC,GAAG,GAAE,MAAiC;IAG/C;;;;;;;;OAQG;IACG,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqBtF,mDAAmD;IAC7C,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAIxD,8DAA8D;IACxD,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D,uEAAuE;IACjE,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAW5D,aAAa;CA2B3B"}
+{"version":3,"file":"roles-service.d.ts","sourceRoot":"","sources":["../../src/lib/services/roles-service.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAyC,KAAK,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAIzF;;;;;GAKG;AACH,qBAAa,YAAY;IAKvB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,GAAG;IANZ,OAAO,CAAC,MAAM,CAAC,WAAW,CAAM;IAChC,OAAO,CAAC,QAAQ,CAAwC;gBAG/C,EAAE,EAAE,eAAe,EACnB,KAAK,GAAE,YAAY,GAAG,IAAW,EACjC,GAAG,GAAE,MAAiC;IAG/C;;;;;;;;OAQG;IACG,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAqBlF,mDAAmD;IAC7C,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAIxD,8DAA8D;IACxD,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D,uEAAuE;IACjE,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAW5D,aAAa;CA2B3B"}

package/dist/theme/css.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Emit theme tokens as a scoped `<style>` body.
+ *
+ * Two hard rules, both learned the expensive way:
+ *  1. NEVER emit site tokens at `:root` — they'd bleed into the admin chrome.
+ *     Always scope to the site shell selector.
+ *  2. Theme values are user-authored, so sanitize before interpolating. Any value
+ *     that could break out of the `--var: value;` declaration (contains `;`, `{`,
+ *     `}`, `<`, `>`, or a CSS `url(`/`expression(`) is dropped, and the token's
+ *     CSS fallback in the layout applies instead.
+ */
+/** Return the value if safe to interpolate into a CSS declaration, else null. */
+export declare function sanitizeTokenValue(value: string): string | null;
+/**
+ * Build a sanitized `--var: value; …` declaration list from a `cssVar → value`
+ * map (see deriveThemeVars). Suitable for an inline `style` attribute on the site
+ * shell element — the simplest way to scope tokens to the site subtree while
+ * beating component-CSS specificity, with no `<style>` injection to guard. Returns
+ * `''` when nothing survives sanitization.
+ */
+export declare function emitThemeVars(vars: Record<string, string>): string;
+/**
+ * Build a scoped style *rule* from a `cssVar → value` map, for callers that
+ * prefer injecting a `<style>` block over an inline attribute. Returns `''` when
+ * nothing survives sanitization, so callers can skip rendering an empty `<style>`.
+ *
+ * @param selector CSS selector to scope the custom properties to, e.g. `.blog-shell`.
+ */
+export declare function emitThemeStyle(selector: string, vars: Record<string, string>): string;
+//# sourceMappingURL=css.d.ts.map

package/dist/theme/css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css.d.ts","sourceRoot":"","sources":["../../src/lib/theme/css.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK/D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAWlE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAIrF"}

package/dist/theme/css.js

@@ -0,0 +1,53 @@
+/**
+ * Emit theme tokens as a scoped `<style>` body.
+ *
+ * Two hard rules, both learned the expensive way:
+ *  1. NEVER emit site tokens at `:root` — they'd bleed into the admin chrome.
+ *     Always scope to the site shell selector.
+ *  2. Theme values are user-authored, so sanitize before interpolating. Any value
+ *     that could break out of the `--var: value;` declaration (contains `;`, `{`,
+ *     `}`, `<`, `>`, or a CSS `url(`/`expression(`) is dropped, and the token's
+ *     CSS fallback in the layout applies instead.
+ */
+const UNSAFE = /[;{}<>]|url\s*\(|expression\s*\(/i;
+/** Return the value if safe to interpolate into a CSS declaration, else null. */
+export function sanitizeTokenValue(value) {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return null;
+    if (UNSAFE.test(trimmed))
+        return null;
+    return trimmed;
+}
+/**
+ * Build a sanitized `--var: value; …` declaration list from a `cssVar → value`
+ * map (see deriveThemeVars). Suitable for an inline `style` attribute on the site
+ * shell element — the simplest way to scope tokens to the site subtree while
+ * beating component-CSS specificity, with no `<style>` injection to guard. Returns
+ * `''` when nothing survives sanitization.
+ */
+export function emitThemeVars(vars) {
+    const declarations = [];
+    for (const [cssVar, rawValue] of Object.entries(vars)) {
+        if (!cssVar.startsWith('--'))
+            continue;
+        const value = sanitizeTokenValue(rawValue);
+        if (value === null)
+            continue;
+        declarations.push(`${cssVar}: ${value};`);
+    }
+    return declarations.join(' ');
+}
+/**
+ * Build a scoped style *rule* from a `cssVar → value` map, for callers that
+ * prefer injecting a `<style>` block over an inline attribute. Returns `''` when
+ * nothing survives sanitization, so callers can skip rendering an empty `<style>`.
+ *
+ * @param selector CSS selector to scope the custom properties to, e.g. `.blog-shell`.
+ */
+export function emitThemeStyle(selector, vars) {
+    const body = emitThemeVars(vars);
+    if (body === '')
+        return '';
+    return `${selector} { ${body} }`;
+}

package/dist/theme/derive.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Derive the admin schema and the runtime CSS-var map from a token list.
+ *
+ * `deriveThemeFields()` feeds the `theme` singleton schema; `deriveThemeVars()`
+ * turns a saved theme document into `{ '--accent': '#…', … }`. Both walk the same
+ * token list, so the form and the rendered CSS can never drift. The app supplies
+ * the tokens (see the app's `theme/tokens.ts`).
+ */
+import type { Field, FieldGroup } from '../types/schemas.js';
+import type { ThemeToken } from './tokens.js';
+/**
+ * Build the field-group list for a theme singleton, one group per distinct
+ * `token.group` in first-seen order. The first group is marked `default`.
+ */
+export declare function deriveThemeFieldGroups(tokens: ThemeToken[]): FieldGroup[];
+/** Build the field list for the `theme` singleton schema from the token set. */
+export declare function deriveThemeFields(tokens: ThemeToken[]): Field[];
+/**
+ * Resolve a theme document into a `cssVar → value` map, falling back to each
+ * token's default when the document omits or blanks a value. Font values are
+ * resolved to their full CSS stack; colors pass through (sanitized in ./css.ts).
+ *
+ * Accepts `unknown` so callers can pass a concrete generated document type (which
+ * lacks a string index signature) without casting; keys are read dynamically.
+ */
+export declare function deriveThemeVars(values: unknown, tokens: ThemeToken[]): Record<string, string>;
+//# sourceMappingURL=derive.d.ts.map

package/dist/theme/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/lib/theme/derive.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAWzE;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,KAAK,EAAE,CA0C/D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuC7F"}

package/dist/theme/derive.js

@@ -0,0 +1,107 @@
+/**
+ * Build the field-group list for a theme singleton, one group per distinct
+ * `token.group` in first-seen order. The first group is marked `default`.
+ */
+export function deriveThemeFieldGroups(tokens) {
+    const seen = new Map();
+    for (const token of tokens) {
+        if (seen.has(token.group))
+            continue;
+        seen.set(token.group, {
+            name: token.group,
+            title: token.group.charAt(0).toUpperCase() + token.group.slice(1),
+            default: seen.size === 0
+        });
+    }
+    return [...seen.values()];
+}
+/** Build the field list for the `theme` singleton schema from the token set. */
+export function deriveThemeFields(tokens) {
+    return tokens.map((token) => {
+        const base = {
+            name: token.name,
+            title: token.title,
+            description: token.description,
+            group: token.group
+        };
+        switch (token.kind) {
+            case 'color':
+                // Color is a plugin field widget, not a built-in type. Emit a string
+                // field wired to the color-picker input; without the plugin installed it
+                // degrades to a plain text input (still a valid CSS color string).
+                return { ...base, type: 'string', input: 'color', initialValue: token.default };
+            case 'range':
+                return {
+                    ...base,
+                    type: 'number',
+                    min: token.min,
+                    max: token.max,
+                    step: token.step,
+                    initialValue: token.default,
+                    options: { layout: 'slider', unit: token.unit }
+                };
+            case 'select':
+                return {
+                    ...base,
+                    type: 'string',
+                    initialValue: token.default,
+                    list: token.options.map((o) => ({ title: o.title, value: o.value })),
+                    options: { layout: 'dropdown' }
+                };
+            case 'font':
+                return {
+                    ...base,
+                    type: 'string',
+                    initialValue: token.default,
+                    list: token.options.map((o) => ({ title: o.title, value: o.value })),
+                    options: { layout: 'dropdown' }
+                };
+        }
+    });
+}
+/**
+ * Resolve a theme document into a `cssVar → value` map, falling back to each
+ * token's default when the document omits or blanks a value. Font values are
+ * resolved to their full CSS stack; colors pass through (sanitized in ./css.ts).
+ *
+ * Accepts `unknown` so callers can pass a concrete generated document type (which
+ * lacks a string index signature) without casting; keys are read dynamically.
+ */
+export function deriveThemeVars(values, tokens) {
+    const vars = {};
+    const doc = {};
+    if (values && typeof values === 'object')
+        Object.assign(doc, values);
+    for (const token of tokens) {
+        const raw = doc[token.name];
+        switch (token.kind) {
+            case 'color': {
+                vars[token.cssVar] =
+                    typeof raw === 'string' && raw.trim() !== '' ? raw.trim() : token.default;
+                break;
+            }
+            case 'select': {
+                const selected = typeof raw === 'string' && raw.trim() !== '' ? raw.trim() : token.default;
+                const known = token.options.some((o) => o.value === selected);
+                vars[token.cssVar] = known ? selected : token.default;
+                break;
+            }
+            case 'range': {
+                const n = typeof raw === 'number' && Number.isFinite(raw) ? raw : token.default;
+                vars[token.cssVar] = `${n}${token.unit ?? ''}`;
+                break;
+            }
+            case 'font': {
+                // Map the stored value to its stack; unknown/blank → default option.
+                const selected = typeof raw === 'string' && raw.trim() !== '' ? raw.trim() : token.default;
+                const option = token.options.find((o) => o.value === selected) ??
+                    token.options.find((o) => o.value === token.default) ??
+                    token.options[0];
+                if (option)
+                    vars[token.cssVar] = option.stack;
+                break;
+            }
+        }
+    }
+    return vars;
+}

package/dist/theme/index.d.ts

@@ -0,0 +1,5 @@
+export * from './tokens.js';
+export * from './derive.js';
+export * from './css.js';
+export * from './schemes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/theme/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/theme/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC"}

package/dist/theme/index.js

@@ -0,0 +1,4 @@
+export * from './tokens.js';
+export * from './derive.js';
+export * from './css.js';
+export * from './schemes.js';

package/dist/theme/schemes.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Color schemes — the reusable palette unit.
+ *
+ * A scheme is seeded with THREE colors (surface, text, primary). Everything else —
+ * the on-primary contrast color, muted/faint text, hairline borders, raised
+ * surfaces, the hover-ink of the accent — is DERIVED, so every scheme is
+ * internally consistent and the editor tunes three dials instead of eight.
+ *
+ * Each scheme is emitted as a scoped class (`.scheme-<name>`) that remaps the same
+ * CSS custom properties the site components already consume (`--paper`, `--ink`,
+ * `--accent`, …). The site shell wears the default scheme; any section can wear a
+ * different one by adding its class — that's the page-builder primitive.
+ *
+ * Typography and layout are deliberately NOT part of a scheme: they're global,
+ * the same way Shopify keeps type/layout out of its color schemes.
+ */
+import type { ArrayField } from '../types/schemas.js';
+/** The three seed colors an editor sets per scheme. */
+export interface ColorScheme {
+    /** Human label; also slugified into the scheme's CSS class. */
+    name: string;
+    /** Background. */
+    surface: string;
+    /** Foreground text. */
+    text: string;
+    /** Accent — links, buttons, highlights. */
+    primary: string;
+}
+/** Slugify a scheme name into a stable, safe CSS class fragment. */
+export declare function schemeSlug(name: string): string;
+/** The CSS class that carries a scheme's tokens, e.g. `scheme-dark`. */
+export declare function schemeClass(name: string): string;
+/**
+ * Pick a readable on-color (near-black or white) for text/icons that sit on top
+ * of `background`. Falls back to white when the color can't be parsed.
+ */
+export declare function contrastColor(background: string): string;
+/**
+ * Resolve a scheme's three seeds into the full CSS-var role map. Seeds are
+ * sanitized; anything invalid falls back to a sensible default so a scheme always
+ * emits a complete, coherent palette. The derived roles are `color-mix`
+ * expressions over `var(--ink)`/`var(--paper)`, so they recompute correctly for
+ * whichever scheme is in scope — no per-shade user input, no drift.
+ */
+export declare function resolveSchemeVars(scheme: ColorScheme): Record<string, string>;
+/**
+ * Emit one scoped rule per scheme, prefixed so it only styles the site subtree
+ * (never `:root`/admin chrome). Returns `''` when there are no schemes.
+ *
+ * @param scopeSelector Ancestor selector the scheme classes live under, e.g. `.blog-shell`.
+ */
+export declare function emitSchemeStyles(schemes: ColorScheme[], scopeSelector: string): string;
+/** Read a theme document's `schemes` array, falling back to `defaults` when absent. */
+export declare function readSchemes(values: unknown, defaults: ColorScheme[]): ColorScheme[];
+/**
+ * Build the `schemes` array field for the theme singleton — a repeatable object
+ * of { name, surface, text, primary }. The first scheme is the site default.
+ */
+export declare function deriveSchemesField(defaults: ColorScheme[], group: string): ArrayField;
+//# sourceMappingURL=schemes.d.ts.map

package/dist/theme/schemes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemes.d.ts","sourceRoot":"","sources":["../../src/lib/theme/schemes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC3B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;CAChB;AAQD,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AA0BD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkB7E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAYtF;AAED,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAmBnF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAwBrF"}