@aphexcms/cms-core 9.3.0 → 9.5.0

package/dist/lib/theme/derive.js

@@ -0,0 +1,108 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=derive.js.map

package/dist/lib/theme/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../../../src/lib/theme/derive.ts"],"names":[],"mappings":"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"}

package/dist/lib/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/lib/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/lib/theme/index.js

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

package/dist/lib/theme/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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/lib/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/lib/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"}

package/dist/lib/theme/schemes.js

@@ -0,0 +1,150 @@
+import { sanitizeTokenValue } from './css.js';
+const FALLBACK = {
+    surface: '#ffffff',
+    text: '#15171a',
+    primary: '#3eb0ef'
+};
+/** Slugify a scheme name into a stable, safe CSS class fragment. */
+export function schemeSlug(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug || 'scheme';
+}
+/** The CSS class that carries a scheme's tokens, e.g. `scheme-dark`. */
+export function schemeClass(name) {
+    return `scheme-${schemeSlug(name)}`;
+}
+/** Parse a 3/6-digit hex to [r,g,b] in 0–255, or null if not a plain hex. */
+function parseHex(hex) {
+    const m = hex.trim().match(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/);
+    const group = m?.[1];
+    if (!group)
+        return null;
+    const h = group.length === 3
+        ? group
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : group;
+    return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+}
+/** WCAG relative luminance (0 black → 1 white) of an sRGB triple. */
+function luminance([r, g, b]) {
+    const lin = (c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+/**
+ * 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 function contrastColor(background) {
+    const rgb = parseHex(background);
+    if (!rgb)
+        return '#ffffff';
+    // Compare contrast against white vs near-black; whichever is higher wins.
+    const L = luminance(rgb);
+    const contrastWhite = 1.05 / (L + 0.05);
+    const contrastBlack = (L + 0.05) / 0.05;
+    return contrastWhite >= contrastBlack ? '#ffffff' : '#0b0b0c';
+}
+/**
+ * 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 function resolveSchemeVars(scheme) {
+    const surface = sanitizeTokenValue(scheme.surface) ?? FALLBACK.surface;
+    const text = sanitizeTokenValue(scheme.text) ?? FALLBACK.text;
+    const primary = sanitizeTokenValue(scheme.primary) ?? FALLBACK.primary;
+    return {
+        '--paper': surface,
+        '--ink': text,
+        '--accent': primary,
+        '--accent-contrast': contrastColor(primary),
+        // Derived — relative to this scheme's ink/paper.
+        '--paper-raised': 'color-mix(in srgb, var(--ink) 2%, var(--paper))',
+        '--ink-soft': 'color-mix(in srgb, var(--ink) 58%, var(--paper))',
+        '--ink-faint': 'color-mix(in srgb, var(--ink) 38%, var(--paper))',
+        '--rule': 'color-mix(in srgb, var(--ink) 12%, transparent)',
+        '--rule-soft': 'color-mix(in srgb, var(--ink) 7%, transparent)',
+        '--accent-ink': 'color-mix(in srgb, var(--accent) 82%, var(--ink))'
+    };
+}
+/**
+ * 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 function emitSchemeStyles(schemes, scopeSelector) {
+    const rules = [];
+    for (const scheme of schemes) {
+        const vars = resolveSchemeVars(scheme);
+        const decls = Object.entries(vars)
+            .map(([k, v]) => `${k}: ${v};`)
+            .join(' ');
+        const cls = schemeClass(scheme.name);
+        // Match the shell itself when it wears the scheme, and any descendant that does.
+        rules.push(`${scopeSelector}.${cls}, ${scopeSelector} .${cls} { ${decls} }`);
+    }
+    return rules.join('\n');
+}
+/** Read a theme document's `schemes` array, falling back to `defaults` when absent. */
+export function readSchemes(values, defaults) {
+    const doc = {};
+    if (values && typeof values === 'object')
+        Object.assign(doc, values);
+    const raw = doc.schemes;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return defaults;
+    const parsed = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const rec = item;
+        const name = typeof rec.name === 'string' && rec.name.trim() !== '' ? rec.name : 'Scheme';
+        parsed.push({
+            name,
+            surface: typeof rec.surface === 'string' ? rec.surface : FALLBACK.surface,
+            text: typeof rec.text === 'string' ? rec.text : FALLBACK.text,
+            primary: typeof rec.primary === 'string' ? rec.primary : FALLBACK.primary
+        });
+    }
+    return parsed.length > 0 ? parsed : defaults;
+}
+/**
+ * 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 function deriveSchemesField(defaults, group) {
+    return {
+        name: 'schemes',
+        type: 'array',
+        title: 'Color schemes',
+        description: 'Reusable palettes. The first is the site default; sections can opt into any other. Set the background, text, and accent — the rest is derived.',
+        group,
+        initialValue: defaults,
+        of: [
+            {
+                type: 'object',
+                name: 'colorScheme',
+                title: 'Scheme',
+                preview: { select: { title: 'name', subtitle: 'primary' } },
+                fields: [
+                    { name: 'name', type: 'string', title: 'Name' },
+                    { name: 'surface', type: 'string', input: 'color', title: 'Background' },
+                    { name: 'text', type: 'string', input: 'color', title: 'Text' },
+                    { name: 'primary', type: 'string', input: 'color', title: 'Accent' }
+                ]
+            }
+        ]
+    };
+}
+//# sourceMappingURL=schemes.js.map

package/dist/lib/theme/schemes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemes.js","sourceRoot":"","sources":["../../../src/lib/theme/schemes.ts"],"names":[],"mappings":"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"}

package/dist/lib/theme/tokens.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Theme token *types* — the shape of a design-system token.
+ *
+ * cms-core owns the machinery (turn a token list into a schema + scoped CSS); the
+ * consuming app owns the concrete token list, its default colors, and font choices
+ * (that's design opinion, not engine concern). See ./derive.ts and ./css.ts for
+ * the functions that operate on these, and the app's own `theme/tokens.ts` for a
+ * concrete set.
+ */
+/** A curated font choice — the stored `value` resolves to a full CSS `stack`. */
+export interface FontOption {
+    title: string;
+    value: string;
+    stack: string;
+}
+interface BaseToken {
+    /** Field name in the theme schema and the token's identity. */
+    name: string;
+    title: string;
+    description?: string;
+    /** The CSS custom property this token drives, e.g. `--accent`. */
+    cssVar: string;
+    /** Field group in the admin form. */
+    group: string;
+}
+export interface ColorToken extends BaseToken {
+    kind: 'color';
+    default: string;
+}
+export interface FontToken extends BaseToken {
+    kind: 'font';
+    /** The stored `value` of the default option. */
+    default: string;
+    options: FontOption[];
+}
+/** A numeric slider — widths, radii, sizes. Emitted as `${value}${unit}`. */
+export interface RangeToken extends BaseToken {
+    kind: 'range';
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+    /** CSS unit appended to the value, e.g. `'px'`, `'rem'`. Defaults to `''`. */
+    unit?: string;
+}
+/** A fixed-choice dropdown — weights, styles. The stored value is emitted verbatim. */
+export interface SelectToken extends BaseToken {
+    kind: 'select';
+    default: string;
+    options: Array<{
+        title: string;
+        value: string;
+    }>;
+}
+export type ThemeToken = ColorToken | FontToken | RangeToken | SelectToken;
+export {};
+//# sourceMappingURL=tokens.d.ts.map

package/dist/lib/theme/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../src/lib/theme/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iFAAiF;AACjF,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd;AAED,UAAU,SAAS;IAClB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC5C,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAU,SAAQ,SAAS;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC5C,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,uFAAuF;AACvF,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC7C,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC"}

package/dist/lib/theme/tokens.js

@@ -0,0 +1,11 @@
+/**
+ * Theme token *types* — the shape of a design-system token.
+ *
+ * cms-core owns the machinery (turn a token list into a schema + scoped CSS); the
+ * consuming app owns the concrete token list, its default colors, and font choices
+ * (that's design opinion, not engine concern). See ./derive.ts and ./css.ts for
+ * the functions that operate on these, and the app's own `theme/tokens.ts` for a
+ * concrete set.
+ */
+export {};
+//# sourceMappingURL=tokens.js.map

package/dist/lib/theme/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../../src/lib/theme/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/lib/types/auth.d.ts

@@ -1,6 +1,5 @@
 import type { CMSUser } from './user.js';
 import type { OrganizationRole } from './organization.js';
-import type { Capability } from './capabilities.js';
 export interface SessionAuth {
     type: 'session';
     user: CMSUser;
@@ -19,11 +18,13 @@ export interface SessionAuth {
      */
     organizationRole: OrganizationRole | string;
     /**
-     * Capabilities resolved for this session by the auth hook (RolesService).
-     * Present for fully-authenticated sessions. When absent, callers fall
-     * back to built-in seed values — see `resolveCapabilities`.
+     * Capability ids granted to this session, resolved by the auth hook (RolesService).
+     * `string[]`, not `Capability[]`: a role can grant plugin-declared capabilities that
+     * aren't in the built-in `Capability` union. Present for fully-authenticated
+     * sessions; when absent, callers fall back to built-in seed values — see
+     * `resolveCapabilities`.
      */
-    capabilities?: Capability[];
+    capabilities?: string[];
     organizations?: Array<{
         id: string;
         name: string;
@@ -57,12 +58,11 @@ export interface ApiKeyAuth {
      */
     permissions: ('read' | 'write')[];
     /**
-     * Fine-grained capability allowlist for this API key. When present,
-     * overrides the coarse `permissions` mapping — the key can do exactly
-     * what's listed and nothing else. Storage format on the key metadata
-     * matches the Capability union.
+     * Fine-grained capability-id allowlist for this API key. When present, overrides
+     * the coarse `permissions` mapping — the key can do exactly what's listed and
+     * nothing else. `string[]` so keys can be scoped to plugin capabilities too.
      */
-    capabilities?: Capability[];
+    capabilities?: string[];
     organizationId: string;
     environment?: string;
     lastUsedAt?: Date;

package/dist/lib/types/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/lib/types/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,IAAI,CAAC;KAChB,CAAC;IACF,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,gBAAgB,EAAE,gBAAgB,GAAG,MAAM,CAAC;IAC5C;;;;OAIG;IACH,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,KAAK,CAAC;QACrB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAAC;QAChC,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,GAAG,CAAC;KACf,CAAC,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,IAAI,CAAC;KAChB,CAAC;CACF;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,WAAW,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;IAClC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,MAAM,IAAI,GAAG,WAAW,GAAG,kBAAkB,GAAG,UAAU,CAAC;AAYjE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAO5C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAMpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE5C"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/lib/types/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,IAAI,CAAC;KAChB,CAAC;IACF,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,gBAAgB,EAAE,gBAAgB,GAAG,MAAM,CAAC;IAC5C;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,KAAK,CAAC;QACrB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAAC;QAChC,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,GAAG,CAAC;KACf,CAAC,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,IAAI,CAAC;KAChB,CAAC;CACF;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,WAAW,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,MAAM,IAAI,GAAG,WAAW,GAAG,kBAAkB,GAAG,UAAU,CAAC;AAYjE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAO5C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAMpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE5C"}

package/dist/lib/types/capabilities.d.ts

@@ -6,11 +6,44 @@ import type { OrganizationRole } from './organization.js';
  * Append-only: removing or renaming a value silently weakens every call site.
  * If a capability is no longer needed, leave the string and stop granting it.
  */
-export type Capability = 'document.read' | 'document.create' | 'document.update' | 'document.delete' | 'document.publish' | 'document.unpublish' | 'asset.read' | 'asset.upload' | 'asset.delete' | 'member.invite' | 'member.remove' | 'member.changeRole' | 'apiKey.manage' | 'role.manage' | 'org.settings';
+export type Capability = 'document.read' | 'document.create' | 'document.update' | 'document.delete' | 'document.publish' | 'document.unpublish' | 'asset.read' | 'asset.upload' | 'asset.delete' | 'member.invite' | 'member.remove' | 'member.changeRole' | 'apiKey.manage' | 'role.manage' | 'org.settings' | 'plugin.settings.manage';
 /**
  * Enumerate every capability. Useful for owner seeding and validation.
  */
 export declare const ALL_CAPABILITIES: readonly Capability[];
+/**
+ * Metadata for one capability — a registry entry. Turns a bare permission string
+ * into something the roles UI can present (title, help text, grouping). Built-ins
+ * are defined below; plugins add their own via the `aphex/capabilities` part, and
+ * the part resolver merges both into one catalog (`resolver.capabilityCatalog()`).
+ */
+export interface CapabilityDefinition {
+    /** The permission string checked at runtime, e.g. `'document.publish'`. */
+    id: string;
+    /** Human label shown in the roles UI. */
+    title: string;
+    /** One-line explanation shown under the title. */
+    description?: string;
+    /** Group heading in the roles UI, e.g. `'Documents'`. */
+    group?: string;
+}
+/**
+ * Define a capability with metadata. Plugins pass these to the `aphex/capabilities`
+ * part so their permissions appear (and are assignable) in the roles UI.
+ *
+ * @example
+ * defineCapability('forms.export', { title: 'Export submissions', group: 'Forms' })
+ */
+export declare function defineCapability(id: string, meta?: Partial<Omit<CapabilityDefinition, 'id'>>): CapabilityDefinition;
+/** Fallback label for a bare id: `document.publish` → `Publish` (last segment, title-cased). */
+export declare function prettifyCapabilityId(id: string): string;
+/** The built-in capability catalog — metadata for every core capability. */
+export declare const BUILTIN_CAPABILITY_DEFS: readonly CapabilityDefinition[];
+/**
+ * Merge the built-in catalog with extra (plugin) definitions, deduped by id — the
+ * first definition of an id wins, so plugins can't silently redefine a core cap.
+ */
+export declare function mergeCapabilityCatalog(extra?: readonly CapabilityDefinition[]): CapabilityDefinition[];
 /**
  * Built-in role names. These are the guaranteed defaults every org receives.
  * Custom role names are any other string.
@@ -19,9 +52,15 @@ export declare const BUILTIN_ROLE_NAMES: readonly OrganizationRole[];
 /**
  * Seed data for the four built-in roles.
  *
- * This is the **default floor** — the set of capabilities a freshly-created
- * org starts with. Once seeded, rows live in `cms_roles` and can be edited by
- * admins (via future Roles UI). Custom roles live alongside these.
+ * For viewer/editor/admin this is the **default floor** — the set of capabilities
+ * a freshly-created org starts with. Once seeded, rows live in `cms_roles` and can
+ * be edited by admins via the Roles UI; they are never force-updated afterwards,
+ * so a capability added by a later core upgrade is not granted retroactively.
+ *
+ * `owner` is different: it is an **invariant**, not a floor. It is always the whole
+ * of ALL_CAPABILITIES, is rejected by the roles PATCH route, and is reconciled on
+ * every boot (see CMSEngine.reconcileBuiltinRoles) so new capabilities reach orgs
+ * that were seeded before those capabilities existed.
  *
  * Also acts as the defense-in-depth fallback: if a role lookup misses (e.g.
  * a row got deleted out-of-band for a built-in name), the checker falls back
@@ -34,8 +73,10 @@ export declare const BUILTIN_ROLE_SEED: Record<OrganizationRole, {
 /**
  * Idempotently expand a capability list so that any write cap drags in the
  * corresponding read. Used by both the role schema and the API-key schema.
+ * Accepts `string[]` since a granted list may include plugin capability ids; the
+ * built-in read/write implications only touch known core ids and pass others through.
  */
-export declare function normalizeCapabilities(caps: readonly Capability[]): Capability[];
+export declare function normalizeCapabilities(caps: readonly string[]): string[];
 /**
  * A persisted role row (per organization).
  */
@@ -44,7 +85,7 @@ export interface Role {
     organizationId: string;
     name: string;
     description: string | null;
-    capabilities: Capability[];
+    capabilities: string[];
     isBuiltIn: boolean;
     createdAt: Date;
     updatedAt: Date;
@@ -53,7 +94,7 @@ export interface NewRole {
     organizationId: string;
     name: string;
     description?: string | null;
-    capabilities: Capability[];
+    capabilities: string[];
     isBuiltIn?: boolean;
 }
 /**
@@ -69,7 +110,7 @@ export declare function isInstanceRole(auth: Auth): boolean;
  * RolesService. If absent (e.g. legacy call site), falls back to the built-in
  * seed for the org role so behavior remains safe.
  */
-export declare function hasCapability(auth: Auth, capability: Capability): boolean;
+export declare function hasCapability(auth: Auth, capability: Capability | (string & {})): boolean;
 /**
  * Resolve the effective capability set for an Auth.
  *
@@ -80,7 +121,7 @@ export declare function hasCapability(auth: Auth, capability: Capability): boole
  *   4. Session fallback → built-in seed for the org role.
  *   5. Partial session → empty set.
  */
-export declare function resolveCapabilities(auth: Auth): ReadonlySet<Capability>;
+export declare function resolveCapabilities(auth: Auth): ReadonlySet<string>;
 /**
  * Resolve the effective organization role name for an Auth, honoring
  * instance-role overrides. Returns the role name as a string — built-in or

package/dist/lib/types/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/lib/types/capabilities.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAEnB,eAAe,GACf,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,oBAAoB,GAEpB,YAAY,GACZ,cAAc,GACd,cAAc,GAEd,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,eAAe,GACf,aAAa,GACb,cAAc,CAAC;AAMlB;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,UAAU,EAgBxC,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAKzD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CACrC,gBAAgB,EAChB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CA4C5D,CAAC;AAeF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,EAAE,CAK/E;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,EAAE,CAQtE;AAWD,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAEzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,CAAC,UAAU,CAAC,CAoCvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAInE;AAID;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,0EAA0E;IAC1E,YAAY,EAAE,UAAU,EAAE,CAAC;CAC3B"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/lib/types/capabilities.ts"],"names":[],"mappings":"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"}