waybetter 0.1.0 → 0.6.0

package/dist/runtime/themeDecor.d.ts

@@ -0,0 +1,73 @@
+import { type ColorRole, type RoleColors } from './themeComponents.ts';
+export declare const DIVIDER_STYLES: readonly ["none", "hairline", "solid", "dashed", "dotted", "double"];
+export declare const CHROME_KINDS: readonly ["none", "titlebar", "masthead", "prompt"];
+export declare const RING_STYLES: readonly ["solid", "dashed", "dotted", "double"];
+export declare const MOTION_CURVES: readonly ["standard", "snappy", "spring", "linear", "steps"];
+export declare const LINK_UNDERLINES: readonly ["always", "hover", "never"];
+export type ThemeDecor = {
+    dividers?: {
+        style: typeof DIVIDER_STYLES[number];
+        color?: ColorRole;
+        width?: number;
+    };
+    /** A drawn frame around the main column: a window title bar, a newspaper masthead, a terminal prompt. `title` is plain text. */
+    chrome?: {
+        kind: typeof CHROME_KINDS[number];
+        title?: string;
+    };
+    focusRing?: {
+        width?: number;
+        style?: typeof RING_STYLES[number];
+        color?: ColorRole;
+        offset?: number;
+    };
+    selection?: {
+        fill: ColorRole;
+        text: ColorRole;
+    };
+    scrollbar?: {
+        width?: 'auto' | 'thin';
+        thumb?: ColorRole;
+        track?: ColorRole;
+        style?: 'flat' | 'classic';
+    };
+    links?: {
+        underline: typeof LINK_UNDERLINES[number];
+    };
+    motion?: {
+        duration?: number;
+        curve?: typeof MOTION_CURVES[number];
+        press?: number;
+    };
+};
+/** Text a theme may put into a drawn bar: letters, digits, spaces and a little punctuation; it is written into a CSS string. */
+export declare const chromeTitle: (value: unknown) => string;
+/** The `decor` group from JSON. Null when nothing valid is left. */
+export declare function sanitizeDecor(value: unknown): ThemeDecor | null;
+/** Where a site's decoration goes. Every entry is optional: a site without it draws nothing for that key. */
+export type DecorTargets<Context> = {
+    /** Rows whose bottom edge is the divider between items (a site's list cells). */
+    divider?: string;
+    /** Links inside running text. */
+    link?: string;
+    /** What takes keyboard focus. */
+    focusable?: string;
+    /** What moves with `motion` (buttons, links, rows). */
+    moving?: string;
+    /** What a press shrinks. */
+    pressable?: string;
+    /** The scrollable roots. */
+    scroller?: string;
+    /** The site's drawing of each chrome kind. */
+    chrome?: Partial<Record<Exclude<typeof CHROME_KINDS[number], 'none'>, (title: string, ctx: Context) => string>>;
+};
+/**
+ * CSS for a theme's decoration. A focus ring is always drawn when the theme names one (at least 2px
+ * and 3:1 on the page's surfaces: the color is swapped for a visible one otherwise); motion only
+ * for people who have not asked for less of it.
+ */
+export declare function compileDecor<Context extends {
+    colors: RoleColors;
+}>(decor: ThemeDecor, targets: DecorTargets<Context>, ctx: Context): string[];
+/** A theme's text as a CSS string literal (for `content`): the allow-list of `chromeTitle` plus escaping of what could end the string. */
+export declare const cssString: (value: string) => string;

package/dist/runtime/themeDecor.js

@@ -0,0 +1,131 @@
+// Decoration: what a theme draws between and around the components: divider lines, a title bar or a
+// masthead, the focus ring, selection, scrollbars, link underlines, the feel of motion. Fixed words
+// and clamped numbers, colors by role. Where the lines and bars go is the site's (its decor targets).
+// Pure.
+import { contrastRatio } from "./themeApi.js";
+import { COLOR_ROLES } from "./themeComponents.js";
+export const DIVIDER_STYLES = ['none', 'hairline', 'solid', 'dashed', 'dotted', 'double'];
+export const CHROME_KINDS = ['none', 'titlebar', 'masthead', 'prompt'];
+export const RING_STYLES = ['solid', 'dashed', 'dotted', 'double'];
+export const MOTION_CURVES = ['standard', 'snappy', 'spring', 'linear', 'steps'];
+export const LINK_UNDERLINES = ['always', 'hover', 'never'];
+const obj = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const oneOf = (value, options) => options.includes(value) ? value : undefined;
+const num = (value, min, max) => typeof value === 'number' && Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : undefined;
+const role = (value) => oneOf(value, COLOR_ROLES);
+/** Text a theme may put into a drawn bar: letters, digits, spaces and a little punctuation; it is written into a CSS string. */
+export const chromeTitle = (value) => typeof value === 'string' ? value.replace(/[^\p{L}\p{N} .,:!?&+\-_/#@*~()[\]|>$]/gu, '').replace(/&/g, '+').trim().slice(0, 24) : '';
+/** The `decor` group from JSON. Null when nothing valid is left. */
+export function sanitizeDecor(value) {
+    const source = obj(value);
+    const out = {};
+    const dividers = obj(source.dividers), dividerStyle = oneOf(dividers.style, DIVIDER_STYLES);
+    if (dividerStyle) {
+        const color = role(dividers.color), width = num(dividers.width, 0, 3);
+        out.dividers = { style: dividerStyle, ...(color ? { color } : {}), ...(width !== undefined ? { width: +width.toFixed(1) } : {}) };
+    }
+    const chrome = obj(source.chrome), kind = oneOf(chrome.kind, CHROME_KINDS);
+    if (kind && kind !== 'none') {
+        const title = chromeTitle(chrome.title);
+        out.chrome = { kind, ...(title ? { title } : {}) };
+    }
+    const ring = obj(source.focusRing);
+    if (Object.keys(ring).length) {
+        const width = num(ring.width, 2, 4), style = oneOf(ring.style, RING_STYLES), color = role(ring.color), offset = num(ring.offset, 0, 4);
+        const focusRing = { ...(width !== undefined ? { width: Math.round(width) } : {}), ...(style ? { style } : {}), ...(color ? { color } : {}), ...(offset !== undefined ? { offset: Math.round(offset) } : {}) };
+        if (Object.keys(focusRing).length)
+            out.focusRing = focusRing;
+    }
+    const selection = obj(source.selection), fill = role(selection.fill), text = role(selection.text);
+    if (fill && text)
+        out.selection = { fill, text };
+    const bar = obj(source.scrollbar);
+    if (Object.keys(bar).length) {
+        const width = oneOf(bar.width, ['auto', 'thin']), thumb = role(bar.thumb), track = role(bar.track), style = oneOf(bar.style, ['flat', 'classic']);
+        const scrollbar = { ...(width ? { width } : {}), ...(thumb ? { thumb } : {}), ...(track ? { track } : {}), ...(style ? { style } : {}) };
+        if (Object.keys(scrollbar).length)
+            out.scrollbar = scrollbar;
+    }
+    const underline = oneOf(obj(source.links).underline, LINK_UNDERLINES);
+    if (underline)
+        out.links = { underline };
+    const motion = obj(source.motion);
+    if (Object.keys(motion).length) {
+        const duration = num(motion.duration, 0, 400), curve = oneOf(motion.curve, MOTION_CURVES), press = num(motion.press, 0.96, 1);
+        const value = { ...(duration !== undefined ? { duration: Math.round(duration) } : {}), ...(curve ? { curve } : {}), ...(press !== undefined ? { press: +press.toFixed(3) } : {}) };
+        if (Object.keys(value).length)
+            out.motion = value;
+    }
+    return Object.keys(out).length ? out : null;
+}
+const CURVES = {
+    standard: 'cubic-bezier(.2,.7,.2,1)', snappy: 'cubic-bezier(.3,1.4,.5,1)', spring: 'cubic-bezier(.2,1.6,.4,1)', linear: 'linear', steps: 'steps(3,end)',
+};
+/** The role among `candidates` that reaches `ratio` on every surface, else the most visible one. */
+function visibleOn(colors, wanted, surfaces, ratio) {
+    const worst = (hex) => Math.min(...surfaces.map(surface => contrastRatio(hex, surface)));
+    if (worst(colors[wanted]) >= ratio)
+        return colors[wanted];
+    return ['accent', 'text', 'inverse'].map(name => colors[name]).reduce((best, hex) => worst(hex) > worst(best) ? hex : best, colors[wanted]);
+}
+/**
+ * CSS for a theme's decoration. A focus ring is always drawn when the theme names one (at least 2px
+ * and 3:1 on the page's surfaces: the color is swapped for a visible one otherwise); motion only
+ * for people who have not asked for less of it.
+ */
+export function compileDecor(decor, targets, ctx) {
+    const out = [];
+    const { colors } = ctx;
+    const surfaces = [colors.bg, colors.surface, colors.page];
+    if (decor.dividers && targets.divider) {
+        const { style, color = 'border', width } = decor.dividers;
+        const line = style === 'none' ? '0 none' : `${style === 'hairline' ? 1 : width ?? (style === 'double' ? 3 : 1)}px ${style === 'hairline' ? 'solid' : style} ${colors[color]}`;
+        out.push(`:root:root :is(${targets.divider}){border-bottom:${line} !important}`);
+    }
+    if (decor.focusRing && targets.focusable) {
+        const { width = 2, style = 'solid', color = 'accent', offset = 2 } = decor.focusRing;
+        out.push(`:root:root :is(${targets.focusable}):focus-visible{outline:${Math.max(2, width)}px ${style} ${visibleOn(colors, color, surfaces, 3)} !important;outline-offset:${offset}px !important}`);
+    }
+    if (decor.selection) {
+        const fill = colors[decor.selection.fill];
+        const text = contrastRatio(colors[decor.selection.text], fill) >= 4.5 ? colors[decor.selection.text] : (contrastRatio('#ffffff', fill) >= contrastRatio('#000000', fill) ? '#ffffff' : '#000000');
+        out.push(`:root:root ::selection{background-color:${fill} !important;color:${text} !important}`);
+    }
+    if (decor.scrollbar) {
+        const { width, thumb = 'border', track, style } = decor.scrollbar;
+        const scroller = targets.scroller ?? 'html,body';
+        const thumbColor = visibleOn(colors, thumb, [track ? colors[track] : colors.page], 1.5);
+        out.push(`:root:root :is(${scroller}){scrollbar-color:${thumbColor} ${track ? colors[track] : 'transparent'} !important${width ? `;scrollbar-width:${width} !important` : ''}}`);
+        // The classic look needs the engine's own scrollbar parts; `scrollbar-color` would switch them off where both are set.
+        if (style === 'classic') {
+            const face = track ? colors[track] : colors.surface;
+            out.push(`@supports selector(::-webkit-scrollbar){:root:root :is(${scroller}){scrollbar-color:auto !important;scrollbar-width:auto !important}:root:root ::-webkit-scrollbar{width:16px;height:16px;background:${face}}:root:root ::-webkit-scrollbar-thumb{background:${colors.surface};box-shadow:inset -1px -1px ${colors.text},inset 1px 1px ${colors.bg},inset -2px -2px ${colors.muted},inset 2px 2px ${colors.elevated}}:root:root ::-webkit-scrollbar-corner{background:${face}}}`);
+        }
+    }
+    if (decor.links && targets.link) {
+        const { underline } = decor.links;
+        out.push(`:root:root :is(${targets.link}){text-decoration:${underline === 'always' ? 'underline' : 'none'} !important;text-underline-offset:2px}`);
+        if (underline === 'hover')
+            out.push(`:root:root :is(${targets.link}):hover{text-decoration:underline !important}`);
+    }
+    if (decor.motion && (targets.moving || targets.pressable)) {
+        const { duration, curve = 'standard', press } = decor.motion;
+        const rules = [];
+        if (duration !== undefined && targets.moving) {
+            rules.push(`:root:root :is(${targets.moving}){transition:background-color ${duration}ms ${CURVES[curve]},color ${duration}ms ${CURVES[curve]},border-color ${duration}ms ${CURVES[curve]},box-shadow ${duration}ms ${CURVES[curve]},transform ${duration}ms ${CURVES[curve]} !important}`);
+        }
+        if (press !== undefined && press < 1 && targets.pressable)
+            rules.push(`:root:root :is(${targets.pressable}):active{transform:scale(${press}) !important}`);
+        if (rules.length)
+            out.push(`@media (prefers-reduced-motion:no-preference){${rules.join('')}}`);
+    }
+    if (decor.chrome) {
+        const css = targets.chrome?.[decor.chrome.kind]?.(decor.chrome.title ?? '', ctx);
+        if (css)
+            out.push(css);
+    }
+    return out;
+}
+/** A theme's text as a CSS string literal (for `content`): the allow-list of `chromeTitle` plus escaping of what could end the string. */
+export const cssString = (value) => `"${value.replace(/[\\"\n\r\f]/g, match => `\\${match.charCodeAt(0).toString(16)} `)}"`;
+//# sourceMappingURL=themeDecor.js.map

package/dist/runtime/themeDecor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"themeDecor.js","sourceRoot":"","sources":["../../../runtime/src/themeDecor.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,oGAAoG;AACpG,sGAAsG;AACtG,QAAQ;AAER,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAmC,MAAM,sBAAsB,CAAC;AAEpF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AACnG,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,CAAU,CAAC;AAChF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAC5E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAC;AAC1F,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAarE,MAAM,GAAG,GAAG,CAAC,KAAc,EAA2B,EAAE,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAgC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC7J,MAAM,KAAK,GAAG,CAAmB,KAAc,EAAE,OAAqB,EAAiB,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAU,CAAC,CAAC,CAAC,CAAC,KAAU,CAAC,CAAC,CAAC,SAAS,CAAC;AAChJ,MAAM,GAAG,GAAG,CAAC,KAAc,EAAE,GAAW,EAAE,GAAW,EAAsB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACpL,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;AAC3D,gIAAgI;AAChI,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAc,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,yCAAyC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAEpL,oEAAoE;AACpE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;IAC5F,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACtE,GAAG,CAAC,QAAQ,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACpI,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC3E,IAAI,IAAI,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QAAC,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAAC,GAAG,CAAC,MAAM,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAAC,CAAC;IAC7H,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACnC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACvI,MAAM,SAAS,GAAG,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QAC9M,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM;YAAE,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/D,CAAC;IACD,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClG,IAAI,IAAI,IAAI,IAAI;QAAE,GAAG,CAAC,SAAS,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACjD,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAU,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,SAAS,CAAU,CAAC,CAAC;QACpK,MAAM,SAAS,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QACzI,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM;YAAE,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/D,CAAC;IACD,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IACtE,IAAI,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,EAAE,SAAS,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,EAAE,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC9H,MAAM,KAAK,GAAG,EAAE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QACnL,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM;YAAE,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC;IACpD,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9C,CAAC;AAoBD,MAAM,MAAM,GAAiD;IAC3D,QAAQ,EAAE,0BAA0B,EAAE,MAAM,EAAE,2BAA2B,EAAE,MAAM,EAAE,2BAA2B,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc;CACxJ,CAAC;AAEF,oGAAoG;AACpG,SAAS,SAAS,CAAC,MAAkB,EAAE,MAAiB,EAAE,QAAkB,EAAE,KAAa;IACzF,MAAM,KAAK,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACjG,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1D,OAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AAC/J,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAyC,KAAiB,EAAE,OAA8B,EAAE,GAAY;IAClI,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IACvB,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,KAAK,CAAC,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACtC,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,QAAQ,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC1D,MAAM,IAAI,GAAG,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9K,GAAG,CAAC,IAAI,CAAC,kBAAkB,OAAO,CAAC,OAAO,mBAAmB,IAAI,cAAc,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACzC,MAAM,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,EAAE,KAAK,GAAG,QAAQ,EAAE,MAAM,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC;QACrF,GAAG,CAAC,IAAI,CAAC,kBAAkB,OAAO,CAAC,SAAS,2BAA2B,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,KAAK,IAAI,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,8BAA8B,MAAM,gBAAgB,CAAC,CAAC;IACrM,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAClM,GAAG,CAAC,IAAI,CAAC,2CAA2C,IAAI,qBAAqB,IAAI,cAAc,CAAC,CAAC;IACnG,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC;QAClE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,WAAW,CAAC;QACjD,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QACxF,GAAG,CAAC,IAAI,CAAC,kBAAkB,QAAQ,qBAAqB,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,cAAc,KAAK,CAAC,CAAC,CAAC,oBAAoB,KAAK,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACjL,uHAAuH;QACvH,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;YACpD,GAAG,CAAC,IAAI,CAAC,0DAA0D,QAAQ,sIAAsI,IAAI,oDAAoD,MAAM,CAAC,OAAO,+BAA+B,MAAM,CAAC,IAAI,kBAAkB,MAAM,CAAC,EAAE,oBAAoB,MAAM,CAAC,KAAK,kBAAkB,MAAM,CAAC,QAAQ,qDAAqD,IAAI,IAAI,CAAC,CAAC;QAC9d,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC;QAClC,GAAG,CAAC,IAAI,CAAC,kBAAkB,OAAO,CAAC,IAAI,qBAAqB,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,wCAAwC,CAAC,CAAC;QACnJ,IAAI,SAAS,KAAK,OAAO;YAAE,GAAG,CAAC,IAAI,CAAC,kBAAkB,OAAO,CAAC,IAAI,+CAA+C,CAAC,CAAC;IACrH,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1D,MAAM,EAAE,QAAQ,EAAE,KAAK,GAAG,UAAU,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC;QAC7D,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YAC7C,KAAK,CAAC,IAAI,CAAC,kBAAkB,OAAO,CAAC,MAAM,iCAAiC,QAAQ,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,QAAQ,MAAM,MAAM,CAAC,KAAK,CAAC,iBAAiB,QAAQ,MAAM,MAAM,CAAC,KAAK,CAAC,eAAe,QAAQ,MAAM,MAAM,CAAC,KAAK,CAAC,cAAc,QAAQ,MAAM,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAC7R,CAAC;QACD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,GAAG,CAAC,IAAI,OAAO,CAAC,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB,OAAO,CAAC,SAAS,4BAA4B,KAAK,eAAe,CAAC,CAAC;QAC3J,IAAI,KAAK,CAAC,MAAM;YAAE,GAAG,CAAC,IAAI,CAAC,iDAAiD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACjG,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,IAAoD,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;QACjI,IAAI,GAAG;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,0IAA0I;AAC1I,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC","sourcesContent":["// Decoration: what a theme draws between and around the components: divider lines, a title bar or a\n// masthead, the focus ring, selection, scrollbars, link underlines, the feel of motion. Fixed words\n// and clamped numbers, colors by role. Where the lines and bars go is the site's (its decor targets).\n// Pure.\n\nimport { contrastRatio } from './themeApi.ts';\nimport { COLOR_ROLES, type ColorRole, type RoleColors } from './themeComponents.ts';\n\nexport const DIVIDER_STYLES = ['none', 'hairline', 'solid', 'dashed', 'dotted', 'double'] as const;\nexport const CHROME_KINDS = ['none', 'titlebar', 'masthead', 'prompt'] as const;\nexport const RING_STYLES = ['solid', 'dashed', 'dotted', 'double'] as const;\nexport const MOTION_CURVES = ['standard', 'snappy', 'spring', 'linear', 'steps'] as const;\nexport const LINK_UNDERLINES = ['always', 'hover', 'never'] as const;\n\nexport type ThemeDecor = {\n  dividers?: { style: typeof DIVIDER_STYLES[number]; color?: ColorRole; width?: number };\n  /** A drawn frame around the main column: a window title bar, a newspaper masthead, a terminal prompt. `title` is plain text. */\n  chrome?: { kind: typeof CHROME_KINDS[number]; title?: string };\n  focusRing?: { width?: number; style?: typeof RING_STYLES[number]; color?: ColorRole; offset?: number };\n  selection?: { fill: ColorRole; text: ColorRole };\n  scrollbar?: { width?: 'auto' | 'thin'; thumb?: ColorRole; track?: ColorRole; style?: 'flat' | 'classic' };\n  links?: { underline: typeof LINK_UNDERLINES[number] };\n  motion?: { duration?: number; curve?: typeof MOTION_CURVES[number]; press?: number };\n};\n\nconst obj = (value: unknown): Record<string, unknown> => value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};\nconst oneOf = <T extends string>(value: unknown, options: readonly T[]): T | undefined => options.includes(value as T) ? value as T : undefined;\nconst num = (value: unknown, min: number, max: number): number | undefined => typeof value === 'number' && Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : undefined;\nconst role = (value: unknown) => oneOf(value, COLOR_ROLES);\n/** Text a theme may put into a drawn bar: letters, digits, spaces and a little punctuation; it is written into a CSS string. */\nexport const chromeTitle = (value: unknown) => typeof value === 'string' ? value.replace(/[^\\p{L}\\p{N} .,:!?&+\\-_/#@*~()[\\]|>$]/gu, '').replace(/&/g, '+').trim().slice(0, 24) : '';\n\n/** The `decor` group from JSON. Null when nothing valid is left. */\nexport function sanitizeDecor(value: unknown): ThemeDecor | null {\n  const source = obj(value);\n  const out: ThemeDecor = {};\n  const dividers = obj(source.dividers), dividerStyle = oneOf(dividers.style, DIVIDER_STYLES);\n  if (dividerStyle) {\n    const color = role(dividers.color), width = num(dividers.width, 0, 3);\n    out.dividers = { style: dividerStyle, ...(color ? { color } : {}), ...(width !== undefined ? { width: +width.toFixed(1) } : {}) };\n  }\n  const chrome = obj(source.chrome), kind = oneOf(chrome.kind, CHROME_KINDS);\n  if (kind && kind !== 'none') { const title = chromeTitle(chrome.title); out.chrome = { kind, ...(title ? { title } : {}) }; }\n  const ring = obj(source.focusRing);\n  if (Object.keys(ring).length) {\n    const width = num(ring.width, 2, 4), style = oneOf(ring.style, RING_STYLES), color = role(ring.color), offset = num(ring.offset, 0, 4);\n    const focusRing = { ...(width !== undefined ? { width: Math.round(width) } : {}), ...(style ? { style } : {}), ...(color ? { color } : {}), ...(offset !== undefined ? { offset: Math.round(offset) } : {}) };\n    if (Object.keys(focusRing).length) out.focusRing = focusRing;\n  }\n  const selection = obj(source.selection), fill = role(selection.fill), text = role(selection.text);\n  if (fill && text) out.selection = { fill, text };\n  const bar = obj(source.scrollbar);\n  if (Object.keys(bar).length) {\n    const width = oneOf(bar.width, ['auto', 'thin'] as const), thumb = role(bar.thumb), track = role(bar.track), style = oneOf(bar.style, ['flat', 'classic'] as const);\n    const scrollbar = { ...(width ? { width } : {}), ...(thumb ? { thumb } : {}), ...(track ? { track } : {}), ...(style ? { style } : {}) };\n    if (Object.keys(scrollbar).length) out.scrollbar = scrollbar;\n  }\n  const underline = oneOf(obj(source.links).underline, LINK_UNDERLINES);\n  if (underline) out.links = { underline };\n  const motion = obj(source.motion);\n  if (Object.keys(motion).length) {\n    const duration = num(motion.duration, 0, 400), curve = oneOf(motion.curve, MOTION_CURVES), press = num(motion.press, 0.96, 1);\n    const value = { ...(duration !== undefined ? { duration: Math.round(duration) } : {}), ...(curve ? { curve } : {}), ...(press !== undefined ? { press: +press.toFixed(3) } : {}) };\n    if (Object.keys(value).length) out.motion = value;\n  }\n  return Object.keys(out).length ? out : null;\n}\n\n/** Where a site's decoration goes. Every entry is optional: a site without it draws nothing for that key. */\nexport type DecorTargets<Context> = {\n  /** Rows whose bottom edge is the divider between items (a site's list cells). */\n  divider?: string;\n  /** Links inside running text. */\n  link?: string;\n  /** What takes keyboard focus. */\n  focusable?: string;\n  /** What moves with `motion` (buttons, links, rows). */\n  moving?: string;\n  /** What a press shrinks. */\n  pressable?: string;\n  /** The scrollable roots. */\n  scroller?: string;\n  /** The site's drawing of each chrome kind. */\n  chrome?: Partial<Record<Exclude<typeof CHROME_KINDS[number], 'none'>, (title: string, ctx: Context) => string>>;\n};\n\nconst CURVES: Record<typeof MOTION_CURVES[number], string> = {\n  standard: 'cubic-bezier(.2,.7,.2,1)', snappy: 'cubic-bezier(.3,1.4,.5,1)', spring: 'cubic-bezier(.2,1.6,.4,1)', linear: 'linear', steps: 'steps(3,end)',\n};\n\n/** The role among `candidates` that reaches `ratio` on every surface, else the most visible one. */\nfunction visibleOn(colors: RoleColors, wanted: ColorRole, surfaces: string[], ratio: number): string {\n  const worst = (hex: string) => Math.min(...surfaces.map(surface => contrastRatio(hex, surface)));\n  if (worst(colors[wanted]) >= ratio) return colors[wanted];\n  return (['accent', 'text', 'inverse'] as ColorRole[]).map(name => colors[name]).reduce((best, hex) => worst(hex) > worst(best) ? hex : best, colors[wanted]);\n}\n\n/**\n * CSS for a theme's decoration. A focus ring is always drawn when the theme names one (at least 2px\n * and 3:1 on the page's surfaces: the color is swapped for a visible one otherwise); motion only\n * for people who have not asked for less of it.\n */\nexport function compileDecor<Context extends { colors: RoleColors }>(decor: ThemeDecor, targets: DecorTargets<Context>, ctx: Context): string[] {\n  const out: string[] = [];\n  const { colors } = ctx;\n  const surfaces = [colors.bg, colors.surface, colors.page];\n  if (decor.dividers && targets.divider) {\n    const { style, color = 'border', width } = decor.dividers;\n    const line = style === 'none' ? '0 none' : `${style === 'hairline' ? 1 : width ?? (style === 'double' ? 3 : 1)}px ${style === 'hairline' ? 'solid' : style} ${colors[color]}`;\n    out.push(`:root:root :is(${targets.divider}){border-bottom:${line} !important}`);\n  }\n  if (decor.focusRing && targets.focusable) {\n    const { width = 2, style = 'solid', color = 'accent', offset = 2 } = decor.focusRing;\n    out.push(`:root:root :is(${targets.focusable}):focus-visible{outline:${Math.max(2, width)}px ${style} ${visibleOn(colors, color, surfaces, 3)} !important;outline-offset:${offset}px !important}`);\n  }\n  if (decor.selection) {\n    const fill = colors[decor.selection.fill];\n    const text = contrastRatio(colors[decor.selection.text], fill) >= 4.5 ? colors[decor.selection.text] : (contrastRatio('#ffffff', fill) >= contrastRatio('#000000', fill) ? '#ffffff' : '#000000');\n    out.push(`:root:root ::selection{background-color:${fill} !important;color:${text} !important}`);\n  }\n  if (decor.scrollbar) {\n    const { width, thumb = 'border', track, style } = decor.scrollbar;\n    const scroller = targets.scroller ?? 'html,body';\n    const thumbColor = visibleOn(colors, thumb, [track ? colors[track] : colors.page], 1.5);\n    out.push(`:root:root :is(${scroller}){scrollbar-color:${thumbColor} ${track ? colors[track] : 'transparent'} !important${width ? `;scrollbar-width:${width} !important` : ''}}`);\n    // The classic look needs the engine's own scrollbar parts; `scrollbar-color` would switch them off where both are set.\n    if (style === 'classic') {\n      const face = track ? colors[track] : colors.surface;\n      out.push(`@supports selector(::-webkit-scrollbar){:root:root :is(${scroller}){scrollbar-color:auto !important;scrollbar-width:auto !important}:root:root ::-webkit-scrollbar{width:16px;height:16px;background:${face}}:root:root ::-webkit-scrollbar-thumb{background:${colors.surface};box-shadow:inset -1px -1px ${colors.text},inset 1px 1px ${colors.bg},inset -2px -2px ${colors.muted},inset 2px 2px ${colors.elevated}}:root:root ::-webkit-scrollbar-corner{background:${face}}}`);\n    }\n  }\n  if (decor.links && targets.link) {\n    const { underline } = decor.links;\n    out.push(`:root:root :is(${targets.link}){text-decoration:${underline === 'always' ? 'underline' : 'none'} !important;text-underline-offset:2px}`);\n    if (underline === 'hover') out.push(`:root:root :is(${targets.link}):hover{text-decoration:underline !important}`);\n  }\n  if (decor.motion && (targets.moving || targets.pressable)) {\n    const { duration, curve = 'standard', press } = decor.motion;\n    const rules: string[] = [];\n    if (duration !== undefined && targets.moving) {\n      rules.push(`:root:root :is(${targets.moving}){transition:background-color ${duration}ms ${CURVES[curve]},color ${duration}ms ${CURVES[curve]},border-color ${duration}ms ${CURVES[curve]},box-shadow ${duration}ms ${CURVES[curve]},transform ${duration}ms ${CURVES[curve]} !important}`);\n    }\n    if (press !== undefined && press < 1 && targets.pressable) rules.push(`:root:root :is(${targets.pressable}):active{transform:scale(${press}) !important}`);\n    if (rules.length) out.push(`@media (prefers-reduced-motion:no-preference){${rules.join('')}}`);\n  }\n  if (decor.chrome) {\n    const css = targets.chrome?.[decor.chrome.kind as Exclude<typeof CHROME_KINDS[number], 'none'>]?.(decor.chrome.title ?? '', ctx);\n    if (css) out.push(css);\n  }\n  return out;\n}\n\n/** A theme's text as a CSS string literal (for `content`): the allow-list of `chromeTitle` plus escaping of what could end the string. */\nexport const cssString = (value: string) => `\"${value.replace(/[\\\\\"\\n\\r\\f]/g, match => `\\\\${match.charCodeAt(0).toString(16)} `)}\"`;\n"]}

package/dist/runtime/themeDoctor.d.ts

@@ -0,0 +1,11 @@
+import { type ThemeSpec } from './themeSpec.ts';
+export type DoctorAdvice = {
+    /** `lighter`: a lighter mechanism would do; `performance`, `accessibility`, `contrast`: a cost. */
+    kind: 'lighter' | 'performance' | 'accessibility' | 'contrast';
+    /** Stable id, for tests and translations (`wb.doctor.<id>`). */
+    id: string;
+    /** English text (the panel translates by id when it has the words). */
+    text: string;
+};
+/** Advice for a theme document. Empty when there is nothing to say. */
+export declare function themeDoctor(theme: ThemeSpec): DoctorAdvice[];

package/dist/runtime/themeDoctor.js

@@ -0,0 +1,51 @@
+// The theme doctor: advice, never a block. A theme may do anything its trust level allows; the doctor
+// points at the lighter mechanism for what the theme does (a token before a component setting, a
+// component setting before CSS, CSS before a script) and at performance, accessibility and contrast
+// costs. Used by the import screen, the Theme Builder's report and `waybetter store check`. Pure.
+import { contrastRatio } from "./themeApi.js";
+import { ensureContrast } from "./themeSpec.js";
+/** What a theme's free-form CSS does that a v2 group does without CSS. */
+const CSS_RULES = [
+    { id: 'css-radius', kind: 'lighter', test: /border-radius\s*:/i, text: 'Corner radii: components.<part>.radius (or shape.radius) sets them without CSS and keeps working when the site renames its classes.' },
+    { id: 'css-bevel', kind: 'lighter', test: /box-shadow\s*:[^;{}]*inset[^;{}]*inset[^;{}]*inset/i, text: 'Bevelled edges: components.<part>.borderStyle "bevel-out" / "bevel-in" draws them from the theme\'s colors.' },
+    { id: 'css-hide', kind: 'lighter', test: /display\s*:\s*none/i, text: 'Hiding a part: components.<part>.visible (avatars, counts, names) or a layout variant (sidebar: hidden) does it, and the owner can switch it back.' },
+    { id: 'css-color', kind: 'lighter', test: /(?:^|[;{\s])(?:color|background(?:-color)?)\s*:\s*#[0-9a-f]{3,8}/i, text: 'Literal colors: name a role (text, muted, accent, surface…) in colors or in a component, so the contrast pass covers it.' },
+    { id: 'css-font', kind: 'lighter', test: /font-family\s*:/i, text: 'Fonts: font.roles sets the post, heading, numbers and mono faces without CSS.' },
+    { id: 'css-has', kind: 'performance', test: /:has\(/i, text: ':has() is matched again on every change of the page; keep it off rules that repeat down a timeline.' },
+    { id: 'css-universal', kind: 'performance', test: /(?:^|[\s,>+~])\*\s*(?:[,{>+~:\[]|$)/m, text: 'A universal selector (*) is matched against every element; anchor the rule on a part.' },
+    { id: 'css-blur', kind: 'performance', test: /backdrop-filter\s*:/i, text: 'Blur (backdrop-filter) is costly on parts that repeat; the glass fill of bars and panels is the cheaper place for it.' },
+    { id: 'css-outline-none', kind: 'accessibility', test: /outline\s*:\s*(?:none|0)\b/i, text: 'Removing the outline hides where keyboard focus is; decor.focusRing draws a visible one instead.' },
+    { id: 'css-motion', kind: 'accessibility', test: /(?:animation|transition)\s*:/i, text: 'Motion should stay inside @media (prefers-reduced-motion: no-preference); decor.motion does that for you.' },
+];
+/** Advice for a theme document. Empty when there is nothing to say. */
+export function themeDoctor(theme) {
+    const out = [];
+    const css = theme.css ?? '';
+    if (css.trim()) {
+        for (const rule of CSS_RULES)
+            if (rule.test.test(css))
+                out.push({ kind: rule.kind, id: rule.id, text: rule.text });
+        if (css.length > 20_000)
+            out.push({ kind: 'performance', id: 'css-size', text: 'More than 20,000 characters of CSS: the site recalculates styles with every rule; tokens and component settings compile to fewer rules.' });
+    }
+    if (theme.colors) {
+        const fixed = ensureContrast(theme.colors);
+        for (const role of ['text', 'muted', 'accent']) {
+            if (fixed[role] !== theme.colors[role])
+                out.push({ kind: 'contrast', id: `contrast-${role}`, text: `The ${role} color was adjusted to stay readable (${contrastRatio(theme.colors[role], theme.colors.bg).toFixed(2)}:1 on the background).` });
+        }
+    }
+    if (theme.components) {
+        const posts = theme.components.post;
+        if (posts?.fill === 'glass')
+            out.push({ kind: 'performance', id: 'glass-post', text: 'Glass on posts is not drawn: blur on every post of a timeline is too costly.' });
+        const text = theme.components.postText?.fontSize;
+        if (text !== undefined && text < 14)
+            out.push({ kind: 'accessibility', id: 'small-post-text', text: 'Post text under 14px is hard to read for many people.' });
+    }
+    if (theme.variants?.nav === 'top' || theme.variants?.nav === 'bottom') {
+        out.push({ kind: 'accessibility', id: 'nav-moved', text: 'Moving the navigation changes where people look for it; it only applies on wide panes, and the owner can turn layout changes off.' });
+    }
+    return out;
+}
+//# sourceMappingURL=themeDoctor.js.map

package/dist/runtime/themeDoctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"themeDoctor.js","sourceRoot":"","sources":["../../../runtime/src/themeDoctor.ts"],"names":[],"mappings":"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","sourcesContent":["// The theme doctor: advice, never a block. A theme may do anything its trust level allows; the doctor\n// points at the lighter mechanism for what the theme does (a token before a component setting, a\n// component setting before CSS, CSS before a script) and at performance, accessibility and contrast\n// costs. Used by the import screen, the Theme Builder's report and `waybetter store check`. Pure.\n\nimport { contrastRatio } from './themeApi.ts';\nimport { ensureContrast, type ThemeSpec } from './themeSpec.ts';\n\nexport type DoctorAdvice = {\n  /** `lighter`: a lighter mechanism would do; `performance`, `accessibility`, `contrast`: a cost. */\n  kind: 'lighter' | 'performance' | 'accessibility' | 'contrast';\n  /** Stable id, for tests and translations (`wb.doctor.<id>`). */\n  id: string;\n  /** English text (the panel translates by id when it has the words). */\n  text: string;\n};\n\ntype Rule = { id: string; kind: DoctorAdvice['kind']; test: RegExp; text: string };\n/** What a theme's free-form CSS does that a v2 group does without CSS. */\nconst CSS_RULES: Rule[] = [\n  { id: 'css-radius', kind: 'lighter', test: /border-radius\\s*:/i, text: 'Corner radii: components.<part>.radius (or shape.radius) sets them without CSS and keeps working when the site renames its classes.' },\n  { id: 'css-bevel', kind: 'lighter', test: /box-shadow\\s*:[^;{}]*inset[^;{}]*inset[^;{}]*inset/i, text: 'Bevelled edges: components.<part>.borderStyle \"bevel-out\" / \"bevel-in\" draws them from the theme\\'s colors.' },\n  { id: 'css-hide', kind: 'lighter', test: /display\\s*:\\s*none/i, text: 'Hiding a part: components.<part>.visible (avatars, counts, names) or a layout variant (sidebar: hidden) does it, and the owner can switch it back.' },\n  { id: 'css-color', kind: 'lighter', test: /(?:^|[;{\\s])(?:color|background(?:-color)?)\\s*:\\s*#[0-9a-f]{3,8}/i, text: 'Literal colors: name a role (text, muted, accent, surface…) in colors or in a component, so the contrast pass covers it.' },\n  { id: 'css-font', kind: 'lighter', test: /font-family\\s*:/i, text: 'Fonts: font.roles sets the post, heading, numbers and mono faces without CSS.' },\n  { id: 'css-has', kind: 'performance', test: /:has\\(/i, text: ':has() is matched again on every change of the page; keep it off rules that repeat down a timeline.' },\n  { id: 'css-universal', kind: 'performance', test: /(?:^|[\\s,>+~])\\*\\s*(?:[,{>+~:\\[]|$)/m, text: 'A universal selector (*) is matched against every element; anchor the rule on a part.' },\n  { id: 'css-blur', kind: 'performance', test: /backdrop-filter\\s*:/i, text: 'Blur (backdrop-filter) is costly on parts that repeat; the glass fill of bars and panels is the cheaper place for it.' },\n  { id: 'css-outline-none', kind: 'accessibility', test: /outline\\s*:\\s*(?:none|0)\\b/i, text: 'Removing the outline hides where keyboard focus is; decor.focusRing draws a visible one instead.' },\n  { id: 'css-motion', kind: 'accessibility', test: /(?:animation|transition)\\s*:/i, text: 'Motion should stay inside @media (prefers-reduced-motion: no-preference); decor.motion does that for you.' },\n];\n\n/** Advice for a theme document. Empty when there is nothing to say. */\nexport function themeDoctor(theme: ThemeSpec): DoctorAdvice[] {\n  const out: DoctorAdvice[] = [];\n  const css = theme.css ?? '';\n  if (css.trim()) {\n    for (const rule of CSS_RULES) if (rule.test.test(css)) out.push({ kind: rule.kind, id: rule.id, text: rule.text });\n    if (css.length > 20_000) out.push({ kind: 'performance', id: 'css-size', text: 'More than 20,000 characters of CSS: the site recalculates styles with every rule; tokens and component settings compile to fewer rules.' });\n  }\n  if (theme.colors) {\n    const fixed = ensureContrast(theme.colors);\n    for (const role of ['text', 'muted', 'accent'] as const) {\n      if (fixed[role] !== theme.colors[role]) out.push({ kind: 'contrast', id: `contrast-${role}`, text: `The ${role} color was adjusted to stay readable (${contrastRatio(theme.colors[role], theme.colors.bg).toFixed(2)}:1 on the background).` });\n    }\n  }\n  if (theme.components) {\n    const posts = theme.components.post;\n    if (posts?.fill === 'glass') out.push({ kind: 'performance', id: 'glass-post', text: 'Glass on posts is not drawn: blur on every post of a timeline is too costly.' });\n    const text = theme.components.postText?.fontSize;\n    if (text !== undefined && text < 14) out.push({ kind: 'accessibility', id: 'small-post-text', text: 'Post text under 14px is hard to read for many people.' });\n  }\n  if (theme.variants?.nav === 'top' || theme.variants?.nav === 'bottom') {\n    out.push({ kind: 'accessibility', id: 'nav-moved', text: 'Moving the navigation changes where people look for it; it only applies on wide panes, and the owner can turn layout changes off.' });\n  }\n  return out;\n}\n"]}

package/dist/runtime/themeIcons.d.ts

@@ -0,0 +1,130 @@
+import { type ColorRole, type RoleColors } from './themeComponents.ts';
+/** Semantic names a pack may draw. `.active` is a selected navigation item, `.on` an action that is set. */
+export declare const ICON_NAMES: readonly ["home", "home.active", "explore", "explore.active", "notifications", "notifications.active", "messages", "messages.active", "grok", "bookmarks", "bookmarks.active", "lists", "communities", "premium", "profile", "profile.active", "more", "compose", "reply", "repost", "repost.on", "like", "like.on", "views", "bookmark", "bookmark.on", "share", "verified", "logo", "caret", "back", "close", "search", "settings", "media", "gif", "poll", "emoji", "schedule", "location", "pinned", "repostContext", "lock"];
+export type IconName = typeof ICON_NAMES[number];
+export declare const ICON_GROUPS: readonly ["nav", "actions", "composer", "misc"];
+export type IconGroup = typeof ICON_GROUPS[number];
+/** Limits of a pack (the JSON Schema and the Store check say the same). */
+export declare const ICON_LIMITS: {
+    readonly names: 64;
+    readonly pathChars: 4000;
+    readonly layers: 6;
+    readonly pngChars: 6000;
+    readonly packBytes: 120000;
+    readonly labelChars: 12;
+    readonly overrides: 8;
+};
+/** Path data only: commands, numbers, separators. */
+export declare const PATH_GRAMMAR: RegExp;
+export type IconFill = ColorRole | string | {
+    from: string;
+    to: string;
+};
+export type IconGlyph = {
+    d: string;
+    rule?: 'evenodd';
+    stroke?: boolean;
+} | {
+    layers: Array<{
+        d: string;
+        fill: IconFill;
+        opacity?: number;
+        rule?: 'evenodd';
+    }>;
+} | {
+    png: string;
+    pixel?: boolean;
+};
+export type IconStyle = {
+    stroke: number;
+    cap: 'round' | 'square' | 'butt';
+    join: 'round' | 'miter' | 'bevel';
+    scale: number;
+};
+export declare const BASE_ICON_STYLE: IconStyle;
+export declare const ICON_LABEL_NAMES: readonly ["reply", "repost", "like", "views", "bookmark", "share"];
+export type IconLabels = Partial<Record<typeof ICON_LABEL_NAMES[number], string>>;
+export type IconSymbols = {
+    like?: 'heart' | 'star' | 'custom';
+    separator?: 'dot' | 'bullet' | 'slash' | 'dash' | 'pipe' | 'none';
+};
+export type IconPack = {
+    id: string;
+    name: string;
+    description: string;
+    author: string;
+    /** SPDX id, or `own` for the author's own drawings, or a plain name for artwork under other terms. */
+    license: string;
+    /** Where the drawings come from (a project name or URL as text) and whom to credit. */
+    source: string;
+    credits: string;
+    version: 1;
+    style: IconStyle;
+    glyphs: Partial<Record<IconName, IconGlyph>>;
+    symbols?: IconSymbols;
+    labels?: IconLabels;
+};
+/** What a theme says about icons: a pack by id, plus small adjustments. Never a whole pack. */
+export type ThemeIcons = {
+    pack?: string;
+    style?: Partial<IconStyle>;
+    overrides?: Partial<Record<IconName, IconGlyph>>;
+    symbols?: IconSymbols;
+    labels?: IconLabels;
+};
+/** One glyph from JSON, or null when it is not valid path data, layers or a small PNG. */
+export declare function sanitizeGlyph(value: unknown): IconGlyph | null;
+export declare const sanitizeIconStyle: (value: unknown, base?: IconStyle) => IconStyle;
+/** Any JSON to a valid pack, or null when it has no id, no name or no valid glyph. */
+export declare function sanitizeIconPack(input: unknown): IconPack | null;
+/** Parses an imported `*.icons.json`; errors are human-readable. */
+export declare function parseIconPackJson(json: string): {
+    pack: IconPack;
+    warnings: string[];
+} | {
+    error: string;
+};
+/** The `icons` group of a theme from JSON. Null when it says nothing valid. */
+export declare function sanitizeThemeIcons(value: unknown): ThemeIcons | null;
+/** `theme`: follow the theme's suggestion; `site`: the site's own icons; otherwise a pack id. */
+export type IconChoice = 'theme' | 'site' | string;
+export declare const normalizeIconChoice: (value: unknown) => IconChoice;
+export type IconCatalog = {
+    packs: readonly IconPack[];
+    get(id: string | undefined): IconPack | null;
+    /** The pack that is drawn: the owner's pick, else the theme's suggestion; null for the site's own icons or an unknown pack. */
+    resolve(choice: IconChoice, theme: ThemeIcons | null | undefined): IconPack | null;
+};
+export declare function createIconCatalog(builtins: readonly IconPack[], installed?: readonly IconPack[]): IconCatalog;
+/** The SVG document of a glyph, built from validated data. `colors` resolves role fills of layers; a single path is black (it is used as a mask). */
+export declare function glyphSvg(glyph: IconGlyph, style: IconStyle, colors?: RoleColors | null): string | null;
+/** True for glyphs that carry their own colors (drawn as an image, not as a mask of the current color). */
+export declare const isColored: (glyph: IconGlyph) => boolean;
+/** How a site finds one of its icons: the container that holds it (stable hooks), else the start of its path data. */
+export type IconMatcher = {
+    /** Selector of the icon's `<svg>` by its container (`[data-testid="like"] svg`). */
+    ctx?: string;
+    /** Prefixes of the site's own path data for this icon, for icons without a container hook. */
+    sig?: readonly string[];
+    group: IconGroup;
+    /** Needed for its group to be drawn at all (a rail never shows half ours, half the site's). */
+    core?: boolean;
+};
+export type IconTable = Partial<Record<IconName, IconMatcher>>;
+/** Selectors of the `<svg>` boxes of one icon. */
+export declare function iconSelectors(matcher: IconMatcher): string[];
+export type IconContext = {
+    colors: RoleColors | null;
+    /** Attribute on `<html>` that lists the groups that are on (`data-wb-icons="nav actions"`); absent: every group draws. */
+    gate?: string;
+    /** The owner lets themes and packs change icons (default: yes). */
+    allowed?: boolean;
+};
+/**
+ * CSS that draws `pack` over a site's icons. One rule per glyph the pack has and the site's table
+ * knows, inside guards: forced colors remove backgrounds (a masked icon would vanish) and an engine
+ * without masks would paint solid squares.
+ */
+export declare function compileIcons(pack: IconPack | null, theme: ThemeIcons | null | undefined, table: IconTable, ctx: IconContext): string;
+/** The groups of `table` whose core icons are all on the page (`has(selector)` says whether one matches). Empty table entries count as present. */
+export declare function iconGroupsPresent(table: IconTable, has: (selector: string) => boolean): IconGroup[];