waybetter 0.1.1 → 0.6.0

package/dist/runtime/themeSchema.js

@@ -0,0 +1,150 @@
+// The JSON Schema of a theme's structure groups and of an icon pack, generated from the same tables
+// the sanitizers use (themeComponents.ts, themeVariants.ts, themeDecor.ts, themeIcons.ts), so a range
+// or a word exists in one place. `theme.schema.json` and `icons.schema.json` in the `waybetter`
+// package are written from here (`scripts/theme-schema.mjs`); a test fails when they are stale. Pure.
+import { ACTION_NAMES, AVATAR_SHAPES, BORDER_STYLES, CASES, COLOR_ROLES, COMPONENTS, COMPONENT_IDS, CORNERS, PRESETS, SHADOWS, TOKEN_LIMITS, } from "./themeComponents.js";
+import { CHROME_KINDS, DIVIDER_STYLES, LINK_UNDERLINES, MOTION_CURVES, RING_STYLES } from "./themeDecor.js";
+import { ICON_LABEL_NAMES, ICON_LIMITS, ICON_NAMES, PATH_GRAMMAR } from "./themeIcons.js";
+import { VARIANT_AXES, VARIANT_AXIS_NAMES } from "./themeVariants.js";
+const range = ([minimum, maximum], type = 'number') => ({ type, minimum, maximum });
+const words = (values) => ({ enum: [...values] });
+const closed = (properties, extra = {}) => ({ type: 'object', additionalProperties: false, properties, ...extra });
+/** Schema-side guard for words written into CSS strings (the sanitizer's allow-list is stricter: letters, digits and a little punctuation). */
+const LABEL_PATTERN = String.raw `^[^\u0000-\u001f"\\<>&{};'` + '`]+$';
+const role = { $ref: '#/$defs/role' };
+const hex = { $ref: '#/$defs/hex' };
+// Fills and states come in four kinds (with or without glass, with or without a gradient); each is one shared definition.
+const kind = (def) => `${def.glass ? 'Glass' : ''}${def.gradient ? 'Gradient' : ''}`;
+function fillDef(glass, gradient) {
+    const options = [role, { const: 'transparent' }];
+    if (glass)
+        options.push({ const: 'glass' });
+    if (gradient)
+        options.push(closed({ from: role, to: role, angle: range(TOKEN_LIMITS.angle) }, { required: ['from', 'to'] }));
+    return { oneOf: options };
+}
+const stateDef = (name) => closed({
+    fill: { $ref: `#/$defs/fill${name}` }, text: role, borderColor: role, shadow: { $ref: '#/$defs/shadow' }, lift: range(TOKEN_LIMITS.lift), scale: range(TOKEN_LIMITS.scale), underline: { type: 'boolean' },
+});
+const fill = (def) => ({ $ref: `#/$defs/fill${kind(def)}` });
+const state = (def) => ({ $ref: `#/$defs/state${kind(def)}` });
+function component(def, id) {
+    const properties = {
+        radius: { oneOf: [range(TOKEN_LIMITS.radius), { const: 'pill' }] },
+        borderWidth: range(TOKEN_LIMITS.borderWidth), borderStyle: words(BORDER_STYLES), borderColor: role,
+        fill: fill(def), text: role,
+        padX: range(TOKEN_LIMITS.padX), padY: range(TOKEN_LIMITS.padY), gap: range(TOKEN_LIMITS.gap),
+        shadow: { $ref: '#/$defs/shadow' }, hover: state(def), active: state(def), focus: state(def),
+    };
+    if (def.presets)
+        properties.preset = words(Object.keys(PRESETS[def.presets]));
+    for (const key of ['height', 'width', 'size', 'maxHeight', 'fontSize'])
+        if (def[key])
+            properties[key] = range(def[key]);
+    if (def.text || def.fontSize) {
+        properties.font = { $ref: '#/$defs/fontRoleName' };
+        properties.weight = range(TOKEN_LIMITS.weight);
+        if (id !== 'postText')
+            properties.case = words(CASES);
+        properties.tracking = range(TOKEN_LIMITS.tracking);
+        properties.leading = range(TOKEN_LIMITS.leading);
+    }
+    if (def.shape)
+        properties.shape = words(AVATAR_SHAPES);
+    if (def.corner)
+        properties.corner = words(CORNERS);
+    if (def.visible)
+        properties.visible = { type: 'boolean' };
+    return closed(properties);
+}
+const glyph = {
+    oneOf: [
+        closed({ d: { $ref: '#/$defs/pathData' }, rule: { const: 'evenodd' }, stroke: { type: 'boolean' } }, { required: ['d'] }),
+        closed({
+            layers: {
+                type: 'array', minItems: 1, maxItems: ICON_LIMITS.layers,
+                items: closed({ d: { $ref: '#/$defs/pathData' }, fill: { oneOf: [role, hex, closed({ from: hex, to: hex }, { required: ['from', 'to'] })] }, opacity: range([0, 1]), rule: { const: 'evenodd' } }, { required: ['d', 'fill'] }),
+            },
+        }, { required: ['layers'] }),
+        closed({ png: { type: 'string', maxLength: ICON_LIMITS.pngChars + 22, pattern: '^data:image/png;base64,[A-Za-z0-9+/]+={0,2}$' }, pixel: { type: 'boolean' } }, { required: ['png'] }),
+    ],
+};
+const iconStyle = closed({ stroke: range([1, 2.5]), cap: words(['round', 'square', 'butt']), join: words(['round', 'miter', 'bevel']), scale: range([0.8, 1.25]) });
+const symbols = closed({ like: words(['heart', 'star', 'custom']), separator: words(['dot', 'bullet', 'slash', 'dash', 'pipe', 'none']) });
+const labels = closed(Object.fromEntries(ICON_LABEL_NAMES.map(name => [name, { type: 'string', minLength: 1, maxLength: ICON_LIMITS.labelChars, pattern: LABEL_PATTERN }])));
+const glyphs = (maxProperties) => closed(Object.fromEntries(ICON_NAMES.map(name => [name, { $ref: '#/$defs/glyph' }])), { maxProperties });
+/** `$defs` shared by the structure groups and the pack schema. */
+export const structureDefs = () => ({
+    role: { description: 'A color role of the theme. Components never carry a color literal.', ...words(COLOR_ROLES) },
+    fontRoleName: words(['interface', 'post', 'heading', 'numbers', 'mono', 'chrome', 'dialog']),
+    shadow: words(SHADOWS),
+    ...Object.fromEntries([[false, false], [true, false], [false, true], [true, true]].flatMap(([glass, gradient]) => {
+        const name = `${glass ? 'Glass' : ''}${gradient ? 'Gradient' : ''}`;
+        return [[`fill${name}`, fillDef(glass, gradient)], [`state${name}`, stateDef(name)]];
+    })),
+    pathData: { type: 'string', minLength: 1, maxLength: ICON_LIMITS.pathChars, pattern: PATH_GRAMMAR.source.replace(/\{1,4000\}\$$/, '+$') },
+    glyph,
+});
+/** The properties a theme document gains: `components`, `variants`, `decor`, `icons`. */
+export function structureProperties() {
+    return {
+        components: {
+            description: 'How each piece of the site is built. Every token is optional; a missing token changes nothing.',
+            ...closed(Object.fromEntries(COMPONENT_IDS.map(id => [id, component(COMPONENTS[id], id)]))),
+        },
+        variants: {
+            description: 'Structural choices. The first option of each axis is the site\'s own layout.',
+            ...closed(Object.fromEntries(VARIANT_AXIS_NAMES.map(axis => [axis, words(VARIANT_AXES[axis])]))),
+        },
+        decor: {
+            description: 'Lines, bars, focus ring, selection, scrollbars, link underlines, motion.',
+            ...closed({
+                dividers: closed({ style: words(DIVIDER_STYLES), color: role, width: range([0, 3]) }, { required: ['style'] }),
+                chrome: closed({ kind: words(CHROME_KINDS), title: { type: 'string', maxLength: 24 } }, { required: ['kind'] }),
+                focusRing: closed({ width: range([2, 4]), style: words(RING_STYLES), color: role, offset: range([0, 4]) }),
+                selection: closed({ fill: role, text: role }, { required: ['fill', 'text'] }),
+                scrollbar: closed({ width: words(['auto', 'thin']), thumb: role, track: role, style: words(['flat', 'classic']) }),
+                links: closed({ underline: words(LINK_UNDERLINES) }, { required: ['underline'] }),
+                motion: closed({ duration: range([0, 400]), curve: words(MOTION_CURVES), press: range([0.96, 1]) }),
+            }),
+        },
+        icons: {
+            description: 'The icon pack this theme suggests (by id), with small adjustments. A whole pack is its own document (icons.schema.json).',
+            ...closed({ pack: { type: 'string', pattern: '^[a-z0-9-]{1,40}$' }, style: iconStyle, overrides: glyphs(ICON_LIMITS.overrides), symbols, labels }),
+        },
+    };
+}
+/** `colors.actions`. */
+export const actionColorsSchema = () => ({
+    description: 'Colors of a set action (liked, reposted, bookmarked) and of the reply hover. Absent: the site\'s own.',
+    ...closed(Object.fromEntries(ACTION_NAMES.map(name => [name, hex]))),
+});
+/** The JSON Schema of an icon pack document (`*.icons.json`). */
+export function iconPackSchema(id) {
+    return {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        $id: id,
+        title: 'wayBetter icon pack',
+        description: 'Glyphs by semantic name, drawn over a site\'s own icons. Path data, colored layers of path data, or small PNGs: never an SVG document.',
+        type: 'object',
+        required: ['id', 'name', 'license', 'glyphs'],
+        additionalProperties: false,
+        properties: {
+            $schema: { type: 'string' },
+            id: { type: 'string', pattern: '^[a-z0-9-]{1,40}$' },
+            name: { type: 'string', minLength: 1, maxLength: 60 },
+            description: { type: 'string', maxLength: 200 },
+            author: { type: 'string', maxLength: 60 },
+            license: { type: 'string', minLength: 1, maxLength: 60, description: 'SPDX id, "own" for the author\'s own drawings, or a plain name for artwork under other terms.' },
+            source: { type: 'string', maxLength: 200 },
+            credits: { type: 'string', maxLength: 400 },
+            version: { const: 1 },
+            style: iconStyle,
+            glyphs: { ...glyphs(ICON_LIMITS.names), minProperties: 1 },
+            symbols,
+            labels,
+        },
+        $defs: { hex: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' }, ...structureDefs() },
+    };
+}
+//# sourceMappingURL=themeSchema.js.map

package/dist/runtime/themeSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"themeSchema.js","sourceRoot":"","sources":["../../../runtime/src/themeSchema.ts"],"names":[],"mappings":"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","sourcesContent":["// The JSON Schema of a theme's structure groups and of an icon pack, generated from the same tables\n// the sanitizers use (themeComponents.ts, themeVariants.ts, themeDecor.ts, themeIcons.ts), so a range\n// or a word exists in one place. `theme.schema.json` and `icons.schema.json` in the `waybetter`\n// package are written from here (`scripts/theme-schema.mjs`); a test fails when they are stale. Pure.\n\nimport {\n  ACTION_NAMES, AVATAR_SHAPES, BORDER_STYLES, CASES, COLOR_ROLES, COMPONENTS, COMPONENT_IDS, CORNERS, PRESETS, SHADOWS, TOKEN_LIMITS,\n} from './themeComponents.ts';\nimport { CHROME_KINDS, DIVIDER_STYLES, LINK_UNDERLINES, MOTION_CURVES, RING_STYLES } from './themeDecor.ts';\nimport { ICON_LABEL_NAMES, ICON_LIMITS, ICON_NAMES, PATH_GRAMMAR } from './themeIcons.ts';\nimport { VARIANT_AXES, VARIANT_AXIS_NAMES } from './themeVariants.ts';\n\ntype Json = Record<string, unknown>;\nconst range = ([minimum, maximum]: readonly [number, number], type = 'number'): Json => ({ type, minimum, maximum });\nconst words = (values: readonly string[]): Json => ({ enum: [...values] });\nconst closed = (properties: Json, extra: Json = {}): Json => ({ type: 'object', additionalProperties: false, properties, ...extra });\n/** Schema-side guard for words written into CSS strings (the sanitizer's allow-list is stricter: letters, digits and a little punctuation). */\nconst LABEL_PATTERN = String.raw`^[^\\u0000-\\u001f\"\\\\<>&{};'` + '`]+$';\nconst role = { $ref: '#/$defs/role' };\nconst hex = { $ref: '#/$defs/hex' };\n\ntype Def = { parent?: string; text?: boolean; height?: readonly [number, number]; width?: readonly [number, number]; size?: readonly [number, number]; maxHeight?: readonly [number, number]; fontSize?: readonly [number, number]; shape?: boolean; corner?: boolean; visible?: boolean; glass?: boolean; gradient?: boolean; presets?: keyof typeof PRESETS };\n\n// Fills and states come in four kinds (with or without glass, with or without a gradient); each is one shared definition.\nconst kind = (def: Def) => `${def.glass ? 'Glass' : ''}${def.gradient ? 'Gradient' : ''}`;\nfunction fillDef(glass: boolean, gradient: boolean): Json {\n  const options: Json[] = [role, { const: 'transparent' }];\n  if (glass) options.push({ const: 'glass' });\n  if (gradient) options.push(closed({ from: role, to: role, angle: range(TOKEN_LIMITS.angle) }, { required: ['from', 'to'] }));\n  return { oneOf: options };\n}\nconst stateDef = (name: string): Json => closed({\n  fill: { $ref: `#/$defs/fill${name}` }, text: role, borderColor: role, shadow: { $ref: '#/$defs/shadow' }, lift: range(TOKEN_LIMITS.lift), scale: range(TOKEN_LIMITS.scale), underline: { type: 'boolean' },\n});\nconst fill = (def: Def): Json => ({ $ref: `#/$defs/fill${kind(def)}` });\nconst state = (def: Def): Json => ({ $ref: `#/$defs/state${kind(def)}` });\n\nfunction component(def: Def, id: string): Json {\n  const properties: Json = {\n    radius: { oneOf: [range(TOKEN_LIMITS.radius), { const: 'pill' }] },\n    borderWidth: range(TOKEN_LIMITS.borderWidth), borderStyle: words(BORDER_STYLES), borderColor: role,\n    fill: fill(def), text: role,\n    padX: range(TOKEN_LIMITS.padX), padY: range(TOKEN_LIMITS.padY), gap: range(TOKEN_LIMITS.gap),\n    shadow: { $ref: '#/$defs/shadow' }, hover: state(def), active: state(def), focus: state(def),\n  };\n  if (def.presets) properties.preset = words(Object.keys(PRESETS[def.presets]));\n  for (const key of ['height', 'width', 'size', 'maxHeight', 'fontSize'] as const) if (def[key]) properties[key] = range(def[key]!);\n  if (def.text || def.fontSize) {\n    properties.font = { $ref: '#/$defs/fontRoleName' };\n    properties.weight = range(TOKEN_LIMITS.weight);\n    if (id !== 'postText') properties.case = words(CASES);\n    properties.tracking = range(TOKEN_LIMITS.tracking);\n    properties.leading = range(TOKEN_LIMITS.leading);\n  }\n  if (def.shape) properties.shape = words(AVATAR_SHAPES);\n  if (def.corner) properties.corner = words(CORNERS);\n  if (def.visible) properties.visible = { type: 'boolean' };\n  return closed(properties);\n}\n\nconst glyph: Json = {\n  oneOf: [\n    closed({ d: { $ref: '#/$defs/pathData' }, rule: { const: 'evenodd' }, stroke: { type: 'boolean' } }, { required: ['d'] }),\n    closed({\n      layers: {\n        type: 'array', minItems: 1, maxItems: ICON_LIMITS.layers,\n        items: closed({ d: { $ref: '#/$defs/pathData' }, fill: { oneOf: [role, hex, closed({ from: hex, to: hex }, { required: ['from', 'to'] })] }, opacity: range([0, 1]), rule: { const: 'evenodd' } }, { required: ['d', 'fill'] }),\n      },\n    }, { required: ['layers'] }),\n    closed({ png: { type: 'string', maxLength: ICON_LIMITS.pngChars + 22, pattern: '^data:image/png;base64,[A-Za-z0-9+/]+={0,2}$' }, pixel: { type: 'boolean' } }, { required: ['png'] }),\n  ],\n};\nconst iconStyle = closed({ stroke: range([1, 2.5]), cap: words(['round', 'square', 'butt']), join: words(['round', 'miter', 'bevel']), scale: range([0.8, 1.25]) });\nconst symbols = closed({ like: words(['heart', 'star', 'custom']), separator: words(['dot', 'bullet', 'slash', 'dash', 'pipe', 'none']) });\nconst labels = closed(Object.fromEntries(ICON_LABEL_NAMES.map(name => [name, { type: 'string', minLength: 1, maxLength: ICON_LIMITS.labelChars, pattern: LABEL_PATTERN }])));\nconst glyphs = (maxProperties: number): Json => closed(Object.fromEntries(ICON_NAMES.map(name => [name, { $ref: '#/$defs/glyph' }])), { maxProperties });\n\n/** `$defs` shared by the structure groups and the pack schema. */\nexport const structureDefs = (): Json => ({\n  role: { description: 'A color role of the theme. Components never carry a color literal.', ...words(COLOR_ROLES) },\n  fontRoleName: words(['interface', 'post', 'heading', 'numbers', 'mono', 'chrome', 'dialog']),\n  shadow: words(SHADOWS),\n  ...Object.fromEntries([[false, false], [true, false], [false, true], [true, true]].flatMap(([glass, gradient]) => {\n    const name = `${glass ? 'Glass' : ''}${gradient ? 'Gradient' : ''}`;\n    return [[`fill${name}`, fillDef(glass!, gradient!)], [`state${name}`, stateDef(name)]];\n  })),\n  pathData: { type: 'string', minLength: 1, maxLength: ICON_LIMITS.pathChars, pattern: PATH_GRAMMAR.source.replace(/\\{1,4000\\}\\$$/, '+$') },\n  glyph,\n});\n\n/** The properties a theme document gains: `components`, `variants`, `decor`, `icons`. */\nexport function structureProperties(): Json {\n  return {\n    components: {\n      description: 'How each piece of the site is built. Every token is optional; a missing token changes nothing.',\n      ...closed(Object.fromEntries(COMPONENT_IDS.map(id => [id, component(COMPONENTS[id] as Def, id)]))),\n    },\n    variants: {\n      description: 'Structural choices. The first option of each axis is the site\\'s own layout.',\n      ...closed(Object.fromEntries(VARIANT_AXIS_NAMES.map(axis => [axis, words(VARIANT_AXES[axis])]))),\n    },\n    decor: {\n      description: 'Lines, bars, focus ring, selection, scrollbars, link underlines, motion.',\n      ...closed({\n        dividers: closed({ style: words(DIVIDER_STYLES), color: role, width: range([0, 3]) }, { required: ['style'] }),\n        chrome: closed({ kind: words(CHROME_KINDS), title: { type: 'string', maxLength: 24 } }, { required: ['kind'] }),\n        focusRing: closed({ width: range([2, 4]), style: words(RING_STYLES), color: role, offset: range([0, 4]) }),\n        selection: closed({ fill: role, text: role }, { required: ['fill', 'text'] }),\n        scrollbar: closed({ width: words(['auto', 'thin']), thumb: role, track: role, style: words(['flat', 'classic']) }),\n        links: closed({ underline: words(LINK_UNDERLINES) }, { required: ['underline'] }),\n        motion: closed({ duration: range([0, 400]), curve: words(MOTION_CURVES), press: range([0.96, 1]) }),\n      }),\n    },\n    icons: {\n      description: 'The icon pack this theme suggests (by id), with small adjustments. A whole pack is its own document (icons.schema.json).',\n      ...closed({ pack: { type: 'string', pattern: '^[a-z0-9-]{1,40}$' }, style: iconStyle, overrides: glyphs(ICON_LIMITS.overrides), symbols, labels }),\n    },\n  };\n}\n\n/** `colors.actions`. */\nexport const actionColorsSchema = (): Json => ({\n  description: 'Colors of a set action (liked, reposted, bookmarked) and of the reply hover. Absent: the site\\'s own.',\n  ...closed(Object.fromEntries(ACTION_NAMES.map(name => [name, hex]))),\n});\n\n/** The JSON Schema of an icon pack document (`*.icons.json`). */\nexport function iconPackSchema(id: string): Json {\n  return {\n    $schema: 'https://json-schema.org/draft/2020-12/schema',\n    $id: id,\n    title: 'wayBetter icon pack',\n    description: 'Glyphs by semantic name, drawn over a site\\'s own icons. Path data, colored layers of path data, or small PNGs: never an SVG document.',\n    type: 'object',\n    required: ['id', 'name', 'license', 'glyphs'],\n    additionalProperties: false,\n    properties: {\n      $schema: { type: 'string' },\n      id: { type: 'string', pattern: '^[a-z0-9-]{1,40}$' },\n      name: { type: 'string', minLength: 1, maxLength: 60 },\n      description: { type: 'string', maxLength: 200 },\n      author: { type: 'string', maxLength: 60 },\n      license: { type: 'string', minLength: 1, maxLength: 60, description: 'SPDX id, \"own\" for the author\\'s own drawings, or a plain name for artwork under other terms.' },\n      source: { type: 'string', maxLength: 200 },\n      credits: { type: 'string', maxLength: 400 },\n      version: { const: 1 },\n      style: iconStyle,\n      glyphs: { ...glyphs(ICON_LIMITS.names), minProperties: 1 },\n      symbols,\n      labels,\n    },\n    $defs: { hex: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' }, ...structureDefs() },\n  };\n}\n"]}

package/dist/runtime/themeSpec.d.ts

@@ -0,0 +1,259 @@
+import { type FontRoleName } from './themeApi.ts';
+import { type ActionColors, type ThemeComponents } from './themeComponents.ts';
+import { type ThemeDecor } from './themeDecor.ts';
+import { type ThemeIcons } from './themeIcons.ts';
+import { type ThemeVariants } from './themeVariants.ts';
+export { FONT_ROLE_NAMES } from './themeApi.ts';
+export type { FontRoleName } from './themeApi.ts';
+export type Role = 'bg' | 'surface' | 'elevated' | 'border' | 'text' | 'muted' | 'accent';
+/** The site's filled primary button (X: "Post"/"Follow"): an `inverse` background with an `onInverse` label. */
+export type ButtonRole = 'inverse' | 'onInverse';
+export type Palette = Record<Role, string> & Partial<Record<ButtonRole, string>>;
+/**
+ * `page` is the canvas behind the site's columns (defaults to `bg`); the columns stay on `bg`.
+ * `actions` are the colors of a set action (liked, reposted, bookmarked) and of the reply hover;
+ * absent, the site's own action colors stay.
+ */
+export type ThemeColors = Palette & {
+    page?: string;
+    actions?: ActionColors;
+};
+export type Density = 'compact' | 'default' | 'comfortable';
+export type AvatarShape = 'circle' | 'rounded' | 'square';
+export type Pattern = 'dots' | 'grid' | 'diagonal' | 'scanlines' | 'paper' | 'clouds';
+export type Background = {
+    kind: 'none';
+} | {
+    kind: 'gradient';
+    from: string;
+    to: string;
+    angle: number;
+    glow?: string;
+} | {
+    kind: 'pattern';
+    pattern: Pattern;
+    ink: string;
+    opacity: number;
+    size: number;
+} | {
+    kind: 'image';
+    url: string;
+    fit: 'cover' | 'tile';
+    dim: number;
+};
+/**
+ * One role's font (roles: themeApi.ts `FONT_ROLE_NAMES`). `family` is a font stack; empty keeps the
+ * inherited family and only changes the rest. `source: "google"` says the first family comes from
+ * Google Fonts (downloaded once, asked first when a theme is imported, loaded from bytes). `weight`
+ * (100-900), `size` (0.75-1.5, relative to the site's size), `tracking` (em) and `tabular` figures
+ * are optional; the interface role takes only `family`/`source` (its size, weights and tracking are
+ * `scale`, `weight`, `bold` and `tracking` of the whole theme).
+ */
+export type FontRoleSpec = {
+    family: string[];
+    source?: 'google';
+    weight?: number;
+    size?: number;
+    tracking?: number;
+    tabular?: boolean;
+};
+export type FontRole = 'inherit' | FontRoleSpec;
+export type FontRoles = Record<FontRoleName, FontRole>;
+export type FontSpec = {
+    /**
+     * Interface font stack (replaces the site's own font everywhere). Empty keeps the site's.
+     * Shorthand kept for older theme files and older apps: it always equals `roles.interface`'s family.
+     */
+    family: string[];
+    /** Post text stack (e.g. a serif reading face); shorthand of `roles.post`'s family. */
+    tweet: string[];
+    /** Which font goes where. Every role inherits from `interface` unless it says otherwise. */
+    roles: FontRoles;
+    /** Multiplies the site's pixel font sizes (0.85-1.2). */
+    scale: number;
+    /** Regular weight (300-500) and bold weight (500-800) that replace the site's 400/700. */
+    weight: number;
+    bold: number;
+    /** Letter spacing in em (-0.03-0.06). */
+    tracking: number;
+    /** Line height multiplier for post text (0 keeps the site's). */
+    leading: number;
+};
+export type ShapeSpec = {
+    radius: number;
+    button: number;
+    avatar: AvatarShape;
+};
+export type LayoutSpec = {
+    column: number;
+    sidebar: number;
+    density: Density;
+    cards: boolean;
+    frame: boolean;
+};
+export type EffectsSpec = {
+    motion: number;
+    hover: 'none' | 'tint' | 'lift' | 'glow';
+    shadow: 'none' | 'soft' | 'deep';
+    crt: boolean;
+};
+export type ThemeSpec = {
+    id: string;
+    name: string;
+    description: string;
+    author: string;
+    version: 1;
+    /** Which way the theme leans; used for scrollbars/form controls and previews. */
+    mode: 'light' | 'dark' | 'auto';
+    /** null keeps the site's own colors (X: Default / Dim / Lights out). */
+    colors: ThemeColors | null;
+    font: FontSpec;
+    shape: ShapeSpec;
+    layout: LayoutSpec;
+    background: Background;
+    effects: EffectsSpec;
+    /** Free-form CSS appended last (owner-trusted, like Custom CSS). */
+    css: string;
+    /** How each piece of the site is built (themeComponents.ts). */
+    components?: ThemeComponents;
+    /** Structural choices: where the navigation sits, how a post is laid out (themeVariants.ts). */
+    variants?: ThemeVariants;
+    /** Lines, bars, focus ring, selection, scrollbars, motion (themeDecor.ts). */
+    decor?: ThemeDecor;
+    /** Which icon pack the theme suggests, with small adjustments (themeIcons.ts). */
+    icons?: ThemeIcons;
+};
+/** Panel overrides: any group may be partially overridden on top of the selected theme. */
+export type ThemeOverrides = {
+    colors?: Partial<ThemeColors>;
+    /** `roles` is merged role by role (a named role replaces that role only). */
+    font?: Partial<Omit<FontSpec, 'roles'>> & {
+        roles?: Partial<FontRoles>;
+    };
+    shape?: Partial<ShapeSpec>;
+    layout?: Partial<LayoutSpec>;
+    background?: Background;
+    effects?: Partial<EffectsSpec>;
+    /** The theme's own CSS as edited in the panel (replaces the theme document's `css`). */
+    css?: {
+        text: string;
+    };
+    /** The owner's say on a theme's layout suggestions, axis by axis (an axis set to the site's own option switches it off). */
+    variants?: Record<string, string>;
+};
+export declare const BASE_SHAPE: ShapeSpec;
+export declare const INHERIT_ROLES: FontRoles;
+/** A font spec from the interface/post stacks alone (every other role inherits). */
+export declare const withRoles: (font: Omit<FontSpec, "roles">) => FontSpec;
+export declare const BASE_FONT: FontSpec;
+export declare const BASE_LAYOUT: LayoutSpec;
+export declare const BASE_EFFECTS: EffectsSpec;
+/** The system UI stack themes put after their own sans-serif families. */
+export declare const SYSTEM_SANS: string[];
+export declare const isHex: (value: unknown) => value is string;
+/** `#rrggbb` + alpha as `rgba()`. */
+export declare const rgba: (hex: string, alpha: number) => string;
+/** Moves `color` toward black or white until it reaches `ratio` against every surface. */
+export declare function reach(color: string, surfaces: string[], ratio: number): string;
+/**
+ * Guarantees legibility for any palette (built-in, imported or overridden): text, secondary text
+ * and links reach WCAG AA (4.5:1) on every surface, including the page canvas, and the site's filled
+ * button keeps a readable label and stands out from the page (3:1).
+ */
+export declare function ensureContrast<T extends Palette & {
+    page?: string;
+    actions?: ActionColors;
+}>(colors: T): T;
+export declare const MAX_IMAGE_CHARS = 1100000;
+export declare const MAX_CSS_CHARS = 60000;
+export declare function sanitizeFonts(value: unknown): string[];
+export declare function sanitizeBackground(value: unknown): Background;
+/** Bounds of a role's own settings (the JSON Schema says the same; tested). */
+export declare const ROLE_LIMITS: {
+    readonly weight: readonly [100, 900];
+    readonly size: readonly [0.75, 1.5];
+    readonly tracking: readonly [-0.05, 0.1];
+};
+/** One role from JSON: "inherit", or a stack with optional extras (clamped; unknown keys dropped). */
+export declare function sanitizeFontRole(value: unknown, role: FontRoleName): FontRole;
+/** A role with a new family, keeping its other settings (and its Google source only for the same font). */
+export declare function withFamily(role: FontRole, family: string[], source?: 'google'): FontRole;
+export declare const slug: (value: string) => string;
+/** Any JSON to a complete, safe theme. Missing groups fall back to the schema's defaults. */
+export declare function sanitizeSpec(input: unknown): ThemeSpec;
+/** True when a theme carries any of the structure groups (components, variants, decoration, icons). */
+export declare const hasStructure: (theme: ThemeSpec) => boolean;
+/** Parses an imported file; errors are human-readable. */
+export declare function parseThemeJson(json: string): {
+    theme: ThemeSpec;
+    warnings: string[];
+} | {
+    error: string;
+};
+/** Applies panel overrides (and an accent) on top of a theme. Colors are then made legible. */
+export declare function applyOverrides(theme: ThemeSpec, overrides?: ThemeOverrides, accent?: string | null): ThemeSpec;
+/** True when a theme changes nothing about the site (the site's own look without overrides). */
+export declare function isNeutral(theme: ThemeSpec): boolean;
+/** Bundled families and the names they are registered under (shell: @fontsource; site pages: FontFace, fonts.ts). */
+export declare const BUNDLED_FONTS: Record<string, string>;
+export declare function fontStack(names: string[]): string;
+/** Roles that are drawn inside the site's page (chrome is wayBetter's own window). */
+export declare const PAGE_ROLES: FontRoleName[];
+/** Bundled families (Geist, Geist Mono) a theme names in the site's page. */
+export declare const bundledFontsUsed: (theme: ThemeSpec, roles?: readonly FontRoleName[]) => string[];
+/** Google Fonts families a theme uses (`source: "google"`), for the given roles. */
+export declare function googleFontsUsed(theme: ThemeSpec, roles?: readonly FontRoleName[]): string[];
+/** A role resolved to what is drawn: the stack actually used and its settings. */
+export type ResolvedFontRole = {
+    /** CSS `font-family`. */
+    stack: string;
+    /** The families of that stack (empty when it is the site's or app's own font). */
+    family: string[];
+    /** True when the family comes from another role (or the site/app default). */
+    inherited: boolean;
+    /** A Google Fonts family the stack starts with. */
+    google: string | null;
+    weight: number | null;
+    size: number;
+    tracking: number | null;
+    tabular: boolean;
+};
+export type ResolvedFontRoles = Record<FontRoleName, ResolvedFontRole>;
+/**
+ * Every role resolved. `site` is the stack an inheriting interface uses: the site's own font in its
+ * page, wayBetter's own UI font in the shell. Every other role inherits the interface, except that an
+ * inheriting `mono` keeps a monospaced stack (`mono`: themeApi.ts `MONO_FAMILIES`, code rarely suits
+ * an interface font).
+ */
+export declare function resolveFontRoles(font: FontSpec, site: string, mono?: string): ResolvedFontRoles;
+/**
+ * A named font stack offered by the panel's pickers. `key` names its translated label
+ * (`wb.fonts.choice.*`); `label` is the English one. A site adds its own font first (X: "X's Chirp",
+ * an empty family that keeps the site's type).
+ */
+export type FontChoice = {
+    id: string;
+    label: string;
+    key?: string;
+    family: string[];
+};
+/** Font choices offered by the panel; any installed family can also be named in theme JSON. */
+export declare const FONT_CHOICES: FontChoice[];
+/** The choice whose stack is exactly `family` in `choices`, or `custom`. */
+export declare const fontChoiceOf: (family: string[], choices?: readonly FontChoice[]) => string;
+/**
+ * The site's page background. A site's `<html>` and `<body>` are often one viewport tall while the
+ * content overflows them (X's timeline), so a background painted on both had `<body>` paint its own
+ * copy over its box, which scrolls away: after a partial scroll the gradient/glow showed only below a hard seam. Now
+ * `<html>` holds the plain page color, `<body>` is transparent (beating, by specificity, the
+ * palette's `html,body{background-color}` and its `[style^="background-color: …"]` remap of the
+ * inline color X puts on `<body>`) and every layer sits on one viewport-sized fixed
+ * layer behind all of the page (`z-index:-1` in the root stacking context), with no `fixed` attachments.
+ */
+export declare function pageBackgroundCss(background: Background, page: string): string[];
+/**
+ * CSS `background` layers for the page canvas (behind the site's columns). `attach` keeps the `fixed`
+ * attachments for a box that scrolls (the Theme Builder preview); the site's page gets the layers without
+ * them, on one viewport-sized fixed layer (`pageBackgroundCss`).
+ */
+export declare function backgroundLayers(background: Background, page: string, attach?: boolean): string;