@texuli/deck 0.0.0-stage → 0.5.0

package/dist/model/backgrounds/contrast.js

@@ -0,0 +1,186 @@
+/**
+ * WCAG 2.x contrast math for deck backgrounds, on sRGB hex colors only.
+ *
+ * Every function here is pure and framework-free. Inputs are `#rgb` or
+ * `#rrggbb` (and, through `opaqueColor`, `rgb()`/`rgba()` composited over a
+ * base); `oklch()` and other color spaces are converted by the caller (the
+ * stage reads them from `@texuli/tokens`). Outputs are always lowercase
+ * `#rrggbb`, so a computed color can go into CSS without escaping.
+ */
+/** WCAG AA for normal-size body text: the floor every background guarantees. */
+export const DECK_TEXT_CONTRAST_MIN = 4.5;
+/** Scrim alphas move in steps of 0.05 … */
+export const DECK_SCRIM_STEP = 0.05;
+/** … up to 0.9 (an image or video always stays faintly visible). */
+export const DECK_SCRIM_MAX = 0.9;
+/** Light ink and the scrim under it; dark ink and the scrim under it. */
+export const PURE_LIGHT = '#ffffff';
+export const PURE_DARK = '#000000';
+const HEX6 = /^#([0-9a-f]{6})$/i;
+const HEX3 = /^#([0-9a-f]{3})$/i;
+/** `#rgb` or `#rrggbb` (any case, surrounding spaces ignored) as 0–255 channels; anything else is `null`. */
+export function parseHexColor(color) {
+    if (typeof color !== 'string' || color.length > 16)
+        return null;
+    const value = color.trim();
+    let hex;
+    const long = HEX6.exec(value);
+    if (long)
+        hex = long[1];
+    else {
+        const short = HEX3.exec(value);
+        if (!short)
+            return null;
+        hex = [...short[1]].map((c) => c + c).join('');
+    }
+    return [0, 2, 4].map((i) => Number.parseInt(hex.slice(i, i + 2), 16));
+}
+const byte = (n) => Math.round(Math.min(255, Math.max(0, n)))
+    .toString(16)
+    .padStart(2, '0');
+/** Channels → lowercase `#rrggbb` (channels are clamped and rounded). */
+export function toHex(rgb) {
+    return `#${rgb.map(byte).join('')}`;
+}
+/** A hex color in its canonical form (`#rrggbb`, lowercase), or `null`. */
+export function normalizeHex(color) {
+    const rgb = parseHexColor(color);
+    return rgb ? toHex(rgb) : null;
+}
+/** sRGB → linear light (the IEC 61966-2-1 threshold; no 8-bit value differs from WCAG's 0.03928). */
+function linear(channel) {
+    const c = channel / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function requireHex(color, fn) {
+    const rgb = parseHexColor(color);
+    if (!rgb)
+        throw new TypeError(`${fn}(): expected a hex color, got ${JSON.stringify(color)}.`);
+    return rgb;
+}
+/** WCAG relative luminance (0 for black, 1 for white). Throws `TypeError` on a non-hex color. */
+export function relativeLuminance(color) {
+    const [r, g, b] = requireHex(color, 'relativeLuminance');
+    return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+/** WCAG contrast ratio, 1 to 21, order independent. Throws `TypeError` on a non-hex color. */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+    return (hi + 0.05) / (lo + 0.05);
+}
+/** `top` over `base` at `alpha` (0–1), composited in sRGB as browsers paint it. */
+export function compositeOver(base, top, alpha) {
+    const b = requireHex(base, 'compositeOver');
+    const t = requireHex(top, 'compositeOver');
+    const a = Number.isFinite(alpha) ? Math.min(1, Math.max(0, alpha)) : 0;
+    return toHex([0, 1, 2].map((i) => b[i] * (1 - a) + t[i] * a));
+}
+const RGB = /^rgba?\(\s*(\d{1,3})\s*[\s,]\s*(\d{1,3})\s*[\s,]\s*(\d{1,3})\s*(?:[,/]\s*(\d{0,3}(?:\.\d{1,6})?)(%?)\s*)?\)$/i;
+/**
+ * A palette color as an opaque hex: hex passes through (canonicalized),
+ * `rgb()`/`rgba()` is composited over `base` (dark-mode borders carry alpha).
+ * Anything else is `null`, so the contrast math never guesses at a color.
+ */
+export function opaqueColor(color, base) {
+    const hex = normalizeHex(color);
+    if (hex)
+        return hex;
+    if (typeof color !== 'string' || color.length > 64)
+        return null;
+    const match = RGB.exec(color.trim());
+    if (!match)
+        return null;
+    const rgb = [match[1], match[2], match[3]].map((n) => Math.min(255, Number(n)));
+    const raw = match[4];
+    let alpha = 1;
+    if (raw !== undefined && raw !== '') {
+        alpha = Number(raw) / (match[5] === '%' ? 100 : 1);
+        if (!Number.isFinite(alpha))
+            return null;
+    }
+    return compositeOver(base, toHex(rgb), alpha);
+}
+/** Points along a linear sRGB gradient: every stop and `perSegment - 1` points between each pair. */
+export function sampleGradient(stops, perSegment = 16) {
+    const steps = Math.max(1, Math.min(256, Math.floor(perSegment)));
+    const out = [];
+    stops.forEach((stop, i) => {
+        out.push(toHex(requireHex(stop, 'sampleGradient')));
+        const next = stops[i + 1];
+        if (next === undefined)
+            return;
+        for (let k = 1; k < steps; k++)
+            out.push(compositeOver(stop, next, k / steps));
+    });
+    return out;
+}
+/** The lowest contrast of `ink` over any of `backgrounds` (21 for an empty list). */
+export function worstContrast(ink, backgrounds) {
+    let worst = 21;
+    for (const background of backgrounds)
+        worst = Math.min(worst, contrastRatio(ink, background));
+    return worst;
+}
+/** Round to the scrim grid (0.05) without float noise. */
+const stepAlpha = (step) => Math.round(step * DECK_SCRIM_STEP * 100) / 100;
+const MAX_STEP = Math.round(DECK_SCRIM_MAX / DECK_SCRIM_STEP);
+/** The first scrim step at or above `alpha` (an author overlay is never weakened). */
+export function scrimStepFor(alpha) {
+    if (!Number.isFinite(alpha) || alpha <= 0)
+        return 0;
+    return Math.min(MAX_STEP, Math.ceil(alpha / DECK_SCRIM_STEP - 1e-9));
+}
+/**
+ * The lowest scrim (in 0.05 steps, from `minimumScrim` up to 0.9) under which
+ * `ink` reaches `minimum` over every background, or `null` when none does.
+ */
+export function inkWithScrim(tone, ink, backgrounds, minimumScrim = 0, minimum = DECK_TEXT_CONTRAST_MIN) {
+    const scrimColor = tone === 'light' ? PURE_DARK : PURE_LIGHT;
+    for (let step = scrimStepFor(minimumScrim); step <= MAX_STEP; step++) {
+        const alpha = stepAlpha(step);
+        const seen = alpha === 0 ? backgrounds : backgrounds.map((bg) => compositeOver(bg, scrimColor, alpha));
+        const contrast = worstContrast(ink, seen);
+        if (contrast >= minimum)
+            return { tone, ink, scrimColor, scrim: alpha, contrast };
+    }
+    return null;
+}
+/**
+ * The ink for a set of backgrounds. Each tone tries the theme ink first and
+ * pure white or black second; the choice needs the lightest scrim, then
+ * prefers the theme ink, then the higher contrast. Pure ink over a 0.9 scrim
+ * always clears AA (about 15:1 against any pixel), so a result always exists.
+ */
+export function chooseInk(backgrounds, inks, options = {}) {
+    const minimum = Math.max(DECK_TEXT_CONTRAST_MIN, Math.min(21, options.minimum ?? 0));
+    const tones = options.forced ? [options.forced] : ['light', 'dark'];
+    let best;
+    for (const tone of tones) {
+        const pure = tone === 'light' ? PURE_LIGHT : PURE_DARK;
+        const themeInk = normalizeHex(inks[tone]) ?? pure;
+        const candidates = themeInk === pure ? [pure] : [themeInk, pure];
+        for (const ink of candidates) {
+            const choice = inkWithScrim(tone, ink, backgrounds, options.minimumScrim ?? 0, minimum);
+            if (!choice)
+                continue;
+            const themed = ink !== pure;
+            const better = !best ||
+                choice.scrim < best.choice.scrim ||
+                (choice.scrim === best.choice.scrim &&
+                    ((themed && !best.themed) ||
+                        (themed === best.themed && choice.contrast > best.choice.contrast)));
+            if (better)
+                best = { choice, themed };
+        }
+    }
+    if (best)
+        return best.choice;
+    // Only reachable with a `minimum` above what a 0.9 scrim allows: report the strongest attempt.
+    const tone = options.forced ?? 'light';
+    const ink = tone === 'light' ? PURE_LIGHT : PURE_DARK;
+    const scrimColor = tone === 'light' ? PURE_DARK : PURE_LIGHT;
+    const seen = backgrounds.map((bg) => compositeOver(bg, scrimColor, DECK_SCRIM_MAX));
+    return { tone, ink, scrimColor, scrim: DECK_SCRIM_MAX, contrast: worstContrast(ink, seen) };
+}

package/dist/model/backgrounds/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Deck backgrounds (model v2 §3.5): presets, the spec schema, the resolver
+ * and the WCAG contrast math it relies on. Framework-free and dependency-free.
+ */
+export { type ChooseInkOptions, chooseInk, compositeOver, contrastRatio, DECK_SCRIM_MAX, DECK_SCRIM_STEP, DECK_TEXT_CONTRAST_MIN, type InkChoice, inkWithScrim, normalizeHex, opaqueColor, PURE_DARK, PURE_LIGHT, parseHexColor, type Rgb, relativeLuminance, sampleGradient, scrimStepFor, type TextTone, toHex, worstContrast, } from './contrast.js';
+export { DECK_BG_VAR_PREFIX, type DeckBackgroundCssVar, type DeckBackgroundLayer, type ResolveDeckBackgroundOptions, type ResolvedDeckBackground, resolveDeckBackground, } from './resolve.js';
+export { BACKGROUND_CODES, DECK_BACKGROUND_PRESET_IDS, DECK_BACKGROUND_PRESETS, DECK_GRADIENT_ANGLE, DECK_GRADIENT_IDS, DECK_GRADIENTS, DECK_MEDIA_FITS, DECK_MEDIA_POSITIONS, DECK_MEDIA_TONES, DECK_PALETTE_ROLES, DECK_PATTERNS, DECK_SOLID_TOKENS, DEFAULT_DECK_BACKGROUND, type DeckBackground, type DeckBackgroundKind, type DeckBackgroundPalette, type DeckBackgroundPresetId, type DeckBackgroundSpec, type DeckGradient, type DeckPaletteRole, type DeckPattern, type DeckSolidToken, deckBackground, deckBackgroundPreset, deckBackgroundSpec, HEX_COLOR_PATTERN, isDeckBackgroundPreset, } from './schema.js';

package/dist/model/backgrounds/index.js

@@ -0,0 +1,7 @@
+/**
+ * Deck backgrounds (model v2 §3.5): presets, the spec schema, the resolver
+ * and the WCAG contrast math it relies on. Framework-free and dependency-free.
+ */
+export { chooseInk, compositeOver, contrastRatio, DECK_SCRIM_MAX, DECK_SCRIM_STEP, DECK_TEXT_CONTRAST_MIN, inkWithScrim, normalizeHex, opaqueColor, PURE_DARK, PURE_LIGHT, parseHexColor, relativeLuminance, sampleGradient, scrimStepFor, toHex, worstContrast, } from "./contrast.js";
+export { DECK_BG_VAR_PREFIX, resolveDeckBackground, } from "./resolve.js";
+export { BACKGROUND_CODES, DECK_BACKGROUND_PRESET_IDS, DECK_BACKGROUND_PRESETS, DECK_GRADIENT_ANGLE, DECK_GRADIENT_IDS, DECK_GRADIENTS, DECK_MEDIA_FITS, DECK_MEDIA_POSITIONS, DECK_MEDIA_TONES, DECK_PALETTE_ROLES, DECK_PATTERNS, DECK_SOLID_TOKENS, DEFAULT_DECK_BACKGROUND, deckBackground, deckBackgroundPreset, deckBackgroundSpec, HEX_COLOR_PATTERN, isDeckBackgroundPreset, } from "./schema.js";

package/dist/model/backgrounds/resolve.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Resolve a background against a palette into paint layers, a text tone and
+ * `--tx-deck-bg-*` CSS variables, with the body-text guarantee: the text
+ * color reaches WCAG AA (4.5:1) over everything behind it. Gradients are
+ * checked at their stops and 15 points between each pair, patterns on their
+ * base and their lines, media at the worst possible pixel (pure black and
+ * pure white). When the background alone is not enough, a scrim (black under
+ * light text, white under dark text) is added at the lowest alpha in 0.05
+ * steps, up to 0.9, that works; an author `overlay` only ever raises it.
+ *
+ * Pure and deterministic. It never throws: an invalid background or an
+ * unreadable palette color is reported in `issues` and replaced by a
+ * documented fallback.
+ */
+import { type DeckDiagnostic, type PathSegment } from '../../schema/index.js';
+import { type TextTone } from './contrast.js';
+import { type DeckBackgroundKind, type DeckBackgroundPalette, type DeckBackgroundPresetId, type DeckPattern } from './schema.js';
+/** Every CSS variable a background sets starts with this prefix. */
+export declare const DECK_BG_VAR_PREFIX = "--tx-deck-bg-";
+export type DeckBackgroundCssVar = `--tx-deck-bg-${string}`;
+/** One paint layer, bottom to top. Colors are always computed `#rrggbb`. */
+export type DeckBackgroundLayer = {
+    type: 'color';
+    color: string;
+} | {
+    type: 'gradient';
+    angle: number;
+    stops: string[];
+} | {
+    type: 'pattern';
+    pattern: DeckPattern;
+    color: string;
+    ink: string;
+} | {
+    type: 'media';
+    media: 'image' | 'video';
+    /** Syntax-checked only: the stage applies the URL policy at the host tier. */
+    src: string;
+    full: boolean;
+    fit: 'cover' | 'contain';
+    position: 'center' | 'top' | 'bottom' | 'left' | 'right';
+    alt?: string;
+    poster?: string;
+    /** Background video is always muted, looping, inline and without controls. */
+    muted?: true;
+    autoplay?: true;
+    loop?: true;
+    playsInline?: true;
+} | {
+    type: 'scrim';
+    color: string;
+    alpha: number;
+};
+export interface ResolvedDeckBackground {
+    kind: DeckBackgroundKind;
+    /** The preset id, when the background came from one (or fell back to the default). */
+    preset?: DeckBackgroundPresetId;
+    /** Bottom to top: a base color, then the gradient, pattern or media, then the scrim. */
+    layers: DeckBackgroundLayer[];
+    /** `light` text on dark backgrounds, `dark` text on light ones. */
+    textTone: TextTone;
+    textColor: string;
+    /** Scrim alpha: 0 to 0.9 in 0.05 steps (0 means none is painted). */
+    scrim: number;
+    /** Black under light text, white under dark text. */
+    scrimColor: string;
+    /** Worst-case contrast of `textColor` over the background and scrim, ≥ 4.5 (floored to 0.01). */
+    contrast: number;
+    /** `--tx-deck-bg-*` variables built only from computed colors, numbers and enum keywords. */
+    cssVars: Record<DeckBackgroundCssVar, string>;
+    /** Recovered problems (invalid background, unreadable palette colors). */
+    issues: DeckDiagnostic[];
+}
+export interface ResolveDeckBackgroundOptions {
+    /** Raise the body-text floor (values below 4.5 are ignored). */
+    minimumContrast?: number;
+    /** A prefix for issue paths, e.g. `['slides', 2, 'background']`. */
+    path?: readonly PathSegment[];
+    slideId?: string;
+}
+/**
+ * Resolve `background` (a preset id, a spec, or `undefined` for the default
+ * `solid-color`) against `palette` (semantic role → hex, see
+ * `DeckBackgroundPalette`).
+ */
+export declare function resolveDeckBackground(background: unknown, palette: DeckBackgroundPalette, options?: ResolveDeckBackgroundOptions): ResolvedDeckBackground;

package/dist/model/backgrounds/resolve.js

@@ -0,0 +1,215 @@
+/**
+ * Resolve a background against a palette into paint layers, a text tone and
+ * `--tx-deck-bg-*` CSS variables, with the body-text guarantee: the text
+ * color reaches WCAG AA (4.5:1) over everything behind it. Gradients are
+ * checked at their stops and 15 points between each pair, patterns on their
+ * base and their lines, media at the worst possible pixel (pure black and
+ * pure white). When the background alone is not enough, a scrim (black under
+ * light text, white under dark text) is added at the lowest alpha in 0.05
+ * steps, up to 0.9, that works; an author `overlay` only ever raises it.
+ *
+ * Pure and deterministic. It never throws: an invalid background or an
+ * unreadable palette color is reported in `issues` and replaced by a
+ * documented fallback.
+ */
+import { createDiagnostic, validate, } from "../../schema/index.js";
+import { chooseInk, compositeOver, DECK_TEXT_CONTRAST_MIN, opaqueColor, PURE_DARK, PURE_LIGHT, relativeLuminance, sampleGradient, } from "./contrast.js";
+import { BACKGROUND_CODES, DECK_BACKGROUND_PRESETS, DECK_GRADIENT_ANGLE, DECK_GRADIENTS, DECK_PALETTE_ROLES, DEFAULT_DECK_BACKGROUND, deckBackground, isDeckBackgroundPreset, } from "./schema.js";
+/** Every CSS variable a background sets starts with this prefix. */
+export const DECK_BG_VAR_PREFIX = '--tx-deck-bg-';
+/** Any pixel of an image or video: the scrim must hold against both extremes. */
+const ANY_PIXEL = [PURE_DARK, PURE_LIGHT];
+/** Points per gradient segment the guarantee is checked at. */
+const GRADIENT_SAMPLES = 16;
+/** Fade steps between the background (0) and the border (full strength) for pattern lines. */
+const PATTERN_INK_STEPS = 20;
+function normalizePalette(input, issues, options) {
+    const where = (role) => [...(options.path ?? []), 'palette', role];
+    const raw = (role) => input !== null && typeof input === 'object' && Object.hasOwn(input, role)
+        ? input[role]
+        : undefined;
+    const bad = (role, fallback) => {
+        issues.push(createDiagnostic(BACKGROUND_CODES.invalidPaletteColor, `Palette role "${role}" is not a hex or rgb() color; using ${fallback}.`, where(role), { severity: 'warning', fix: 'Pass the role as #rrggbb.', slideId: options.slideId }));
+    };
+    let background = opaqueColor(raw('background'), PURE_LIGHT);
+    if (!background) {
+        background = PURE_LIGHT;
+        bad('background', background);
+    }
+    const out = { background };
+    for (const role of DECK_PALETTE_ROLES) {
+        if (role === 'background')
+            continue;
+        const color = opaqueColor(raw(role), background);
+        if (color)
+            out[role] = color;
+        else {
+            // Foreground falls back to the pure ink that reads on the background; the rest to the background.
+            const fallback = role === 'foreground'
+                ? relativeLuminance(background) > 0.179
+                    ? PURE_DARK
+                    : PURE_LIGHT
+                : background;
+            bad(role, fallback);
+            out[role] = fallback;
+        }
+    }
+    const inverse = raw('inverse');
+    if (inverse === undefined)
+        out.inverse = out.foreground;
+    else {
+        const color = opaqueColor(inverse, background);
+        if (!color)
+            bad('inverse', out.foreground);
+        out.inverse = color ?? out.foreground;
+    }
+    return out;
+}
+/** The theme's text-bearing pair, as the light and the dark ink. */
+function themeInks(palette) {
+    const fg = palette.foreground;
+    const bg = palette.background;
+    return relativeLuminance(fg) >= relativeLuminance(bg)
+        ? { light: fg, dark: bg }
+        : { light: bg, dark: fg };
+}
+/**
+ * The line color of a dot or grid pattern: the theme `border`, faded toward
+ * the base only as far as text stays at AA on the lines without any scrim
+ * (a pattern paints none). Strong 3:1 borders would otherwise be as dark as text.
+ */
+function patternInk(base, border, inks) {
+    for (let step = PATTERN_INK_STEPS; step > 0; step -= 1) {
+        const ink = step === PATTERN_INK_STEPS ? border : compositeOver(base, border, step / PATTERN_INK_STEPS);
+        if (chooseInk([base, ink], inks).scrim === 0)
+            return ink;
+    }
+    return base;
+}
+function solidColor(token, palette) {
+    return palette[token];
+}
+function pickSpec(input, issues, options) {
+    if (input === undefined) {
+        return {
+            spec: DECK_BACKGROUND_PRESETS[DEFAULT_DECK_BACKGROUND],
+            preset: DEFAULT_DECK_BACKGROUND,
+        };
+    }
+    if (isDeckBackgroundPreset(input))
+        return { spec: DECK_BACKGROUND_PRESETS[input], preset: input };
+    const checked = validate(deckBackground, input, { path: options.path ?? [], maxIssues: 20 });
+    if (checked.ok && typeof checked.value === 'object')
+        return { spec: checked.value };
+    for (const issue of checked.issues) {
+        issues.push(options.slideId === undefined ? issue : { ...issue, slideId: options.slideId });
+    }
+    // The validation issues explain the problem; the fallback is documented, not repeated.
+    if (checked.issues.length > 0) {
+        return {
+            spec: DECK_BACKGROUND_PRESETS[DEFAULT_DECK_BACKGROUND],
+            preset: DEFAULT_DECK_BACKGROUND,
+        };
+    }
+    issues.push(createDiagnostic(BACKGROUND_CODES.unknownBackground, `The background is not valid; using ${DEFAULT_DECK_BACKGROUND}.`, options.path ?? [], {
+        fix: `Use a preset id or a background spec (${DEFAULT_DECK_BACKGROUND} is the default).`,
+        slideId: options.slideId,
+    }));
+    return {
+        spec: DECK_BACKGROUND_PRESETS[DEFAULT_DECK_BACKGROUND],
+        preset: DEFAULT_DECK_BACKGROUND,
+    };
+}
+/**
+ * Resolve `background` (a preset id, a spec, or `undefined` for the default
+ * `solid-color`) against `palette` (semantic role → hex, see
+ * `DeckBackgroundPalette`).
+ */
+export function resolveDeckBackground(background, palette, options = {}) {
+    const issues = [];
+    const colors = normalizePalette(palette, issues, options);
+    const { spec, preset } = pickSpec(background, issues, options);
+    const inks = themeInks(colors);
+    const minimum = Math.max(DECK_TEXT_CONTRAST_MIN, options.minimumContrast ?? 0);
+    const layers = [];
+    const cssVars = {};
+    let base;
+    let choice;
+    switch (spec.kind) {
+        case 'solid': {
+            base = spec.color ? spec.color.toLowerCase() : solidColor(spec.token ?? 'background', colors);
+            layers.push({ type: 'color', color: base });
+            choice = chooseInk([base], inks, { minimum });
+            break;
+        }
+        case 'gradient': {
+            const stops = DECK_GRADIENTS[spec.gradient].map((role) => colors[role]);
+            const angle = spec.angle ?? DECK_GRADIENT_ANGLE;
+            base = stops[0];
+            layers.push({ type: 'color', color: base }, { type: 'gradient', angle, stops });
+            choice = chooseInk(sampleGradient(stops, GRADIENT_SAMPLES), inks, { minimum });
+            cssVars['--tx-deck-bg-gradient'] = `linear-gradient(${angle}deg, ${stops.join(', ')})`;
+            break;
+        }
+        case 'pattern': {
+            base = colors.background;
+            const ink = patternInk(base, colors.border, inks);
+            layers.push({ type: 'color', color: base }, { type: 'pattern', pattern: spec.pattern, color: base, ink });
+            choice = chooseInk([base, ink], inks, { minimum });
+            cssVars['--tx-deck-bg-pattern'] = spec.pattern;
+            cssVars['--tx-deck-bg-pattern-ink'] = ink;
+            break;
+        }
+        default: {
+            // image, image-full, video, video-full: light text over a dark scrim unless declared light.
+            const forced = spec.tone === 'light' ? 'dark' : 'light';
+            base = forced === 'light' ? PURE_DARK : PURE_LIGHT;
+            const isVideo = spec.kind === 'video' || spec.kind === 'video-full';
+            const fit = 'fit' in spec && spec.fit ? spec.fit : 'cover';
+            const position = spec.position ?? 'center';
+            layers.push({ type: 'color', color: base }, {
+                type: 'media',
+                media: isVideo ? 'video' : 'image',
+                src: spec.src,
+                full: spec.kind.endsWith('-full'),
+                fit,
+                position,
+                ...('alt' in spec && spec.alt ? { alt: spec.alt } : {}),
+                ...('poster' in spec && spec.poster ? { poster: spec.poster } : {}),
+                ...(isVideo
+                    ? { muted: true, autoplay: true, loop: true, playsInline: true }
+                    : {}),
+            });
+            choice = chooseInk(ANY_PIXEL, inks, {
+                forced,
+                minimumScrim: spec.overlay ?? 0,
+                minimum,
+            });
+            cssVars['--tx-deck-bg-media-fit'] = fit;
+            cssVars['--tx-deck-bg-media-position'] = position;
+            break;
+        }
+    }
+    if (choice.scrim > 0)
+        layers.push({ type: 'scrim', color: choice.scrimColor, alpha: choice.scrim });
+    const ordered = {
+        '--tx-deck-bg-color': base,
+        '--tx-deck-bg-text': choice.ink,
+        '--tx-deck-bg-tone': choice.tone,
+        '--tx-deck-bg-scrim': choice.scrim > 0 ? choice.scrimColor : 'transparent',
+        '--tx-deck-bg-scrim-alpha': String(choice.scrim),
+        ...cssVars,
+    };
+    return {
+        kind: spec.kind,
+        ...(preset ? { preset } : {}),
+        layers,
+        textTone: choice.tone,
+        textColor: choice.ink,
+        scrim: choice.scrim,
+        scrimColor: choice.scrimColor,
+        contrast: Math.floor(choice.contrast * 100) / 100,
+        cssVars: ordered,
+        issues,
+    };
+}