@evolve.ui/theme-system 1.1.0 → 1.2.0

package/src/effects/validate.ts

@@ -0,0 +1,683 @@
+/**
+ * Plain data checks run before a sheet is emitted. One throw lists every problem.
+ */
+import * as cssVars from '../tailwind/cssVars';
+import { effectClasses } from './classes';
+import { effectHooks, freePseudoSlot, rootOf, type EffectHookId, type PseudoSlot, type StateBackground } from './hooks';
+import { materials, type EffectLayer, type EffectMaterial, type EffectRule } from './rules';
+import {
+    effectTokens,
+    tokenOf,
+    type EffectTokenKind,
+    type EffectTokenName,
+    type EffectTokenSpec,
+    type EffectTokenValues,
+} from './tokens';
+
+export class EffectLayerError extends Error {
+    constructor(readonly problems: readonly string[]) {
+        super(`Invalid effect layer:\n- ${problems.join('\n- ')}`);
+        this.name = 'EffectLayerError';
+    }
+}
+
+/** Literal colour syntax. Token values may contain these; rule values never do. */
+const LITERAL_COLOUR = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\(\s*(?!var\()/i;
+
+/** `:disabled` or `[attr]` / `[attr="value"]`. A comma takes at most one ASCII space. Names start with a letter. Quoted values are word characters, spaces, and hyphens. */
+const UNLESS_GRAMMAR =
+    /^(?::disabled|\[[a-z][a-z-]*(?:="[\w -]*")?\])(?:, ?(?::disabled|\[[a-z][a-z-]*(?:="[\w -]*")?\]))*$/;
+
+const CHANNELS = /^(\d{1,3}) (\d{1,3}) (\d{1,3})$/;
+
+/** Channels escape: exactly `var(--name)`. An `--effect-*` name must itself be a channels token. */
+const CHANNEL_VAR = /^var\(--([a-z0-9-]+)\)$/;
+
+const REMAPPABLE_COLOR = /^--color-(text|icon)-/;
+
+const remappableVars = new Set<string>([
+    '--effect-font-accent',
+    ...Object.values(cssVars).filter((value) => typeof value === 'string' && REMAPPABLE_COLOR.test(value)),
+]);
+
+const PAINT_PROPERTIES = new Set([
+    'background',
+    'backgroundColor',
+    'backgroundImage',
+    'backdropFilter',
+    'color',
+    'fontFamily',
+]);
+
+const BACKGROUND_PAINTS = new Set(['background', 'backgroundColor', 'backgroundImage']);
+
+const MATERIAL_PAINTS = ['background', 'backgroundColor', 'backgroundImage', 'backdropFilter'] as const;
+
+/** Only `inset` may be negative. A negative border width or radius is invalid CSS and drops the declaration. */
+const LENGTH_PX = /^-?\d+(\.\d+)?px$/;
+
+const NON_NEGATIVE_PX = /^\d+(\.\d+)?px$/;
+
+const BORDER_STYLES = new Set<string>(['dashed', 'dotted', 'solid']);
+
+const DECORATION_FIELDS = new Set([
+    'inset',
+    'borderRadius',
+    'borderWidth',
+    'borderStyle',
+    'borderColor',
+    'background',
+    'boxShadow',
+]);
+
+type LooseRule = {
+    readonly acknowledge?: unknown;
+    readonly after?: unknown;
+    readonly before?: unknown;
+    readonly material?: unknown;
+    readonly on?: unknown;
+    readonly paint?: unknown;
+    readonly radius?: unknown;
+    readonly shadow?: unknown;
+    readonly unless?: unknown;
+    readonly vars?: unknown;
+    readonly when?: unknown;
+};
+
+type RuleOrigin = 'brand' | 'vocabulary';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const hasOwn = (source: object, key: string): boolean => Object.prototype.hasOwnProperty.call(source, key);
+
+/** An unquoted `url(` is a url-token. Only ASCII spaces may precede the quote; CSS reads any other space as url content. */
+const UNQUOTED_URL = /url\((?! *["'])/i;
+
+/**
+ * `var(` must be followed by a custom-property name and then `,` or `)`.
+ * Anything else (`var()`, `var(--a b)`, `var(--a.b)`) is dropped at parse time and the token becomes guaranteed-invalid.
+ */
+const VAR_CALL = /var\(/gi;
+const VAR_SHAPE = /var\( *--[\w-]+ *[,)]/iy;
+
+/** Functions a colour, gradient, shadow, filter, or font value needs. `env()`, `attr()`, and `if()` are not among them. */
+const ALLOWED_FUNCTIONS = new Set([
+    'blur',
+    'brightness',
+    'calc',
+    'clamp',
+    'color',
+    'color-mix',
+    'conic-gradient',
+    'contrast',
+    'drop-shadow',
+    'grayscale',
+    'hsl',
+    'hsla',
+    'hue-rotate',
+    'hwb',
+    'invert',
+    'lab',
+    'lch',
+    'linear-gradient',
+    'max',
+    'min',
+    'oklab',
+    'oklch',
+    'opacity',
+    'radial-gradient',
+    'repeating-conic-gradient',
+    'repeating-linear-gradient',
+    'repeating-radial-gradient',
+    'rgb',
+    'rgba',
+    'saturate',
+    'sepia',
+    'url',
+    'var',
+]);
+
+/**
+ * A token is consumed through `var()` by enforced declarations. A CSS-wide keyword there is invalid at computed-value
+ * time, so the consumer falls back to `unset` and wipes the host's own paint. Decorations may still say `inherit`.
+ */
+const CSS_WIDE_KEYWORD = /(?<![\w-])(?:initial|inherit|unset|revert|revert-layer)(?![\w-])/i;
+
+const QUOTED = /"[^"]*"|'[^']*'/g;
+
+const hasMalformedVar = (value: string): boolean =>
+    [...value.matchAll(VAR_CALL)].some((match) => {
+        VAR_SHAPE.lastIndex = match.index;
+        return !VAR_SHAPE.test(value);
+    });
+
+/**
+ * One CSS declaration value. Code points below U+0020, U+007F, and `\` are rejected anywhere.
+ * Outside quotes, `;` `{` `}` `!`, comments, and functions outside `ALLOWED_FUNCTIONS` are rejected.
+ * `url(` must be quoted and `var(` must name a custom property followed by `,` or `)`.
+ * `(` and `[` share a stack: a closer must match the opener, and the stack must end empty.
+ * A value that trims to nothing is rejected. Quoted strings may contain `;`.
+ */
+const isSingleValue = (value: string): boolean => {
+    if (value.trim() === '' || UNQUOTED_URL.test(value) || hasMalformedVar(value)) {
+        return false;
+    }
+    const stack: Array<'(' | '['> = [];
+    let quote: '"' | "'" | undefined;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index] ?? '';
+        const code = char.charCodeAt(0);
+        if (code < 0x20 || code === 0x7f || char === '\\') {
+            return false;
+        }
+        if (quote !== undefined) {
+            if (char === quote) {
+                quote = undefined;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === ';' || char === '{' || char === '}' || char === '!') {
+            return false;
+        }
+        const next = value[index + 1];
+        if ((char === '/' && next === '*') || (char === '*' && next === '/')) {
+            return false;
+        }
+        if (char === '(') {
+            let start = index;
+            while (start > 0 && /[\w-]/.test(value[start - 1] ?? '')) {
+                start -= 1;
+            }
+            const name = value.slice(start, index).toLowerCase();
+            if (name !== '' && !ALLOWED_FUNCTIONS.has(name)) {
+                return false;
+            }
+        }
+        if (char === '(' || char === '[') {
+            stack.push(char);
+            continue;
+        }
+        if (char === ')' || char === ']') {
+            const open = stack.pop();
+            if (char === ')' ? open !== '(' : open !== '[') {
+                return false;
+            }
+        }
+    }
+    return quote === undefined && stack.length === 0;
+};
+
+const isHookId = (value: unknown): value is EffectHookId => typeof value === 'string' && hasOwn(effectHooks, value);
+
+const isEffectClassName = (value: unknown): boolean =>
+    typeof value === 'string' && (Object.values(effectClasses) as readonly string[]).includes(value);
+
+const isMaterial = (value: unknown): value is EffectMaterial =>
+    value === 'surface' || value === 'raised' || value === 'scrim';
+
+const isStateBackground = (value: unknown): value is StateBackground =>
+    value === 'hover' || value === 'active' || value === 'focus-within';
+
+const tokenKind = (name: string): EffectTokenKind | undefined =>
+    hasOwn(effectTokens, name) ? effectTokens[name as EffectTokenName].kind : undefined;
+
+const readValue = (source: object, key: string): unknown => {
+    if (!Object.prototype.hasOwnProperty.call(source, key)) {
+        return undefined;
+    }
+    return Reflect.get(source, key) as unknown;
+};
+
+const expectRef = (value: unknown, kind: EffectTokenKind, label: string, index: number, problems: string[]): void => {
+    if (typeof value !== 'string') {
+        problems.push(`rules[${index}] ${label} must be a token ref`);
+        return;
+    }
+    if (LITERAL_COLOUR.test(value)) {
+        problems.push(`rules[${index}] ${label} contains a literal colour`);
+        return;
+    }
+    const name = tokenOf(value);
+    if (name === undefined) {
+        const shaped = /^var\(--effect-([a-z0-9-]+)\)$/.exec(value);
+        problems.push(
+            shaped === null
+                ? `rules[${index}] ${label} must be exactly one effect token`
+                : `rules[${index}] ${label} unknown effect token ${value}`
+        );
+        return;
+    }
+    if (effectTokens[name].kind !== kind) {
+        problems.push(`rules[${index}] ${label} must be a ${kind} token`);
+    }
+};
+
+const paintKind = (property: string): EffectTokenKind => {
+    if (property === 'fontFamily') {
+        return 'font';
+    }
+    if (property === 'backdropFilter') {
+        return 'filter';
+    }
+    return 'paint';
+};
+
+const enforcesBackground = (rule: LooseRule): boolean => {
+    if (isMaterial(rule.material)) {
+        return true;
+    }
+    if (!isRecord(rule.paint)) {
+        return false;
+    }
+    return Object.keys(rule.paint).some((key) => BACKGROUND_PAINTS.has(key));
+};
+
+const hasEdge = (rule: LooseRule): boolean => isMaterial(rule.material) && materials[rule.material].edge;
+
+const takenOf = (on: string): readonly PseudoSlot[] =>
+    isHookId(on) ? (effectHooks[on] as { taken: readonly PseudoSlot[] }).taken : [];
+
+const collectTokenProblems = (tokens: EffectTokenValues): string[] => {
+    const problems: string[] = [];
+    for (const key of Object.keys(tokens)) {
+        if (!hasOwn(effectTokens, key)) {
+            problems.push(`unknown token ${key}`);
+        }
+    }
+    for (const [key, spec] of Object.entries(effectTokens) as [EffectTokenName, EffectTokenSpec][]) {
+        const value = readValue(tokens, key);
+        if (value === undefined) {
+            if (spec.default === undefined) {
+                problems.push(`missing required token ${key}`);
+            }
+            continue;
+        }
+        if (typeof value !== 'string') {
+            problems.push(`token ${key} must be a string`);
+            continue;
+        }
+        if (!isSingleValue(value)) {
+            problems.push(`token ${key} must be a single CSS value`);
+            continue;
+        }
+        if (CSS_WIDE_KEYWORD.test(value.replace(QUOTED, '""'))) {
+            problems.push(`token ${key} must not use a CSS-wide keyword`);
+            continue;
+        }
+        if (spec.kind === 'channels' && !isChannels(value)) {
+            problems.push(`token ${key} must be R G B channels`);
+        }
+    }
+    return [...problems, ...collectReferenceProblems(tokens)];
+};
+
+const isChannels = (value: string): boolean => {
+    const channels = CHANNELS.exec(value);
+    if (channels !== null) {
+        return channels.slice(1).every((channel) => Number(channel) <= 255);
+    }
+    const name = CHANNEL_VAR.exec(value)?.[1];
+    if (name === undefined) {
+        return false;
+    }
+    return !name.startsWith('effect-') || tokenKind(name.slice('effect-'.length)) === 'channels';
+};
+
+const EFFECT_REF = /var\( *--effect-([\w-]+)/gi;
+
+const referencesOf = (value: string): string[] => [...value.matchAll(EFFECT_REF)].map((match) => match[1] ?? '');
+
+/**
+ * `var(--effect-*)` references must name a known token and must not form a cycle.
+ * Two graphs are checked: the token block as written, and the fallback block, where every token with an `opaque`
+ * target is replaced by a reference to that target (`none` has no reference). A cycle in either makes every token on
+ * it guaranteed-invalid, and the fallback cycle only shows when a user has asked for less transparency.
+ */
+const collectReferenceProblems = (tokens: EffectTokenValues): string[] => {
+    const problems: string[] = [];
+    const written = new Map<string, string[]>();
+    for (const [key, spec] of Object.entries(effectTokens) as [EffectTokenName, EffectTokenSpec][]) {
+        const value = readValue(tokens, key) ?? spec.default;
+        const references = typeof value === 'string' ? referencesOf(value) : [];
+        for (const reference of references) {
+            if (!hasOwn(effectTokens, reference)) {
+                problems.push(`token ${key} references unknown token --effect-${reference}`);
+            }
+        }
+        written.set(
+            key,
+            references.filter((reference) => hasOwn(effectTokens, reference))
+        );
+    }
+    const fallback = new Map(written);
+    for (const [key, spec] of Object.entries(effectTokens) as [EffectTokenName, EffectTokenSpec][]) {
+        if (spec.opaque !== undefined) {
+            fallback.set(key, spec.opaque === 'none' ? [] : [spec.opaque]);
+        }
+    }
+    for (const [label, graph] of [
+        ['', written],
+        [' in the opaque fallback', fallback],
+    ] as const) {
+        const cycle = findCycle(graph);
+        if (cycle !== undefined) {
+            problems.push(`tokens form a var() cycle${label}: ${cycle.join(' -> ')}`);
+        }
+    }
+    return problems;
+};
+
+const findCycle = (graph: ReadonlyMap<string, readonly string[]>): string[] | undefined => {
+    const state = new Map<string, 'visiting' | 'done'>();
+    const path: string[] = [];
+    const visit = (node: string): string[] | undefined => {
+        if (state.get(node) === 'done') {
+            return undefined;
+        }
+        if (state.get(node) === 'visiting') {
+            return [...path.slice(path.indexOf(node)), node];
+        }
+        state.set(node, 'visiting');
+        path.push(node);
+        for (const next of graph.get(node) ?? []) {
+            const cycle = visit(next);
+            if (cycle !== undefined) {
+                return cycle;
+            }
+        }
+        path.pop();
+        state.set(node, 'done');
+        return undefined;
+    };
+    for (const node of graph.keys()) {
+        const cycle = visit(node);
+        if (cycle !== undefined) {
+            return cycle;
+        }
+    }
+    return undefined;
+};
+
+type ElementClaim = {
+    readonly element: string;
+    readonly index: number;
+    readonly on: string;
+    readonly slot: PseudoSlot;
+};
+
+const isExclusive = (first: string, second: string): boolean =>
+    isHookId(first) &&
+    ((effectHooks[first] as { exclusiveWith?: readonly string[] }).exclusiveWith ?? []).includes(second);
+
+/**
+ * The element a rule styles. A state hook shares its root's element when one host extends the other
+ * (`listFileCard.selected`, `dropzone.disabled`); `modal.backdrop` is a different element from `modal`.
+ */
+const elementOf = (on: string): string => {
+    if (!isHookId(on)) {
+        return on;
+    }
+    const root = rootOf(on);
+    if (!isHookId(root)) {
+        return root;
+    }
+    const rootHost: string = effectHooks[root].host;
+    const host: string = effectHooks[on].host;
+    return rootHost.startsWith(host) || host.startsWith(rootHost) ? root : on;
+};
+
+const collectRuleProblems = (rules: readonly EffectRule[], origin: RuleOrigin): string[] => {
+    const loose = rules as readonly LooseRule[];
+    const problems: string[] = [];
+    const claims: { index: number; on: string; slot: PseudoSlot }[] = [];
+    const edges: ElementClaim[] = [];
+    const decorations: ElementClaim[] = [];
+
+    loose.forEach((rule, index) => {
+        const on = typeof rule.on === 'string' ? rule.on : undefined;
+        const hook = on !== undefined && isHookId(on);
+        const optIn = on !== undefined && isEffectClassName(on);
+
+        if (on === undefined || (!hook && !optIn)) {
+            problems.push(`rules[${index}] unknown hook ${String(rule.on)}`);
+        } else if (origin === 'brand' && optIn) {
+            problems.push(`rules[${index}] brand rules cannot target opt-in class ${on}`);
+        }
+
+        if (rule.when !== undefined && rule.when !== 'hover' && rule.when !== 'active') {
+            problems.push(`rules[${index}] when must be hover or active`);
+        }
+        if (rule.unless !== undefined && (typeof rule.unless !== 'string' || !UNLESS_GRAMMAR.test(rule.unless))) {
+            problems.push(`rules[${index}] unless must be :disabled or attribute selectors`);
+        }
+        if (
+            rule.acknowledge !== undefined &&
+            (!Array.isArray(rule.acknowledge) || rule.acknowledge.some((entry) => !isStateBackground(entry)))
+        ) {
+            problems.push(`rules[${index}] acknowledge must be hover, active, or focus-within`);
+        }
+        if (rule.material !== undefined && !isMaterial(rule.material)) {
+            problems.push(`rules[${index}] unknown material ${String(rule.material)}`);
+        }
+        if (rule.shadow !== undefined && tokenKind(typeof rule.shadow === 'string' ? rule.shadow : '') !== 'shadow') {
+            problems.push(`rules[${index}] shadow must name a shadow token`);
+        }
+        if (rule.radius !== undefined && tokenKind(typeof rule.radius === 'string' ? rule.radius : '') !== 'length') {
+            problems.push(`rules[${index}] radius must name a length token`);
+        }
+
+        if (rule.paint !== undefined) {
+            if (!isRecord(rule.paint)) {
+                problems.push(`rules[${index}] paint must be an object`);
+            } else {
+                for (const [key, value] of Object.entries(rule.paint)) {
+                    if (!PAINT_PROPERTIES.has(key)) {
+                        problems.push(`rules[${index}] paint property ${key} is not allowed`);
+                        continue;
+                    }
+                    if (typeof value === 'string' && !isSingleValue(value)) {
+                        problems.push(`rules[${index}] paint.${key} must be a single CSS value`);
+                        continue;
+                    }
+                    expectRef(value, paintKind(key), `paint.${key}`, index, problems);
+                }
+            }
+        }
+
+        if (rule.material !== undefined && rule.shadow !== undefined && isMaterial(rule.material)) {
+            if (materials[rule.material].shadow !== null) {
+                problems.push(`rules[${index}] material ${rule.material} already sets box-shadow; drop shadow`);
+            }
+        }
+
+        if (rule.material !== undefined && isRecord(rule.paint)) {
+            for (const key of MATERIAL_PAINTS) {
+                if (rule.paint[key] !== undefined) {
+                    problems.push(`rules[${index}] material cannot combine with paint.${key}`);
+                }
+            }
+        }
+
+        if (rule.vars !== undefined) {
+            if (!isRecord(rule.vars)) {
+                problems.push(`rules[${index}] vars must be an object`);
+            } else {
+                for (const [key, value] of Object.entries(rule.vars)) {
+                    if (!remappableVars.has(key)) {
+                        problems.push(`rules[${index}] vars key ${key} is not remappable`);
+                        continue;
+                    }
+                    if (typeof value === 'string' && !isSingleValue(value)) {
+                        problems.push(`rules[${index}] vars ${key} must be a single CSS value`);
+                        continue;
+                    }
+                    if (key === '--effect-font-accent') {
+                        expectRef(value, 'font', `vars ${key}`, index, problems);
+                    } else {
+                        expectRef(value, 'channels', `vars ${key}`, index, problems);
+                    }
+                }
+            }
+        }
+
+        for (const slot of ['before', 'after'] as const) {
+            const decoration = rule[slot];
+            if (decoration === undefined) {
+                continue;
+            }
+            if (!isRecord(decoration)) {
+                problems.push(`rules[${index}] ${slot} must be a decoration`);
+                continue;
+            }
+            for (const [key, value] of Object.entries(decoration)) {
+                if (!DECORATION_FIELDS.has(key)) {
+                    problems.push(`rules[${index}] ${slot} property ${key} is not allowed`);
+                }
+                if (typeof value !== 'string' || !isSingleValue(value)) {
+                    problems.push(`rules[${index}] ${slot}.${key} must be a single CSS value`);
+                    continue;
+                }
+                if (!DECORATION_FIELDS.has(key)) {
+                    continue;
+                }
+                if (key === 'inset' && !LENGTH_PX.test(value)) {
+                    problems.push(`rules[${index}] ${slot}.inset must be a px length`);
+                } else if (key === 'borderWidth' && !NON_NEGATIVE_PX.test(value)) {
+                    problems.push(`rules[${index}] ${slot}.borderWidth must be a non-negative px length`);
+                } else if (key === 'borderRadius' && value !== 'inherit' && !NON_NEGATIVE_PX.test(value)) {
+                    problems.push(`rules[${index}] ${slot}.borderRadius must be a non-negative px length or inherit`);
+                } else if (key === 'borderStyle' && !BORDER_STYLES.has(value)) {
+                    problems.push(`rules[${index}] ${slot}.borderStyle must be dashed, dotted, or solid`);
+                } else if (key === 'borderColor' || key === 'background') {
+                    expectRef(value, 'paint', `${slot}.${key}`, index, problems);
+                } else if (key === 'boxShadow') {
+                    expectRef(value, 'shadow', `${slot}.${key}`, index, problems);
+                }
+            }
+        }
+
+        if (on === undefined) {
+            return;
+        }
+        const taken = takenOf(on);
+        if (rule.before !== undefined && taken.includes('before')) {
+            problems.push(`rules[${index}] decoration uses taken slot before`);
+        }
+        if (rule.after !== undefined && taken.includes('after')) {
+            problems.push(`rules[${index}] decoration uses taken slot after`);
+        }
+
+        const element = elementOf(on);
+        for (const slot of ['before', 'after'] as const) {
+            if (rule[slot] !== undefined && !taken.includes(slot)) {
+                decorations.push({ element, index, on, slot });
+            }
+        }
+
+        if (rule.when !== undefined) {
+            return;
+        }
+        if (hasEdge(rule)) {
+            const slot = freePseudoSlot(taken);
+            if (slot === undefined) {
+                problems.push(`rules[${index}] edge needs a free slot`);
+            } else {
+                const decorated =
+                    (slot === 'before' && rule.before !== undefined) || (slot === 'after' && rule.after !== undefined);
+                if (decorated) {
+                    problems.push(`rules[${index}] edge and decoration claim ${slot}`);
+                }
+                claims.push({ index, on, slot });
+                edges.push({ element, index, on, slot });
+            }
+        }
+        if (rule.before !== undefined && !taken.includes('before')) {
+            claims.push({ index, on, slot: 'before' });
+        }
+        if (rule.after !== undefined && !taken.includes('after')) {
+            claims.push({ index, on, slot: 'after' });
+        }
+
+        if (isHookId(on) && enforcesBackground(rule)) {
+            const backgrounds = effectHooks[on].stateBackgrounds;
+            for (const state of backgrounds) {
+                const acknowledged = Array.isArray(rule.acknowledge) && rule.acknowledge.includes(state);
+                const covered =
+                    state !== 'focus-within' &&
+                    loose.some((other, otherIndex) => otherIndex > index && other.when === state && other.on === on);
+                if (!acknowledged && !covered) {
+                    problems.push(`rules[${index}] flattens ${state} on ${on}; cover it with when or acknowledge`);
+                }
+            }
+        }
+    });
+
+    const grouped = new Map<string, number[]>();
+    for (const claim of claims) {
+        const key = `${claim.on}\0${claim.slot}`;
+        const indices = grouped.get(key) ?? [];
+        indices.push(claim.index);
+        grouped.set(key, indices);
+    }
+    for (const [key, indices] of grouped) {
+        const unique = [...new Set(indices)];
+        if (unique.length < 2) {
+            continue;
+        }
+        const slot = key.split('\0')[1];
+        const target = key.split('\0')[0];
+        problems.push(`rules[${unique.join(', ')}] claim the same ${slot} slot on ${target}`);
+    }
+
+    // A state hook or a `when` rule styles the same element as its root, so its decoration would merge with the
+    // root's masked edge (padding, mask, edge background) instead of replacing it.
+    for (const decoration of decorations) {
+        const edge = edges.find(
+            (other) =>
+                other.index !== decoration.index &&
+                other.element === decoration.element &&
+                other.slot === decoration.slot &&
+                !isExclusive(other.on, decoration.on)
+        );
+        if (edge !== undefined) {
+            problems.push(
+                `rules[${decoration.index}] decorates ${decoration.slot} on ${decoration.element}, where rules[${edge.index}] paints the edge`
+            );
+        }
+    }
+
+    loose.forEach((rule, index) => {
+        if (!isHookId(rule.on) || !rule.on.includes('.')) {
+            return;
+        }
+        const root = rootOf(rule.on);
+        if (!isHookId(root)) {
+            return;
+        }
+        const laterRoot = loose.findIndex((other, otherIndex) => otherIndex > index && other.on === root);
+        if (laterRoot !== -1) {
+            problems.push(`rules[${index}] state rule must come after rules for ${root}`);
+        }
+    });
+
+    return problems;
+};
+
+const throwIf = (problems: readonly string[]): void => {
+    if (problems.length > 0) {
+        throw new EffectLayerError(problems);
+    }
+};
+
+export const validateEffectLayer = (layer: EffectLayer): void => {
+    throwIf([...collectTokenProblems(layer.tokens), ...collectRuleProblems(layer.rules, 'brand')]);
+};
+
+export const validateRules = (rules: readonly EffectRule[], origin: RuleOrigin): void => {
+    throwIf(collectRuleProblems(rules, origin));
+};