"version": "1.5.0",

import { Image } from "astro:assets";

import ValidationAreas from "../../../assets/validation-areas.png";

<Image

src={ValidationAreas}

alt="Console logs showing all three ways elements are flagged as invalid."

loading="eager"

/>

In the example above, the `<title>` element is missing, so capo.js warns that "Expected exactly 1 `<title>` element, found 0".

There are a handful of standardized pragma directives that can be used with the `http-equiv` attribute to change browser behavior. There are even some non-standard directives that browsers still choose support, the most notable being [`origin-trial`](#no-invalid-origin-trials). And there are actually a couple of standardized directives that are non-conforming, meaning that their use is totally discouraged, specifically: `content-language` and `set-cookie`.

:::caution

Contrary to popular belief, `http-equiv` meta tags _are not_ equivalent to HTTP headers. Learn more about why [you probably don't need `http-equiv` meta tags](https://rviscomi.dev/2023/07/you-probably-dont-need-http-equiv-meta-tags/).

:::

Even when using a standardized, supported, and conforming `http-equiv` directive, its `content` attribute value may still be invalid. For example, the `content-type` directive _must_ declare a character encoding of UTF-8. There are some additional restrictions on this directive, specifically the requirements that it be discovered within the first 1024 bytes and it doesn't coincide with the `<meta charset>` element.

Many of these cases are harmless no-ops, but capo.js will validate them and provide a helpful warning message with relevant metadata to help you understand whether it's safe to remove it or if anything needs to be changed for it to work properly.

There are some cases where it's not so harmless:

- `set-cookie` doesn't actually set any cookies, which could lead to broken behavior.

- `content-type` character encoding can be declared too late, which may lead to performance issues.

- `content-security-policy` [breaks](https://issues.chromium.org/issues/40273969) Chrome's preload scanner, which may lead to performance issues.

- `content-security-policy` directives like `frame-ancestors` and `sandbox` are not supported in meta tags and may have been set mistakenly, breaking assumptions about the page's security.

- `description` and similar metadata may have been mistakenly assigned to the `http-equiv` meta attribute instead of the intended `name` attribute, which could break assumptions about the page's SEO.

- `refresh` can reload or redirect the page and is known to cause [accessibility issues](https://www.w3.org/TR/WCAG10-HTML-TECHS/#meta-element).

According to the [W3C specification](https://w3c.github.io/webappsec-csp/#policy-delivery), a Content Security Policy (CSP) can be set as either an HTTP header or a `<meta http-equiv>` tag.

The `default-style` directive indicates which [alternative stylesheet](https://developer.mozilla.org/en-US/docs/Web/CSS/Alternative_style_sheets) should be enabled. While it's completely standard and supported across browsers, [adoption is extremely low](https://rviscomi.dev/2023/07/you-probably-dont-need-http-equiv-meta-tags/#http-equiv-adoption) at only about 1k websites. Of those, about [31%](https://rviscomi.dev/2023/07/you-probably-dont-need-http-equiv-meta-tags/#default-style) are used incorrectly.

To be used correctly, the `content` attribute of the directive must be equal to the `title` value of an alternative stylesheet. capo.js will warn when the title cannot be found and the directive has no effect.

In addition to flagging incorrect usage, capo.js will also discourage using this directive entirely. Setting a preferred stylesheet results in a flash of unstyled content, which could be avoided by using default stylesheets with `@media` rules instead.

The `content-type` directive is an alias for the `charset` meta tag, which declares the document's content encoding. The [HTML spec](https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv-content-type) places strict requirements on how and where this declaration can occur:

- The document cannot have both a `content-type` directive and a `charset` meta tag

- If one does exist, the character encoding declaration must be found within the firsts 1024 bytes of the document

- If one does exist, the character encoding must be set to UTF-8

It's valid for a document not to have either `content-type` nor `charset` meta tags, as long as the `Content-Type` HTTP header is set, also to UTF-8. capo.js does not presently validate HTTP headers, only the contents of the document `<head>`.

capo.js will validate that all three of the requirements above are met, and log a warning if not. If there are redundant character encoding declarations, capo.js will warn on the `content-type` element, giving preference to the `charset` meta tag. If the declaration occurs too late, capo.js will include the byte index for reference. And if the encoding is not set to UTF-8, capo.js will log the actual encoding used.

The `refresh` directive can force the page to reload or redirect after a specified amount of time. This is considered an [accessibility issue](https://www.w3.org/TR/WCAG10-CORE-TECHS/#auto-page-refresh) by the WCAG. It can be disorienting to users for the page to suddenly reload or redirect, and there are more semantic ways to indicate that a page's contents have moved.

capo.js issues a warning whenever a meta `refresh` directive is found. If it contains a redirect, capo.js encourages using HTTP 3xx redirects instead. Otherwise, it encourages including a mechanism for users to disable the auto-reloading behavior, if one is not already provided by browsers.

The [`x-dns-prefetch-control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control) HTTP header and meta directive are non-standard, but widely supported. By default, most browsers will speculatively resolve the DNS records for URLs needed by the page, which is a generally accepted performance optimization.

In Chrome, any value other than `on` will disable the default DNS prefetching behavior. capo.js will always warn when this directive is found, and the message will be unique to the usage. In cases when DNS prefetching is explicitly enabled, capo.js clarifies that this has no effect as it's already the default behavior. In cases where it's set to `off`, capo.js emphasizes the performance benefits of DNS prefetching and clarifies that it should only be disabled when there are legitimate security concerns. For all other values besides `on` and `off`, capo.js warns about using non-standard values and reiterates the performance and security considerations.