@actuate-media/cms-core 0.35.0 → 0.36.0

package/dist/appearance/color.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Color parsing + WCAG contrast.
+ *
+ * Accent colors are stored either as a preset name (resolved elsewhere) or as
+ * a raw CSS color string. To validate contrast we need a real luminance, so we
+ * parse both `#rgb`/`#rrggbb` and `oklch(L C H)` into LINEAR sRGB and apply the
+ * WCAG relative-luminance + contrast-ratio formulas. Linear RGB is exactly what
+ * the luminance formula wants, so the hex path linearizes gamma sRGB and the
+ * oklch path (via OKLab→linear sRGB, per Björn Ottosson) is already linear.
+ */
+export interface LinearRgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/** Parse a supported color string (`#hex` or `oklch(...)`) into linear sRGB. */
+export declare function parseColorToLinear(input: string): LinearRgb | null;
+/** WCAG relative luminance from linear sRGB. */
+export declare function relativeLuminance(rgb: LinearRgb): number;
+/** WCAG contrast ratio (1..21) between two colors. Returns 0 if unparseable. */
+export declare function contrastRatio(a: string, b: string): number;
+/** True when the color string is a parseable `#hex` or `oklch(...)` value. */
+export declare function isParseableColor(input: string): boolean;
+//# sourceMappingURL=color.d.ts.map

package/dist/appearance/color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/appearance/color.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAuDD,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAMlE;AAED,gDAAgD;AAChD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAExD;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAS1D;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvD"}

package/dist/appearance/color.js

@@ -0,0 +1,90 @@
+/**
+ * Color parsing + WCAG contrast.
+ *
+ * Accent colors are stored either as a preset name (resolved elsewhere) or as
+ * a raw CSS color string. To validate contrast we need a real luminance, so we
+ * parse both `#rgb`/`#rrggbb` and `oklch(L C H)` into LINEAR sRGB and apply the
+ * WCAG relative-luminance + contrast-ratio formulas. Linear RGB is exactly what
+ * the luminance formula wants, so the hex path linearizes gamma sRGB and the
+ * oklch path (via OKLab→linear sRGB, per Björn Ottosson) is already linear.
+ */
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/** sRGB gamma channel (0..1) → linear (0..1). */
+function srgbToLinear(c) {
+    return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+function parseHex(input) {
+    let hex = input.trim().replace(/^#/, '');
+    if (hex.length === 3) {
+        hex = hex
+            .split('')
+            .map((ch) => ch + ch)
+            .join('');
+    }
+    if (!/^[0-9a-fA-F]{6}$/.test(hex))
+        return null;
+    const r = parseInt(hex.slice(0, 2), 16) / 255;
+    const g = parseInt(hex.slice(2, 4), 16) / 255;
+    const b = parseInt(hex.slice(4, 6), 16) / 255;
+    return { r: srgbToLinear(r), g: srgbToLinear(g), b: srgbToLinear(b) };
+}
+/** Parse `oklch(L C H)` (L 0..1 or 0%..100%, C ≥ 0, H degrees) → linear sRGB. */
+function parseOklch(input) {
+    const m = input.trim().match(/^oklch\(\s*([\d.]+%?)\s+([\d.]+)\s+([\d.]+)\s*\)$/i);
+    if (!m)
+        return null;
+    let L = parseFloat(m[1]);
+    if (m[1].endsWith('%'))
+        L /= 100;
+    const C = parseFloat(m[2]);
+    const Hdeg = parseFloat(m[3]);
+    if (!Number.isFinite(L) || !Number.isFinite(C) || !Number.isFinite(Hdeg))
+        return null;
+    const h = (Hdeg * Math.PI) / 180;
+    const a = C * Math.cos(h);
+    const b = C * Math.sin(h);
+    const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+    const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+    const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+    const l = l_ * l_ * l_;
+    const mm = m_ * m_ * m_;
+    const s = s_ * s_ * s_;
+    const r = 4.0767416621 * l - 3.3077115913 * mm + 0.2309699292 * s;
+    const g = -1.2684380046 * l + 2.6097574011 * mm - 0.3413193965 * s;
+    const bl = -0.0041960863 * l - 0.7034186147 * mm + 1.707614701 * s;
+    return { r: clamp01(r), g: clamp01(g), b: clamp01(bl) };
+}
+/** Parse a supported color string (`#hex` or `oklch(...)`) into linear sRGB. */
+export function parseColorToLinear(input) {
+    if (!input)
+        return null;
+    const trimmed = input.trim();
+    if (trimmed.startsWith('#'))
+        return parseHex(trimmed);
+    if (/^oklch\(/i.test(trimmed))
+        return parseOklch(trimmed);
+    return null;
+}
+/** WCAG relative luminance from linear sRGB. */
+export function relativeLuminance(rgb) {
+    return 0.2126 * rgb.r + 0.7152 * rgb.g + 0.0722 * rgb.b;
+}
+/** WCAG contrast ratio (1..21) between two colors. Returns 0 if unparseable. */
+export function contrastRatio(a, b) {
+    const ca = parseColorToLinear(a);
+    const cb = parseColorToLinear(b);
+    if (!ca || !cb)
+        return 0;
+    const la = relativeLuminance(ca);
+    const lb = relativeLuminance(cb);
+    const lighter = Math.max(la, lb);
+    const darker = Math.min(la, lb);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/** True when the color string is a parseable `#hex` or `oklch(...)` value. */
+export function isParseableColor(input) {
+    return parseColorToLinear(input) !== null;
+}
+//# sourceMappingURL=color.js.map

package/dist/appearance/color.js.map

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

package/dist/appearance/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Appearance + brand module barrel.
+ *
+ * Single source of truth for admin theme preferences and brand assets, stored
+ * on the `settings` global and consumed by the admin shell, the public
+ * frontend (`GET /public/brand`), and Next.js favicon metadata.
+ */
+export type { ColorMode, SidebarDensity, AccentColorName, LogoShape, AdminBrandingMode, BrandAssetRole, AppearanceSettings, BrandSettings, BrandAssetMetadata, ResolvedLogo, ResolvedAdminBrand, ResolvedPublicBrand, FaviconMetadata, BrandAssetLike, } from './types.js';
+export { classifyLogoShape, logoShapeWarning } from './logo-shape.js';
+export { parseColorToLinear, relativeLuminance, contrastRatio, isParseableColor, type LinearRgb, } from './color.js';
+export { ACCENT_PRESETS, ACCENT_PRESET_LIST, MIN_ACCENT_CONTRAST, isAccentPreset, validateAccentColor, generateAdminThemeTokens, accentTokensToCssVars, type AccentTokens, type AccentPreset, type AccentValidation, } from './theme-tokens.js';
+export { SETTINGS_GLOBAL_COLLECTION, DEFAULT_APPEARANCE, DEFAULT_BRAND, siteInitials, resolveAdminBrand, resolvePublicBrand, getFaviconMetadata, parseAppearance, parseBrand, brandAssetIds, gatherBrandAssets, getAppearanceSettings, getBrandSettings, resolveBrand, type ResolvedBrandBundle, } from './resolve.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/appearance/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,YAAY,EACV,SAAS,EACT,cAAc,EACd,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAErE,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,KAAK,SAAS,GACf,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACZ,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAA"}

package/dist/appearance/index.js

@@ -0,0 +1,5 @@
+export { classifyLogoShape, logoShapeWarning } from './logo-shape.js';
+export { parseColorToLinear, relativeLuminance, contrastRatio, isParseableColor, } from './color.js';
+export { ACCENT_PRESETS, ACCENT_PRESET_LIST, MIN_ACCENT_CONTRAST, isAccentPreset, validateAccentColor, generateAdminThemeTokens, accentTokensToCssVars, } from './theme-tokens.js';
+export { SETTINGS_GLOBAL_COLLECTION, DEFAULT_APPEARANCE, DEFAULT_BRAND, siteInitials, resolveAdminBrand, resolvePublicBrand, getFaviconMetadata, parseAppearance, parseBrand, brandAssetIds, gatherBrandAssets, getAppearanceSettings, getBrandSettings, resolveBrand, } from './resolve.js';
+//# sourceMappingURL=index.js.map

package/dist/appearance/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/appearance/index.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAErE,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,GAEjB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,GAItB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,GAEb,MAAM,cAAc,CAAA"}

package/dist/appearance/logo-shape.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Logo shape classification.
+ *
+ * Pure, dimension-based classification used to (a) pick the right rendering
+ * slot for an uploaded asset and (b) surface non-blocking warnings when an
+ * asset is uploaded into a role it doesn't suit (e.g. a square mark dropped
+ * into the full-width "Primary Logo" slot). We NEVER stretch or crop — these
+ * are advisory only; rendering always uses object-fit: contain.
+ */
+import type { BrandAssetRole, LogoShape } from './types.js';
+/**
+ * Classify a logo by aspect ratio (width / height):
+ *   - square:     0.8 ≤ ratio ≤ 1.25  (marks, favicons, app icons)
+ *   - horizontal: ratio > 1.8         (headers, full sidebar)
+ *   - vertical:   ratio < 0.8         (rarely fits headers/sidebars)
+ *   - neutral:    everything in between
+ *   - unknown:    missing/invalid dimensions
+ */
+export declare function classifyLogoShape(width: number | null | undefined, height: number | null | undefined): LogoShape;
+/**
+ * Advisory warning when an asset's shape doesn't suit its role. Returns null
+ * when the shape is fine (or unknown — we don't nag about SVGs without
+ * intrinsic dimensions).
+ */
+export declare function logoShapeWarning(role: BrandAssetRole, shape: LogoShape): string | null;
+//# sourceMappingURL=logo-shape.d.ts.map

package/dist/appearance/logo-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logo-shape.d.ts","sourceRoot":"","sources":["../../src/appearance/logo-shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3D;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAChC,SAAS,CAOX;AAiBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAwBtF"}

package/dist/appearance/logo-shape.js

@@ -0,0 +1,62 @@
+/**
+ * Classify a logo by aspect ratio (width / height):
+ *   - square:     0.8 ≤ ratio ≤ 1.25  (marks, favicons, app icons)
+ *   - horizontal: ratio > 1.8         (headers, full sidebar)
+ *   - vertical:   ratio < 0.8         (rarely fits headers/sidebars)
+ *   - neutral:    everything in between
+ *   - unknown:    missing/invalid dimensions
+ */
+export function classifyLogoShape(width, height) {
+    if (!width || !height || width <= 0 || height <= 0)
+        return 'unknown';
+    const ratio = width / height;
+    if (ratio >= 0.8 && ratio <= 1.25)
+        return 'square';
+    if (ratio > 1.8)
+        return 'horizontal';
+    if (ratio < 0.8)
+        return 'vertical';
+    return 'neutral';
+}
+/** Roles that want a square asset (mark/favicon/app icon). */
+const SQUARE_ROLES = new Set([
+    'publicLogoMark',
+    'adminLogoMark',
+    'faviconSource',
+]);
+/** Roles that want a wide lockup (header / full sidebar). */
+const WIDE_ROLES = new Set([
+    'publicPrimaryLogo',
+    'adminPrimaryLogo',
+    'publicDarkLogo',
+    'adminDarkLogo',
+]);
+/**
+ * Advisory warning when an asset's shape doesn't suit its role. Returns null
+ * when the shape is fine (or unknown — we don't nag about SVGs without
+ * intrinsic dimensions).
+ */
+export function logoShapeWarning(role, shape) {
+    if (shape === 'unknown')
+        return null;
+    if (WIDE_ROLES.has(role)) {
+        if (shape === 'square') {
+            return 'This looks like a square mark. It will work well for icons and collapsed navigation. For full-width headers, upload a horizontal primary logo or use mark + site title.';
+        }
+        if (shape === 'vertical') {
+            return 'Vertical logos may not fit well in headers or sidebars. Consider uploading a horizontal logo and a square mark.';
+        }
+    }
+    if (SQUARE_ROLES.has(role)) {
+        if (shape === 'horizontal') {
+            return role === 'faviconSource'
+                ? 'This favicon source is not square. A square image works better for favicons and app icons and avoids cropping.'
+                : 'This looks like a horizontal logo. A square mark works better for favicons, collapsed sidebar, and app icons.';
+        }
+        if (shape === 'vertical') {
+            return 'Vertical images do not crop cleanly to a square icon. Upload a square mark for the best result.';
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=logo-shape.js.map

package/dist/appearance/logo-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logo-shape.js","sourceRoot":"","sources":["../../src/appearance/logo-shape.ts"],"names":[],"mappings":"AAWA;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAgC,EAChC,MAAiC;IAEjC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,SAAS,CAAA;IACpE,MAAM,KAAK,GAAG,KAAK,GAAG,MAAM,CAAA;IAC5B,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,QAAQ,CAAA;IAClD,IAAI,KAAK,GAAG,GAAG;QAAE,OAAO,YAAY,CAAA;IACpC,IAAI,KAAK,GAAG,GAAG;QAAE,OAAO,UAAU,CAAA;IAClC,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,8DAA8D;AAC9D,MAAM,YAAY,GAAgC,IAAI,GAAG,CAAC;IACxD,gBAAgB;IAChB,eAAe;IACf,eAAe;CAChB,CAAC,CAAA;AAEF,6DAA6D;AAC7D,MAAM,UAAU,GAAgC,IAAI,GAAG,CAAC;IACtD,mBAAmB;IACnB,kBAAkB;IAClB,gBAAgB;IAChB,eAAe;CAChB,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAoB,EAAE,KAAgB;IACrE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IAEpC,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,yKAAyK,CAAA;QAClL,CAAC;QACD,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;YACzB,OAAO,iHAAiH,CAAA;QAC1H,CAAC;IACH,CAAC;IAED,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;YAC3B,OAAO,IAAI,KAAK,eAAe;gBAC7B,CAAC,CAAC,gHAAgH;gBAClH,CAAC,CAAC,+GAA+G,CAAA;QACrH,CAAC;QACD,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;YACzB,OAAO,iGAAiG,CAAA;QAC1G,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/appearance/resolve.d.ts

@@ -0,0 +1,46 @@
+import type { AppearanceSettings, BrandAssetLike, BrandSettings, FaviconMetadata, ResolvedAdminBrand, ResolvedPublicBrand } from './types.js';
+export declare const SETTINGS_GLOBAL_COLLECTION = "settings";
+export declare const DEFAULT_APPEARANCE: AppearanceSettings;
+export declare const DEFAULT_BRAND: BrandSettings;
+/** Up to two uppercase initials derived from the site title. */
+export declare function siteInitials(siteTitle: string | null | undefined): string;
+/**
+ * Resolve the admin sidebar brand with the spec's fallback chains.
+ *
+ * inheritPublicBrand → admin uses the public assets.
+ * customAdminBrand   → admin-specific assets win, falling back to public.
+ * Collapsed mark falls back to favicon source, then site initials.
+ */
+export declare function resolveAdminBrand(brand: BrandSettings, assets: Map<string, BrandAssetLike>, siteTitle: string | null | undefined): ResolvedAdminBrand;
+/** Resolve the public site brand (header/footer/nav). */
+export declare function resolvePublicBrand(brand: BrandSettings, assets: Map<string, BrandAssetLike>, siteTitle: string | null | undefined): ResolvedPublicBrand;
+/**
+ * Favicon metadata for Next.js `metadata.icons`. Appends a cache-busting
+ * `?v=` token derived from the brand's `updatedAt` so changing the favicon
+ * invalidates the browser/CDN copy.
+ */
+export declare function getFaviconMetadata(brand: BrandSettings, assets: Map<string, BrandAssetLike>): FaviconMetadata;
+export declare function parseAppearance(blob: Record<string, unknown>): AppearanceSettings;
+export declare function parseBrand(blob: Record<string, unknown>): BrandSettings;
+/** Collect every asset ID referenced by a brand settings record. */
+export declare function brandAssetIds(brand: BrandSettings): string[];
+/** Fetch the referenced media rows and key them by asset ID. */
+export declare function gatherBrandAssets(db: unknown, ids: string[]): Promise<Map<string, BrandAssetLike>>;
+export declare function getAppearanceSettings(db: unknown): Promise<AppearanceSettings>;
+export declare function getBrandSettings(db: unknown): Promise<BrandSettings>;
+export interface ResolvedBrandBundle {
+    brand: BrandSettings;
+    admin: ResolvedAdminBrand;
+    public: ResolvedPublicBrand;
+    favicon: FaviconMetadata;
+    /** Every referenced asset, keyed for direct per-field editor previews. */
+    assets: BrandAssetLike[];
+    /** Site title used for alt text + initials (from General Settings). */
+    siteTitle: string | null;
+}
+/**
+ * One-shot resolver used by the public brand endpoint and the admin shell:
+ * read the settings blob, gather referenced assets, and resolve every view.
+ */
+export declare function resolveBrand(db: unknown, siteTitle: string | null | undefined): Promise<ResolvedBrandBundle>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/appearance/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/appearance/resolve.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,eAAe,EACf,kBAAkB,EAElB,mBAAmB,EACpB,MAAM,YAAY,CAAA;AAEnB,eAAO,MAAM,0BAA0B,aAAa,CAAA;AAEpD,eAAO,MAAM,kBAAkB,EAAE,kBAMhC,CAAA;AAED,eAAO,MAAM,aAAa,EAAE,aAE3B,CAAA;AAED,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAQzE;AAiBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EACnC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACnC,kBAAkB,CA0BpB;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EACnC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACnC,mBAAmB,CASrB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GAClC,eAAe,CAajB;AAuBD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,kBAAkB,CAWjF;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAGvE;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,CAY5D;AAqBD,gEAAgE;AAChE,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,OAAO,EACX,GAAG,EAAE,MAAM,EAAE,GACZ,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAWtC;AAED,wBAAsB,qBAAqB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAEpF;AAED,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAE1E;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,aAAa,CAAA;IACpB,KAAK,EAAE,kBAAkB,CAAA;IACzB,MAAM,EAAE,mBAAmB,CAAA;IAC3B,OAAO,EAAE,eAAe,CAAA;IACxB,0EAA0E;IAC1E,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,uEAAuE;IACvE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,OAAO,EACX,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAa9B"}

package/dist/appearance/resolve.js

@@ -0,0 +1,208 @@
+/**
+ * Brand resolution.
+ *
+ * Turns stored {@link BrandSettings} (asset IDs) + Media Center rows into the
+ * concrete logo/favicon URLs the admin shell, public site, and Next.js
+ * metadata consume. Resolution encodes the fallback chains from the spec so
+ * callers never hardcode logo paths and always degrade gracefully to site
+ * initials.
+ *
+ * The pure functions (`resolveAdminBrand`, `resolvePublicBrand`,
+ * `getFaviconMetadata`, `siteInitials`) take an already-fetched asset map and
+ * are unit-tested; the async gatherers read the `settings` global + media rows.
+ */
+import { classifyLogoShape } from './logo-shape.js';
+export const SETTINGS_GLOBAL_COLLECTION = 'settings';
+export const DEFAULT_APPEARANCE = {
+    adminColorModeDefault: 'system',
+    adminAccentColor: 'purple',
+    sidebarDensity: 'default',
+    contentFont: 'DM Sans',
+    reduceMotion: false,
+};
+export const DEFAULT_BRAND = {
+    mode: 'inheritPublicBrand',
+};
+/** Up to two uppercase initials derived from the site title. */
+export function siteInitials(siteTitle) {
+    const cleaned = (siteTitle ?? '').trim();
+    if (!cleaned)
+        return 'A';
+    const words = cleaned.split(/\s+/).filter(Boolean);
+    if (words.length === 1) {
+        return words[0].slice(0, 2).toUpperCase();
+    }
+    return (words[0][0] + words[1][0]).toUpperCase();
+}
+function toResolvedLogo(asset, alt) {
+    if (!asset || !asset.publicUrl)
+        return null;
+    return {
+        url: asset.publicUrl,
+        alt,
+        shape: classifyLogoShape(asset.width ?? undefined, asset.height ?? undefined),
+        width: asset.width ?? undefined,
+        height: asset.height ?? undefined,
+    };
+}
+function altFor(brand, siteTitle) {
+    return brand.defaultLogoAltText?.trim() || (siteTitle ?? '').trim() || 'Logo';
+}
+/**
+ * Resolve the admin sidebar brand with the spec's fallback chains.
+ *
+ * inheritPublicBrand → admin uses the public assets.
+ * customAdminBrand   → admin-specific assets win, falling back to public.
+ * Collapsed mark falls back to favicon source, then site initials.
+ */
+export function resolveAdminBrand(brand, assets, siteTitle) {
+    const alt = altFor(brand, siteTitle);
+    const get = (id) => (id ? assets.get(id) : undefined);
+    const custom = brand.mode === 'customAdminBrand';
+    const primaryAsset = custom
+        ? (get(brand.adminPrimaryLogoAssetId) ?? get(brand.publicPrimaryLogoAssetId))
+        : get(brand.publicPrimaryLogoAssetId);
+    const markAsset = custom
+        ? (get(brand.adminLogoMarkAssetId) ??
+            get(brand.publicLogoMarkAssetId) ??
+            get(brand.faviconSourceAssetId))
+        : (get(brand.publicLogoMarkAssetId) ?? get(brand.faviconSourceAssetId));
+    const darkAsset = custom
+        ? (get(brand.adminDarkLogoAssetId) ?? get(brand.publicDarkLogoAssetId))
+        : get(brand.publicDarkLogoAssetId);
+    return {
+        primary: toResolvedLogo(primaryAsset, alt),
+        mark: toResolvedLogo(markAsset, alt),
+        dark: toResolvedLogo(darkAsset, alt),
+        initials: siteInitials(siteTitle),
+        inherited: !custom,
+    };
+}
+/** Resolve the public site brand (header/footer/nav). */
+export function resolvePublicBrand(brand, assets, siteTitle) {
+    const alt = altFor(brand, siteTitle);
+    const get = (id) => (id ? assets.get(id) : undefined);
+    return {
+        primary: toResolvedLogo(get(brand.publicPrimaryLogoAssetId), alt),
+        mark: toResolvedLogo(get(brand.publicLogoMarkAssetId) ?? get(brand.faviconSourceAssetId), alt),
+        dark: toResolvedLogo(get(brand.publicDarkLogoAssetId), alt),
+        initials: siteInitials(siteTitle),
+    };
+}
+/**
+ * Favicon metadata for Next.js `metadata.icons`. Appends a cache-busting
+ * `?v=` token derived from the brand's `updatedAt` so changing the favicon
+ * invalidates the browser/CDN copy.
+ */
+export function getFaviconMetadata(brand, assets) {
+    const source = brand.faviconSourceAssetId ? assets.get(brand.faviconSourceAssetId) : undefined;
+    const generated = (brand.generatedFaviconAssetIds ?? [])
+        .map((id) => assets.get(id)?.publicUrl)
+        .filter((u) => Boolean(u));
+    if (!source || !source.publicUrl) {
+        return { icon: null, apple: null, type: null, generated };
+    }
+    const version = brand.updatedAt ? Date.parse(brand.updatedAt) : null;
+    const bust = version && !Number.isNaN(version) ? `?v=${version}` : '';
+    const url = `${source.publicUrl}${bust}`;
+    return { icon: url, apple: url, type: source.mimeType || null, generated };
+}
+async function readSettingsBlob(db) {
+    const d = db;
+    if (!d?.document?.findFirst)
+        return {};
+    const doc = await d.document.findFirst({
+        where: { collection: SETTINGS_GLOBAL_COLLECTION, deletedAt: null },
+    });
+    const data = doc?.data;
+    return data && typeof data === 'object' ? data : {};
+}
+export function parseAppearance(blob) {
+    const a = blob.appearance ?? {};
+    return {
+        adminColorModeDefault: a.adminColorModeDefault ?? DEFAULT_APPEARANCE.adminColorModeDefault,
+        adminAccentColor: a.adminAccentColor ?? DEFAULT_APPEARANCE.adminAccentColor,
+        sidebarDensity: a.sidebarDensity ?? DEFAULT_APPEARANCE.sidebarDensity,
+        contentFont: a.contentFont ?? DEFAULT_APPEARANCE.contentFont,
+        reduceMotion: a.reduceMotion ?? DEFAULT_APPEARANCE.reduceMotion,
+        updatedAt: a.updatedAt,
+        updatedBy: a.updatedBy,
+    };
+}
+export function parseBrand(blob) {
+    const b = blob.brand ?? {};
+    return { ...DEFAULT_BRAND, ...b };
+}
+/** Collect every asset ID referenced by a brand settings record. */
+export function brandAssetIds(brand) {
+    const ids = [
+        brand.publicPrimaryLogoAssetId,
+        brand.publicLogoMarkAssetId,
+        brand.publicDarkLogoAssetId,
+        brand.adminPrimaryLogoAssetId,
+        brand.adminLogoMarkAssetId,
+        brand.adminDarkLogoAssetId,
+        brand.faviconSourceAssetId,
+        ...(brand.generatedFaviconAssetIds ?? []),
+    ].filter((id) => Boolean(id));
+    return Array.from(new Set(ids));
+}
+function mediaRowToAsset(row) {
+    const id = typeof row.id === 'string' ? row.id : null;
+    if (!id)
+        return null;
+    const publicUrl = (typeof row.publicUrl === 'string' && row.publicUrl) ||
+        (typeof row.storageKey === 'string' && /^(https?:\/\/|\/)/.test(row.storageKey)
+            ? row.storageKey
+            : '');
+    return {
+        id,
+        publicUrl: publicUrl || '',
+        mimeType: typeof row.mimeType === 'string' ? row.mimeType : '',
+        width: typeof row.width === 'number' ? row.width : null,
+        height: typeof row.height === 'number' ? row.height : null,
+        fileName: typeof row.filename === 'string' ? row.filename : null,
+        sizeBytes: typeof row.fileSize === 'number' ? row.fileSize : null,
+    };
+}
+/** Fetch the referenced media rows and key them by asset ID. */
+export async function gatherBrandAssets(db, ids) {
+    const map = new Map();
+    if (ids.length === 0)
+        return map;
+    const d = db;
+    if (!d?.media?.findMany)
+        return map;
+    const rows = await d.media.findMany({ where: { id: { in: ids }, deletedAt: null } });
+    for (const row of rows) {
+        const asset = mediaRowToAsset(row);
+        if (asset)
+            map.set(asset.id, asset);
+    }
+    return map;
+}
+export async function getAppearanceSettings(db) {
+    return parseAppearance(await readSettingsBlob(db));
+}
+export async function getBrandSettings(db) {
+    return parseBrand(await readSettingsBlob(db));
+}
+/**
+ * One-shot resolver used by the public brand endpoint and the admin shell:
+ * read the settings blob, gather referenced assets, and resolve every view.
+ */
+export async function resolveBrand(db, siteTitle) {
+    const blob = await readSettingsBlob(db);
+    const brand = parseBrand(blob);
+    const title = siteTitle ?? (typeof blob.siteTitle === 'string' ? blob.siteTitle : null);
+    const assets = await gatherBrandAssets(db, brandAssetIds(brand));
+    return {
+        brand,
+        admin: resolveAdminBrand(brand, assets, title),
+        public: resolvePublicBrand(brand, assets, title),
+        favicon: getFaviconMetadata(brand, assets),
+        assets: Array.from(assets.values()),
+        siteTitle: title ?? null,
+    };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/appearance/resolve.js.map

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

package/dist/appearance/theme-tokens.d.ts

@@ -0,0 +1,50 @@
+import type { AccentColorName, AppearanceSettings } from './types.js';
+export interface AccentTokens {
+    brand: string;
+    brandForeground: string;
+    primary: string;
+    primaryForeground: string;
+    sidebarPrimary: string;
+    ring: string;
+}
+export interface AccentPreset {
+    name: AccentColorName;
+    label: string;
+    /** Swatch color for the picker (the light-mode brand value). */
+    swatch: string;
+    light: AccentTokens;
+    dark: AccentTokens;
+}
+/**
+ * Curated accent presets. Light/dark brand values mirror the existing
+ * `theme.css` violet so "purple" is a visual no-op; the others are tuned to the
+ * same lightness/chroma envelope so they read as text on cards and as solid
+ * fills, and pass the >=3:1 UI-contrast bar against their foreground.
+ */
+export declare const ACCENT_PRESETS: Record<AccentColorName, AccentPreset>;
+export declare const ACCENT_PRESET_LIST: AccentPreset[];
+/** Minimum WCAG contrast for a primary fill vs its foreground (UI/large text). */
+export declare const MIN_ACCENT_CONTRAST = 3;
+export declare function isAccentPreset(value: string): value is AccentColorName;
+export interface AccentValidation {
+    valid: boolean;
+    /** Computed contrast of the accent fill against white (light mode). */
+    contrast: number;
+    reason?: string;
+}
+/**
+ * Validate an accent value. Presets are always valid (pre-vetted). A custom
+ * string must parse AND clear {@link MIN_ACCENT_CONTRAST} against white so
+ * white text on the primary button stays legible.
+ */
+export declare function validateAccentColor(value: string): AccentValidation;
+/**
+ * Resolve the accent tokens for a settings value + resolved color mode.
+ * Falls back to the purple preset when the stored value is a custom color
+ * (custom colors only set `--brand`/`--primary` directly; we keep purple's
+ * foreground/ring envelope). Unknown names fall back to purple.
+ */
+export declare function generateAdminThemeTokens(settings: Pick<AppearanceSettings, 'adminAccentColor'>, resolvedMode: 'light' | 'dark'): AccentTokens;
+/** Map accent tokens to the CSS custom properties the theme consumes. */
+export declare function accentTokensToCssVars(tokens: AccentTokens): Record<string, string>;
+//# sourceMappingURL=theme-tokens.d.ts.map

package/dist/appearance/theme-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-tokens.d.ts","sourceRoot":"","sources":["../../src/appearance/theme-tokens.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAErE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,eAAe,EAAE,MAAM,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,iBAAiB,EAAE,MAAM,CAAA;IACzB,cAAc,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,eAAe,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,YAAY,CAAA;IACnB,IAAI,EAAE,YAAY,CAAA;CACnB;AAKD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,eAAe,EAAE,YAAY,CA0GhE,CAAA;AAED,eAAO,MAAM,kBAAkB,EAAE,YAAY,EAAkC,CAAA;AAE/E,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,eAAe,CAEtE;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAA;IACd,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAiBnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,EACtD,YAAY,EAAE,OAAO,GAAG,MAAM,GAC7B,YAAY,CAmBd;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUlF"}