@markuplint/types 5.0.0-rc.2 → 5.0.0-rc.5

package/lib/whatwg/check-media-query-list.js

@@ -0,0 +1,484 @@
+import * as csstree from 'css-tree';
+import { cssSyntaxMatch } from '../css-syntax.js';
+import { matched, unmatched } from '../match-result.js';
+import { Token } from '../token/index.js';
+const expects = [
+    {
+        type: 'format',
+        value: 'media query list',
+    },
+];
+/**
+ * Media types defined by Media Queries Level 5 §2.3 as currently active.
+ *
+ * @see https://www.w3.org/TR/mediaqueries-5/#media-types
+ */
+const ACTIVE_MEDIA_TYPES = new Set(['all', 'screen', 'print']);
+/**
+ * Media types that Media Queries Level 5 §2.3 still recognises as syntax
+ * (so user agents must not throw on them) but **must make match nothing**.
+ * Authoring conformance: do not use these.
+ */
+const DEPRECATED_MEDIA_TYPES = new Set([
+    'tty',
+    'tv',
+    'projection',
+    'handheld',
+    'braille',
+    'embossed',
+    'aural',
+    'speech',
+]);
+/**
+ * Media features deprecated since Media Queries Level 4. MDN's `@media`
+ * reference explicitly lists `device-width`, `device-height`, and
+ * `device-aspect-ratio` as deprecated; the `min-` / `max-` prefixed
+ * variants are deprecated as derivatives of the same features (MQL4's
+ * range-feature syntax replaces the explicit prefix forms).
+ *
+ * Note: Media Queries Level 5 Appendix A is the normative location, but
+ * its content was not directly retrievable via WebFetch at the time this
+ * list was authored, so MDN is the verified source.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/@media
+ */
+const DEPRECATED_MEDIA_FEATURES = new Set([
+    'device-width',
+    'min-device-width',
+    'max-device-width',
+    'device-height',
+    'min-device-height',
+    'max-device-height',
+    'device-aspect-ratio',
+    'min-device-aspect-ratio',
+    'max-device-aspect-ratio',
+]);
+/**
+ * Maps each MQL5 §4 range/discrete-numeric feature to the CSS value
+ * type its argument must satisfy. The actual unit / sign / dimension
+ * checking is delegated to `csstree.lexer.match()` below — only the
+ * feature-to-type association needs to live in markuplint because
+ * css-tree does not expose a per-feature value-type registry.
+ *
+ * **How to add a new MQL feature** when the spec extends the catalogue
+ * (e.g., a future Level 6 may add a new resolution or ratio feature):
+ *
+ * 1. Find the feature definition in
+ *    {@link https://www.w3.org/TR/mediaqueries-5/#mq-features Media Queries §4}
+ *    (or its successor) and read its `Value:` line — that's the CSS
+ *    type, expressed as `<length>` / `<integer>` / `<resolution>` /
+ *    `<ratio>` (or a discrete keyword set, which is *not* handled here).
+ * 2. Add an entry to this map. The value must be one of the four
+ *    string literals — keep this list narrow because each new type
+ *    string also needs to be a valid `csstree.lexer.match()` syntax.
+ * 3. If the new feature carries an MQL-side semantic constraint that
+ *    goes beyond CSS Values §6 (e.g., "must be non-negative" beyond
+ *    `<integer>`'s signed grammar, "must be strictly positive" beyond
+ *    `<ratio>`'s `[0,∞]` range), encode it in Stage B of
+ *    `validateFeatureValue()`.
+ * 4. Add table-driven cases in `check-media-query-list.spec.ts` —
+ *    cover at least one valid and one invalid value, plus one case
+ *    that exercises Stage B if applicable.
+ * 5. Discrete keyword features (e.g., `prefers-color-scheme: dark`)
+ *    intentionally fall through this map; they are validated by the
+ *    enum-driven attribute checking elsewhere.
+ *
+ * @see https://www.w3.org/TR/mediaqueries-5/#mq-features
+ */
+const FEATURE_VALUE_TYPE = {
+    // <length>
+    width: '<length>',
+    height: '<length>',
+    'min-width': '<length>',
+    'max-width': '<length>',
+    'min-height': '<length>',
+    'max-height': '<length>',
+    // <integer> — MQL5 §4.4 imposes a non-negative additional constraint
+    // enforced separately below
+    color: '<integer>',
+    'min-color': '<integer>',
+    'max-color': '<integer>',
+    'color-index': '<integer>',
+    'min-color-index': '<integer>',
+    'max-color-index': '<integer>',
+    monochrome: '<integer>',
+    'min-monochrome': '<integer>',
+    'max-monochrome': '<integer>',
+    'horizontal-viewport-segments': '<integer>',
+    'min-horizontal-viewport-segments': '<integer>',
+    'max-horizontal-viewport-segments': '<integer>',
+    'vertical-viewport-segments': '<integer>',
+    'min-vertical-viewport-segments': '<integer>',
+    'max-vertical-viewport-segments': '<integer>',
+    // <resolution>
+    resolution: '<resolution>',
+    'min-resolution': '<resolution>',
+    'max-resolution': '<resolution>',
+    // <ratio> — MQL5 §4.5 imposes a positive additional constraint
+    // enforced separately below
+    'aspect-ratio': '<ratio>',
+    'min-aspect-ratio': '<ratio>',
+    'max-aspect-ratio': '<ratio>',
+};
+/**
+ * Validates a `media` attribute value against the Media Queries Level 5
+ * grammar and authoring constraints.
+ *
+ * Catches three classes of conformance error that nu-validator reports but
+ * `whatwg-mimetype`-style checks do not:
+ *
+ * 1. **Syntax errors** — unbalanced parens, stray semicolons inside `()`,
+ *    unrecognised dimensions. Detected via `css-tree`'s `mediaQueryList`
+ *    parser entry-point.
+ * 2. **Unknown / deprecated media types** — anything outside
+ *    {`all`, `screen`, `print`} (e.g., `alla`, `notscreen`, `projection`).
+ *    Per [Media Queries Level 5 §2.3](https://www.w3.org/TR/mediaqueries-5/#media-types),
+ *    deprecated types are syntactically valid but author conformance
+ *    forbids them.
+ * 3. **Deprecated media features** — `device-width` / `device-height` /
+ *    `device-aspect-ratio` and their min-/max- variants. MDN's `@media`
+ *    reference marks them as
+ *    [deprecated since Media Queries Level 4](https://developer.mozilla.org/en-US/docs/Web/CSS/@media).
+ * 4. **Wrong-type feature values** — `(min-width: 400)` (unitless
+ *    non-zero number for a `<length>` feature), `(min-width: 400dpi)`
+ *    (resolution unit on a length feature), `(color: 1em)` (length
+ *    on an integer feature). The matrix covers length / integer /
+ *    resolution / ratio features per Media Queries Level 5 §4. Unknown
+ *    features are passed through unchanged so forward-compat additions
+ *    do not regress to errors.
+ *
+ * @see https://www.w3.org/TR/mediaqueries-5/
+ */
+export const checkMediaQueryList = () => value => {
+    if (!value) {
+        return unmatched(value, 'empty-token', { expects });
+    }
+    // Stage 1: delegate to the CSS Syntax matcher (the same engine that
+    // `<media-query-list>` used to use). Catches malformed grammar that
+    // the lenient `csstree.parse(..., { context: 'mediaQueryList' })`
+    // silently accepts: missing `and` whitespace (`screenand (...)`),
+    // unterminated declarations (`screen and (min-width:`), trailing
+    // combinators (`screen and (...) and`), trailing commas (`screen,`),
+    // whitespace-only values, etc.
+    const syntaxResult = cssSyntaxMatch(value, '<media-query-list>');
+    if (!syntaxResult.matched) {
+        return syntaxResult;
+    }
+    // css-tree silently swallows stray semicolons inside `()` (e.g.,
+    // `(min-width: 400px;)`), but the CSS Syntax tokenizer rule says a
+    // `<semicolon-token>` is invalid inside a `<media-condition>`. Detect
+    // it manually before delegating to css-tree.
+    const semicolon = findSemicolonInsideParens(value);
+    if (semicolon != null) {
+        return new Token(';', semicolon, value).unmatched({
+            reason: 'unexpected-token',
+            expects,
+            partName: 'a stray semicolon inside the media condition',
+        });
+    }
+    // Stage 2: re-parse with the lenient mediaQueryList AST so we can
+    // walk it and reject deprecated/unknown identifiers.
+    let ast;
+    try {
+        ast = csstree.parse(value, { context: 'mediaQueryList', positions: true });
+    }
+    catch (error) {
+        // css-tree's parser raises a JS-builtin `SyntaxError` decorated
+        // with `source` / `offset` / `formattedMessage` for user-input
+        // parse failures (Tier-3 violations). Anything else — programmer-
+        // error fatal errors (`TypeError` / `ReferenceError` / bare
+        // `SyntaxError`) or non-`Error` throws — bubbles up so the three-
+        // tier policy can treat it as Tier-1.
+        if (!isCssTreeParseError(error))
+            throw error;
+        return unmatched(value, 'syntax-error', { expects, partName: error.message });
+    }
+    if (ast.type !== 'MediaQueryList') {
+        return unmatched(value, 'syntax-error', { expects });
+    }
+    for (const query of ast.children ?? []) {
+        if (query.type !== 'MediaQuery')
+            continue;
+        // css-tree's `MediaQuery` runtime nodes carry `mediaType` and
+        // `condition` properties (verified empirically from `csstree.parse`),
+        // but `@types/css-tree` does not surface them. Cast through the
+        // minimal shape we actually consume rather than `any`.
+        const q = query;
+        // Validate the media type identifier (only present when the query
+        // uses `<media-type>` form; condition-only queries skip this check).
+        const mediaType = q.mediaType;
+        if (typeof mediaType === 'string') {
+            const lowered = mediaType.toLowerCase();
+            if (DEPRECATED_MEDIA_TYPES.has(lowered)) {
+                const offset = q.loc?.start.offset ?? 0;
+                return new Token(mediaType, offset, value).unmatched({
+                    reason: 'doesnt-exist-in-enum',
+                    expects,
+                    partName: `deprecated media type "${mediaType}"`,
+                });
+            }
+            if (!ACTIVE_MEDIA_TYPES.has(lowered)) {
+                const offset = q.loc?.start.offset ?? 0;
+                return new Token(mediaType, offset, value).unmatched({
+                    reason: 'doesnt-exist-in-enum',
+                    expects,
+                    candidate: nearestMediaType(lowered),
+                });
+            }
+        }
+        // Walk the condition tree for Feature / MediaFeature nodes and
+        // reject deprecated names. Features the engine doesn't recognise
+        // at all surface as parse errors via the try/catch above.
+        if (q.condition) {
+            const result = walkCondition(q.condition, value);
+            if (result)
+                return result;
+        }
+    }
+    return matched();
+};
+function walkCondition(node, source) {
+    let result = null;
+    csstree.walk(node, child => {
+        if (result)
+            return;
+        // `Feature` / `MediaFeature` are runtime node types emitted by
+        // css-tree's mediaQueryList parser but not exposed by
+        // `@types/css-tree`. Compare via cast to keep the narrow typing.
+        const childType = child.type;
+        // Reject <general-enclosed> fallback matches. Media Queries Level 5 §3
+        // (the <general-enclosed> Production) states: "Authors must not use
+        // <general-enclosed> in their stylesheets. It exists only for
+        // future-compatibility, so that new syntax additions do not invalidate
+        // too much of a <media-condition> in older user agents." css-tree only
+        // emits GeneralEnclosed when the enclosed tokens genuinely fail
+        // <media-feature> grammar (e.g., `(min-width:)` — empty value after
+        // the colon; `(123)` — number token where <ident> is expected).
+        // Well-formed `(<ident>: <value>)` shapes with unknown feature names
+        // still parse as `Feature`, so forward-compatibility for new feature
+        // names is preserved.
+        if (childType === 'GeneralEnclosed') {
+            const offset = child.loc?.start.offset ?? 0;
+            const endOffset = child.loc?.end.offset ?? offset;
+            const raw = source.slice(offset, endOffset);
+            result = new Token(raw, offset, source).unmatched({
+                reason: 'syntax-error',
+                expects,
+                partName: `unknown or malformed media condition ${JSON.stringify(raw)} (Media Queries Level 5 §3 forbids <general-enclosed> in author stylesheets)`,
+            });
+            return;
+        }
+        if (childType !== 'Feature' && childType !== 'MediaFeature')
+            return;
+        const feat = child;
+        const name = feat.name;
+        if (typeof name !== 'string')
+            return;
+        const lowered = name.toLowerCase();
+        if (DEPRECATED_MEDIA_FEATURES.has(lowered)) {
+            const offset = child.loc?.start.offset ?? 0;
+            // Skip the leading `(` so the highlight lands on the feature name.
+            const nameOffset = source.slice(offset).search(/[A-Z]/i);
+            result = new Token(name, offset + Math.max(nameOffset, 0), source).unmatched({
+                reason: 'doesnt-exist-in-enum',
+                expects,
+                partName: `deprecated media feature "${name}"`,
+            });
+            return;
+        }
+        // Boolean form `(name)` carries `value: null` and is type-agnostic.
+        if (!feat.value)
+            return;
+        const typeError = validateFeatureValue(lowered, feat.value, source);
+        if (typeError)
+            result = typeError;
+    });
+    return result;
+}
+/**
+ * Cross-checks a media feature's parsed value against the expected
+ * type per Media Queries Level 5 §4. Returns an `unmatched` result
+ * when the value type does not satisfy the feature's grammar (e.g.,
+ * `<integer>` features given a `<dimension>`, or `<length>` features
+ * given a unitless non-zero number).
+ *
+ * Returns null for:
+ * - Unknown features (treated as forward-compat — defer to css-tree)
+ * - Custom CSS variables / functions / calc() (not statically reducible)
+ *
+ * @see https://www.w3.org/TR/mediaqueries-5/#mq-features
+ */
+function validateFeatureValue(feature, value, source) {
+    const expectedType = FEATURE_VALUE_TYPE[feature];
+    if (!expectedType)
+        return null;
+    // Defer calc()/var()/clamp() — their static value cannot be computed
+    // without resolving cascades. css-tree accepts them; we trust
+    // nu-validator does the same in practice.
+    if (value.type === 'Function' || value.type === 'Parentheses')
+        return null;
+    const offset = value.loc?.start.offset ?? 0;
+    const raw = source.slice(offset, value.loc?.end.offset ?? offset);
+    // Stage A: CSS-syntax conformance — delegate the dimension / unit /
+    // fractional / scientific-notation matrix to `csstree.lexer.match()`
+    // rather than maintain a parallel hardcoded table. css-tree's
+    // `<length>` / `<integer>` / `<resolution>` / `<ratio>` definitions
+    // mirror CSS Values and Units Level 4 §6 and stay in sync as the
+    // language evolves (container query units, viewport-relative
+    // variants, etc.). `error: null` signals a successful match; a
+    // non-null `SyntaxMatchError` describes the mismatch and is included
+    // in the partName so the user sees which unit / dimension failed.
+    // `lexer.match()` *throws* a `SyntaxReferenceError` for unknown
+    // syntax names (e.g., a typo in `FEATURE_VALUE_TYPE`); let it bubble
+    // up as Tier-1 fatal so a programmer error never masquerades as a
+    // user-facing lint violation.
+    const lexerResult = csstree.lexer.match(expectedType, value);
+    if (lexerResult.error) {
+        const detail = lexerResult.error.message?.split('\n')[0] ?? '';
+        return new Token(raw, offset, source).unmatched({
+            reason: 'syntax-error',
+            expects,
+            partName: detail
+                ? `${expectedType} required for "${feature}" (${detail})`
+                : `${expectedType} required for "${feature}"`,
+        });
+    }
+    // Stage B: MQL5 semantic constraints that go beyond CSS Values §6.
+    // Stage A already rejects negative numbers for `<ratio>` (the type's
+    // `<number [0,∞]>` range constraint excludes them), but accepts `0`
+    // as in-range — Stage B adds the strictly-positive constraint from
+    // MQL5 §4.5. Stage A also accepts negative `<integer>` per CSS Values
+    // §6.2 grammar, so MQL5 §4.4's non-negative requirement for
+    // `color` / `monochrome` / `*-viewport-segments` is enforced here.
+    if (expectedType === '<integer>' &&
+        value.type === 'Number' &&
+        Number.parseInt(value.value, 10) < 0) {
+        return new Token(raw, offset, source).unmatched({
+            reason: 'syntax-error',
+            expects,
+            partName: `<integer> for "${feature}" must be non-negative (MQL5 §4.4)`,
+        });
+    }
+    if (expectedType === '<ratio>') {
+        // `@types/css-tree` declares `Ratio.left/.right` as `string`, but the
+        // runtime mediaQueryList parser emits `NumberNode` children — cast
+        // through `unknown` to consume the actual runtime shape.
+        const ratio = value.type === 'Ratio'
+            ? value
+            : null;
+        const numerator = ratio
+            ? Number.parseFloat(ratio.left.value)
+            : value.type === 'Number'
+                ? Number.parseFloat(value.value)
+                : undefined;
+        const denominator = ratio ? Number.parseFloat(ratio.right.value) : 1;
+        if (numerator !== undefined && (!(numerator > 0) || !(denominator > 0))) {
+            return new Token(raw, offset, source).unmatched({
+                reason: 'syntax-error',
+                expects,
+                partName: `<ratio> for "${feature}" must be positive (MQL5 §4.5)`,
+            });
+        }
+    }
+    return null;
+}
+/**
+ * Only used for the "candidate" typo hint shown to the user, not for validation.
+ */
+function nearestMediaType(input) {
+    for (const candidate of ACTIVE_MEDIA_TYPES) {
+        if (input.startsWith(candidate) || candidate.startsWith(input)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Returns the offset of the first `;` that appears inside a balanced `(`
+ * region, or `null` when no such semicolon exists. Used as a pre-parse
+ * guard because css-tree's media-query parser silently absorbs stray
+ * semicolons rather than flagging them.
+ *
+ * Implementation note: Media Queries Level 5 grammar contains no quoted
+ * strings, so a naive paren-depth counter is sufficient — there is no
+ * `"a;b"` literal context to consider. If a future MQ level introduces
+ * quoted-string production this scan would falsely flag the inner `;`
+ * and need a string-aware tokenizer instead.
+ */
+/**
+ * Distinguishes css-tree's user-input parse errors (Tier-3 violations)
+ * from JS-builtin `SyntaxError`s thrown elsewhere (Tier-1 fatal errors like
+ * `JSON.parse('bad')`). css-tree decorates its `SyntaxError` instances
+ * with `source` and `formattedMessage`; the JS builtin does not.
+ */
+function isCssTreeParseError(error) {
+    return (error instanceof SyntaxError &&
+        typeof error.source === 'string' &&
+        typeof error.formattedMessage === 'string');
+}
+function findSemicolonInsideParens(input) {
+    let depth = 0;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (ch === '(')
+            depth++;
+        else if (ch === ')')
+            depth = Math.max(0, depth - 1);
+        else if (ch === ';' && depth > 0)
+            return i;
+    }
+    return null;
+}
+/**
+ * Exists so callers that embed a `<media-condition>` inside a larger grammar
+ * (`<source-size-list>` in `<sizes>`) can enforce the same forbidden-in-authoring
+ * rule that {@link checkMediaQueryList} applies to `<media-query-list>` values.
+ *
+ * @see https://www.w3.org/TR/mediaqueries-5/#general-enclosed — "Authors must
+ * not use `<general-enclosed>` in their stylesheets. It exists only for
+ * future-compatibility, so that new syntax additions do not invalidate too
+ * much of a `<media-condition>` in older user agents."
+ *
+ * Contract:
+ *
+ * - css-tree emits `GeneralEnclosed` only when the enclosed tokens fail
+ *   `<media-feature>` grammar (`(min-width:)` empty value, `(123)` non-ident);
+ *   well-formed `(<ident>: <value>)` shapes parse as `Feature`, so unknown
+ *   feature names keep passing (forward-compatibility).
+ * - Returns `null` on any css-tree parse failure — the enclosing checker owns
+ *   grammar-error reporting. Only a *successful* parse reaching the fallback
+ *   surfaces here.
+ * - Programmer-error throws (`TypeError` etc.) bubble up; only Tier-3 css-tree
+ *   `SyntaxError` shapes are swallowed via `isCssTreeParseError`.
+ *
+ * @param snippet raw parenthesised group extracted from the outer value
+ * @returns first match's `{ raw, offset }` (offset is 0-based within `snippet`
+ *   — callers add their own outer offset when reporting), or `null` if none
+ */
+export function findGeneralEnclosed(snippet) {
+    let ast;
+    try {
+        ast = csstree.parse(snippet, { context: 'mediaQueryList', positions: true });
+    }
+    catch (error) {
+        // css-tree's user-input parse failures (Tier-3) may surface when the
+        // caller hands a snippet that fails media-query grammar even though the
+        // outer grammar accepted it — return null so the outer diagnostic path
+        // owns the reporting. Rethrow anything else (Tier-1 programmer errors
+        // like `TypeError`) rather than silently hiding the bug.
+        if (!isCssTreeParseError(error))
+            throw error;
+        return null;
+    }
+    // `csstree.find` stops on the first match; walking the whole tree is wasted
+    // work once we have a hit. oxlint's `no-array-method-this-argument` mis-
+    // identifies this as an Array-method call because the API happens to be
+    // named `find` — suppress inline.
+    // eslint-disable-next-line unicorn/no-array-method-this-argument
+    const node = csstree.find(ast, child => child.type === 'GeneralEnclosed');
+    if (!node)
+        return null;
+    const offset = node.loc?.start.offset ?? 0;
+    const endOffset = node.loc?.end.offset ?? offset;
+    return { raw: snippet.slice(offset, endOffset), offset };
+}

package/lib/whatwg/check-mime-type.d.ts

@@ -1,9 +1,5 @@
 import type { CustomSyntaxChecker } from '../types.js';
 /**
- * Validates a MIME type string according to the WHATWG MIME Sniffing specification.
- *
- * Optionally restricts to MIME types with no parameters.
- *
  * @see https://mimesniff.spec.whatwg.org/#valid-mime-type
  */
 export declare const checkMIMEType: CustomSyntaxChecker<{

package/lib/whatwg/check-mime-type.js

@@ -9,10 +9,55 @@ const expects = (withoutParameters) => [
     },
 ];
 /**
- * Validates a MIME type string according to the WHATWG MIME Sniffing specification.
- *
- * Optionally restricts to MIME types with no parameters.
+ * [RFC 9110 §5.6.6](https://www.rfc-editor.org/rfc/rfc9110#name-parameters)
+ * requires the closing DQUOTE in `quoted-string`; the
+ * [WHATWG MIME Sniffing](https://mimesniff.spec.whatwg.org/#parse-a-mime-type)
+ * parser tolerates the missing terminator and returns a partial value (so
+ * `MIMEType.parse` cannot surface this conformance error). We do the
+ * structural scan ourselves and run it before invoking the parser.
  *
+ * **Limitation:** the scan assumes the opening DQUOTE immediately follows
+ * the `=` byte. RFC 9110 allows OWS (optional whitespace) around `=`, but
+ * WHATWG MIME Sniffing's tokenizer (and every nu-validator-known input
+ * today) closes that gap. If a future fixture exercises `; charset = "..."`
+ * style spacing, extend this scan to skip OWS before checking for `"`.
+ */
+function findUnterminatedQuotedString(value) {
+    for (let i = 0; i < value.length;) {
+        if (value[i] !== ';') {
+            i++;
+            continue;
+        }
+        i++;
+        while (i < value.length && value[i] !== '=' && value[i] !== ';')
+            i++;
+        if (i >= value.length || value[i] === ';')
+            continue;
+        i++;
+        if (i >= value.length || value[i] !== '"')
+            continue;
+        const start = i;
+        i++;
+        let terminated = false;
+        while (i < value.length) {
+            if (value[i] === '\\') {
+                i += 2;
+                continue;
+            }
+            if (value[i] === '"') {
+                i++;
+                terminated = true;
+                break;
+            }
+            i++;
+        }
+        if (!terminated) {
+            return { offset: start };
+        }
+    }
+    return null;
+}
+/**
  * @see https://mimesniff.spec.whatwg.org/#valid-mime-type
  */
 export const checkMIMEType = options => value => {
@@ -20,6 +65,13 @@ export const checkMIMEType = options => value => {
     if (!value) {
         return unmatched(value, 'empty-token', { expects: expects(withoutParameters) });
     }
+    const unterminated = findUnterminatedQuotedString(value);
+    if (unterminated) {
+        return new Token(value.slice(unterminated.offset), unterminated.offset, value).unmatched({
+            reason: 'syntax-error',
+            expects: expects(withoutParameters),
+        });
+    }
     const mimeType = MIMEType.parse(value);
     if (mimeType) {
         if (value.toLowerCase() === mimeType.essence) {

package/lib/whatwg/check-simple-color.d.ts

@@ -1,9 +1,7 @@
 import type { FormattedPrimitiveTypeCreator } from '../types.js';
 /**
- * Checks whether a string is a valid simple color.
- *
- * A valid simple color is exactly seven characters long:
- * a U+0023 NUMBER SIGN (#) followed by six ASCII hex digits.
+ * Not the same as the CSS `<color>` type — named colors, `rgb()`, `hsl()`,
+ * etc. are all invalid here. Used for `input[type=color]` value validation.
  *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-simple-colour
  */

package/lib/whatwg/check-simple-color.js

@@ -1,8 +1,6 @@
 /**
- * Checks whether a string is a valid simple color.
- *
- * A valid simple color is exactly seven characters long:
- * a U+0023 NUMBER SIGN (#) followed by six ASCII hex digits.
+ * Not the same as the CSS `<color>` type — named colors, `rgb()`, `hsl()`,
+ * etc. are all invalid here. Used for `input[type=color]` value validation.
  *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-simple-colour
  */

package/lib/whatwg/check-url.d.ts

@@ -3,14 +3,22 @@ import type { CustomSyntaxChecker } from '../types.js';
  * Validates a URL string (potentially surrounded by spaces) per the WHATWG
  * URL Standard. Accepts both absolute and relative URLs.
  *
- * Uses `new URL()` for structural parsing and adds strict checks matching
- * the nu-html-checker's galimatias StrictErrorHandler behavior:
- * - Illegal whitespace (tabs, newlines) in URL
- * - Malformed percent-encoding
- * - C0 control characters
- * - URLs that fail `new URL()` parsing (even with a dummy base)
+ * Uses `new URL()` for structural parsing and surfaces the validation errors
+ * that `new URL()` silently accepts but nu-validator (and the URL LS) report.
+ *
+ * Categories caught:
+ *
+ * - **invalid-URL-unit** (forbidden code points, malformed percent-encoding,
+ *   unencoded space, tab/CR/LF)
+ * - **invalid-reverse-solidus** (`\` in a special-scheme URL)
+ * - **special-scheme-missing-following-solidus** (`http:foo`, `file:bar`)
+ *   and `file-scheme-missing-following-solidus` / single-slash variants
+ * - **file-invalid-Windows-drive-letter** (`file:///C|/foo`)
+ * - **invalid-credentials** (`http://user:pass@example.com`)
+ * - **IPv4-non-decimal-part** (`http://192.0x00A80001`, hex/octal host labels)
+ * - any URL that fails `new URL()` parsing (even with a dummy base)
  *
  * @see https://html.spec.whatwg.org/multipage/urls-and-fetching.html#valid-url-potentially-surrounded-by-spaces
- * @see https://url.spec.whatwg.org/#url-code-points
+ * @see https://url.spec.whatwg.org/#url-parsing
  */
 export declare const checkURL: CustomSyntaxChecker;